x-rw-bug-d4

> 品牌名: x-rw 技术 Bug 排查 (D4) — 本文档为 D4 的执行规范与路由表，AI 加载时以本文件为准。

> 来源声明：本 Skill 是对 SkillHub 专家包「Bug 排查」(tech-bug-troubleshooting) 中 5 个方法论 Skill 的
> 二次策展与融合，并补入代码审查、测试生成两项增强。各原始 Skill 的版权归原作者所有，
> 完整来源与许可证说明见 ATTRIBUTION.md。本作品不主张原创方法论著作权，仅做整合、泛化与编排。

核心承诺：修得彻底。修得到位。不引入新 Bug。每次修复都沉淀经验。

何时使用

• 报错了 / 异常 / 崩溃 / 构建失败 / 测试失败
• 功能坏了、行为不对、输出错误
• 控制台有 error/warning（即使功能看起来正常）
• 回归、超时、性能下降
• 关键词：fix bug / debug / not working / error / broken / 排查 / 修 Bug

不适用：新功能开发（用对应开发 skill）、纯代码审查无报错上下文（用 code-review 类 skill）、
性能优化专项（用 performance 类 skill）。

核心哲学

> 随机修 Bug 既浪费时间又制造新 Bug。快速补丁掩盖根本问题。
> 永远先找根本原因，再尝试修复。症状修复 = 失败。

违反流程的字面意思 = 违反流程的精神。时间越紧、越想"快速修一下"，越要走完流程。

十一条铁律（详解见 references/iron-rules.md）

1. R1 根因必须通过 4 关才修：可复现 + 因果 + 可逆 + 机制可解释
2. R2 修前先分类问题层（代码/配置/架构/AI 能力），在根因层修
3. R3 范围必须通过 5 关：调用方 + 契约 + 不变量 + 调用点 + 重复扫描
4. R4 修前追踪影响链（代码→数据→时间→事件）+ 全局扫同模式
5. R5 写码前预测副作用 + 查盲点注册表（references/blind-spots.md）
6. R6 修复后验证「正确且已生效」：跑回归 + 清缓存重启 + 走到修复路径
7. R7 框架/库行为 → 先读源码，绝不只信文档/注释/假设
8. R8 UI Bug 先拿运行时证据（截图+DevTools+复现）再提修复
9. R9 模式匹配（正则/字符串/名称查找）必须检查边界（词边界/锚点/精确）
10. R10 未完成「Bug 摘要+代码审查+知识沉淀+自我反思」不算修完
11. R11 🔒 只修当前 Bug，禁止顺带调整其它地方：发现其它问题只记入沉淀，不顺手修改；超范围改动必须单独提出并与用户确认

工作流总览

Phase 0 分诊      严重度(P0-P3) + 层级(Trivial/Standard/Complex)
Phase 1 证据收集   日志解析 + 稳定复现          → references/log-analysis-snippets.md
Phase 2 根因分析   七步/四阶段/五步法融合        → references/debugger-commands.md, error-patterns.md
Phase 3 范围与预测 5 关 + 盲点检查
Phase 4 修复       最小改动, ≤50 LOC
Phase 5 验证与审查 回归 + 运行时 + 代码审查 + 测试生成 → references/regression-matrix.md, code-review-checklist.md, test-gen-guide.md
Phase 6 沉淀反思   模式提取 + 反思评分            → references/bug-patterns.md, bug-records.md

Phase 0: 分诊（先定严重度与层级，控制流程深度）

Trivial 快速修复（>1 文件或改变行为 → 升级 Standard）：

## Quick Fix
- Bug: [一句话]   Fix: [一行改动]   File: [path:line]
- Test: [如何验证 — lint/test/手动]   Risk: None (隔离, 无行为变化)

references/ 条件触发矩阵（O2 路由权威）

> 目的：将"什么 Bug 走哪条线、调用哪些 references/"显性化。O2 多专家辩论后，依据本矩阵选型 skill 并路由。
> 🔒 强制：O2 选型必须对照本矩阵，不得凭记忆选型；每次调用必须 skill-call 记录走了哪条线。

一、O2 路由决策树

用户描述 Bug
    │
    ▼
Phase 0 分诊 → 严重度(P0-P3) + 层级(Trivial/Standard/Complex)
    │
    ▼
O2 多专家辩论 → Bug 领域分类
    │
    ├─── 通用线（所有 Bug 必走，见下方 Line A）
    │
    ├─── 领域分支（O2 判定 Bug 属于以下领域时追加）
    │    ├─ 后端 Bug        → 追加 backend-patterns.md     (Phase 2)
    │    ├─ 前端 Bug        → 追加 frontend-patterns.md    (Phase 2)
    │    │                   → 追加 visual-regression.md   (Phase 5, 条件)
    │    ├─ 安全漏洞        → 追加 security-patterns.md    (Phase 2)
    │    ├─ 性能瓶颈        → 追加 performance-debug.md    (Phase 2)
    │    ├─ CI/CD 失败      → 追加 ci-cd-failure.md        (Phase 2)
    │    ├─ 依赖冲突        → 追加 dependency-conflict.md  (Phase 2)
    │    └─ 跨进程/系统级   → 追加 system-rca.md           (Phase 2)
    │
    ├─── 条件分支（满足特定条件时追加）
    │    ├─ 需定位引入提交   → 追加 git-bisect.md            (Phase 2)
    │    ├─ 需边界探索       → 追加 property-based-testing.md (Phase 5)
    │    └─ 涉及重构对比     → 追加 diff-testing.md          (Phase 5)
    │
    └─── 严重度裁剪
         ├─ P3 Trivial → 仅走 Line L（快速路径，跳过 Phase 2 深化/Phase 3/Phase 5C-5D）
         ├─ P2 Standard → 走 Line A + 领域分支（跳过增强项 5C-5D 可选）
         └─ P0/P1 Complex → 走 Line A + 全部匹配的领域/条件分支（全量）

二、完整条件触发矩阵（23 个文件）

> 触发类型说明：🔒 强制 = 全量流程必走（P3 Trivial 按裁剪规则）｜🎯 条件 = O2 判定 Bug 领域/特征后追加｜📝 活文件 = 每次修复后增量更新｜📦 按需 = 生成交付物时加载

三、执行路径线（O2 选型后走的具体线路）

> 每条线对应 O2 输出的一组 DAG 任务，G3 按拓扑执行。skill-call 记录中标注走了哪条线。

Line A — 通用全量线（P0/P1 必走）

P1: log-analysis-snippets.md
 → P2: debugger-commands.md + error-patterns.md
 → P3: blind-spots.md
 → P4: iron-rules.md（全程参照）
 → P5: regression-matrix.md + code-review-checklist.md + test-gen-guide.md
 → P6: bug-patterns.md + bug-records.md（增量写入）
 → 收尾: deliverable-templates.md（按需）+ ui-style-guide.md（交付物含 HTML 时）

Line B — 后端 Bug 线

Line A
 + P2 追加: backend-patterns.md

触发信号：API 报错 / DB 异常 / 服务端逻辑错误 / 序列化问题 / 幂等性缺失

Line C — 前端 Bug 线

Line A
 + P2 追加: frontend-patterns.md
 + P5 追加: visual-regression.md（条件：涉及 UI 视觉改动）

触发信号：React Hooks 异常 / 事件不响应 / 样式错乱 / 浏览器兼容性 / DOM 操作错误

Line D — 安全漏洞线

Line A
 + P2 追加: security-patterns.md

触发信号：SQL 注入 / XSS / CSRF / 认证绕过 / 越权访问 / 敏感数据泄露

Line E — 性能瓶颈线

Line A
 + P2 追加: performance-debug.md

触发信号：慢查询 / N+1 查询 / 内存泄漏 / CPU 飙高 / 响应延迟 / 大量 GC

Line F — CI/CD 失败线

Line A
 + P2 追加: ci-cd-failure.md

触发信号：构建失败 / 测试流水线报错 / 部署阶段异常 / 环境配置问题

Line G — 依赖冲突线

Line A
 + P2 追加: dependency-conflict.md

触发信号：版本不兼容 / 包冲突 / 传递依赖问题 / ModuleNotFoundError / NoSuchMethodError

Line H — 系统级 RCA 线

Line A
 + P2 追加: system-rca.md

触发信号：跨进程通信异常 / 浏览器自动化失败 / SSE/WebSocket 断连 / 微服务调用链断裂 / IPC 问题

Line I — 二分定位线（条件追加，可与任意领域线组合）

任意 Line + P2 追加: git-bisect.md

触发信号：Bug 是近期引入但不知道哪个提交 / 回归型 Bug / 需要定位首坏提交

Line J — 边界探索线（条件追加）

Line A + P5 追加: property-based-testing.md

触发信号：输入域广 / 边界 case 多 / 需要系统性探索参数空间

Line K — 重构对比线（条件追加）

Line A + P5 追加: diff-testing.md

触发信号：Bug 修复涉及重构 / 需要验证重构前后行为一致性

Line L — P3 快速修复线（Trivial 专用）

P1: log-analysis-snippets.md（轻量）
 → P4: iron-rules.md（参照）
 → P6: bug-patterns.md + bug-records.md（增量写入）
 → 收尾: deliverable-templates.md（按需）

> 跳过 Phase 2 根因深化、Phase 3 范围预测、Phase 5C 代码审查、Phase 5D 测试生成。
> 若修复 >1 文件或改变行为 → 自动升级 Standard，改走 Line A + 领域分支。

四、组合规则

1. 领域线可叠加：一个 Bug 可同时属于多个领域（如"前端性能瓶颈"= Line C + Line E），O2 追加所有匹配的 references
2. 条件线可叠加：任何领域线都可追加条件线（如"后端安全漏洞需二分定位"= Line B + Line D + Line I）
3. P3 裁剪优先：P3 Trivial 只走 Line L，不走领域分支；升级后重新按 Standard 走线
4. P2 可选增强：P2 Standard 的 Phase 5C/5D（代码审查/测试生成）为可选，O2 根据 Bug 复杂度决定
5. 🔒 skill-call 强制记录：每次调用 references/ skill 时，必须在 debug.db 记录走了哪条 Line、在哪个 Phase、调用原因

启动门禁（Entry Gate，🔒 100% 强制执行）

> 目的：确保"O2 接管预处理、.debug/ 输出、debug.db 记录"三个强制约定不可能被跳过——不是靠自觉，而是靠脚本门禁：门禁未通过则命令非零退出，流程无法继续。

任何使用路径（有 C0 / 无 C0 / 手动）的第一步，必须依次执行：

# ① 启动门禁（自动：记录会话 + 创建 .debug/{bug-id}/ + 标记 O2 待处理）
python3 scripts/debug_db.py gate --project {project_key} --bug-id {bug-id} \
  --debug-root {项目根目录} --desc "{Bug 描述}"
# 输出必须为 {"gate": "passed", ...}，否则停止

# ② O2 完成需求预处理后（多专家辩论 → 选 references/ skill 出规划 → 格式匹配转换 DAG）：
python3 scripts/debug_db.py gate-done --project {project_key} --bug-id {bug-id}

# ③ 交给 G3 执行前，必须校验门禁与执行契约：
python3 scripts/debug_db.py gate-check --project {project_key} --bug-id {bug-id}
python3 scripts/debug_db.py contract-check --project {project_key} --bug-id {bug-id}
# 两者输出必须均为 passed；任一输出 blocked/failed/violated（非零退出），禁止继续

门禁拦截规则（🔒 强制执行）：

执行顺序不可调换、不可省略：① gate → ② O2 预处理 + gate-done → ③ gate-check 通过 → ④ G3 执行 → ⑤ 产物写入 .debug/{bug-id}/ + debug.db 记录。

规划-执行分离架构（🔒 强制执行）

> 核心原则：references/ 中的所有 skill 只出规划，不执行；具体执行全部交由 G3；G3 执行前 必须由 O2 做格式匹配。三者职责边界不可逾越。

分工铁律：

强制流程：

gate → O2 预处理：
       ① 多专家辩论 → 分类 Bug 类型
       ② 选型：调用匹配的 references/ skill（skill 只产出子流程规划）
       ③ 格式匹配：O2 将规划转换为 G3 标准 DAG JSON（校验字段/依赖/格式）
     → gate-done → gate-check 通过
     → G3 按 DAG 执行（唯一执行者）→ 产物写入 .debug/{bug-id}/ + debug.db 记录

禁止事项（🔒 强制）：
- ❌ references/ skill 不得直接执行任何任务（它们只出规划，是子流程设计者）
- ❌ D4 主体不得绕过 G3 直接执行修复/验证动作
- ❌ G3 不得跳过 O2 格式匹配直接执行规划（未匹配的规划视为非法输入）
- ❌ O2 不得越过 G3 代行执行（O2 只做规划与格式匹配）

格式匹配检查项（O2 交给 G3 前必须逐项通过）：
- [ ] 规划已转换为标准 DAG JSON（任务 id/title/type/risk_level + transitions）
- [ ] 依赖关系无环、可拓扑排序
- [ ] 每个任务标注风险等级（high/medium/low），高危任务已设人工确认
- [ ] 与 references/ skill 的规划内容一致（无遗漏子流程）

技术强制（contract-check，🔒 100% 强制执行）：

> 仅靠文档标注是软约束。真正的强制来自脚本门禁：每次会话在 debug.db 中写入执行契约字段
> execution_contract = plan_only_g3_exec（由 gate 自动写入），G3 执行前必须通过契约校验，
> 未通过则非零退出，流程无法继续。

# G3 执行前，必须运行执行契约校验（强制）：
python3 scripts/debug_db.py contract-check --project {project_key} --bug-id {bug-id}
# 输出必须为 {"contract": "passed"}；若输出 violated（非零退出），禁止 G3 执行

契约校验三要素（任一不满足 → violated + 非零退出）：

完整强制链：gate（写入契约）→ O2 规划+格式匹配 → gate-done → contract-check 通过 → G3 执行（唯一执行者）

执行-回归循环（🔒 强制：G3 执行后必须回到 skill 规划继续）

> 目的：防止"G3 切入执行后子流程被打破"——G3 每批执行完必须回到 references/ skill 的规划中，
> 检查是否还有未完成步骤；未完成则继续，直到该 skill 设想的完整子流程全部完成，才允许收尾。

循环流程（每批迭代）：

references/ skill 规划（O2 注册总步骤）
   ↓
O2 生成本批 DAG → contract-check 通过 → G3 执行本批
   ↓
G3 回写进度 plan-progress（累计已完成步骤）
   ↓
plan-check（🔒 强制，每批后必须运行）：
   ├─ 存在未完成规划（exit=1）→ 回到 references/ skill 规划，O2 生成下一批 DAG，继续循环
   └─ 全部完成（exit=0）→ 循环结束，进入收尾（验证报告 + debug.db 记录 + 询问用户）

命令（🔒 强制执行）：

# ① O2 选型时：注册 skill 规划（记录该 skill 子流程总步骤，循环基准）
python3 scripts/debug_db.py plan-register --project {project_key} --bug-id {bug-id} \
  --skill {skill文件名} --steps {总步骤数} --summary "{1.复现 2.定位 3.修复 4.验证}"

# ② G3 每批执行完成后：回写累计进度（达到总步骤自动 completed）
python3 scripts/debug_db.py plan-progress --project {project_key} --bug-id {bug-id} \
  --skill {skill文件名} --done {累计已完成步骤}

# ③ 循环检查（🔒 每批后必须运行）：未完成 → exit 1 + 列出剩余步骤
python3 scripts/debug_db.py plan-check --project {project_key} --bug-id {bug-id}

强制规则（🔒 不可违反）：
- 🔒 G3 每批执行后必须运行 plan-check，不得跳过直接收尾
- 🔒 plan-check 输出 loop: continue（exit 1）时，必须回到 references/ skill 规划，由 O2 生成下一批 DAG 继续执行，禁止放弃剩余步骤
- 🔒 所有规划均 completed（exit 0）才允许进入收尾（验证报告、debug.db 记录、询问用户）
- 🔒 未注册规划就执行 plan-progress 会报错，必须先 plan-register

G3 批次隔离（🔒 强制：并行/串行/上下游互不干扰）

> 目的：每个 G3 执行批次是隔离单元——不得干扰其他并行/串行批次，也不得干扰上下游 skill 规划。
> 隔离靠独立工作目录 + 批次登记保证：批次间不共享、不覆盖、不串写。

隔离目录结构（由 batch-start 自动创建）：

<project-root>/.debug/tmp/{bug_id}/{skill}/batch-{N}/
    ├── batch-1/    ← 批次 1 专用（仅本批次可读写）
    ├── batch-2/    ← 批次 2 专用（仅本批次可读写）
    └── ...

命令（🔒 强制执行）：

# ① 批次启动：创建该批次独立隔离目录并登记（batch 号省略则自动递增）
python3 scripts/debug_db.py batch-start --project {project_key} --bug-id {bug-id} \
  --skill {skill文件名} --debug-root {项目根目录}

# ② 批次结束：标记 done/failed（失败批次不影响其他批次）
python3 scripts/debug_db.py batch-end --project {project_key} --bug-id {bug-id} \
  --skill {skill文件名} --batch {N} --status done|failed

# ③ 隔离检查：列出全部批次与隔离目录，确认互不重叠
python3 scripts/debug_db.py batch-list --project {project_key} --bug-id {bug-id}

隔离铁律（🔒 不可违反）：

自动化工作流（C0 下游集成 O2+G3，无 C0 也可直接调用）

触发方式:
- 有 C0: C0 调度 → D4 入口 → gate → O2 规划+格式匹配 → G3 执行 → 产物输出 → .debug/{bug-id}/
- 无 C0: 直接调用 D4 → 用户给出 Bug 描述 → gate → O2 规划+格式匹配 → G3 执行 → 产物输出 → .debug/{bug-id}/

两种方式都支持，用户可以按需选择。

整体流程

[C0 → ] D4 入口 → 🔒 启动门禁 gate → O2 规划路由+格式匹配(预处理)
        → gate-done → gate-check + contract-check 通过
        → 循环：G3 批次(batch-start → 隔离目录执行 → batch-end) → plan-progress 回写 → plan-check
             ├─ 未完成 → 回到 skill 规划 → O2 下一批 DAG → G3 新批次（隔离）继续 🔄
             └─ 全部完成 → 收尾：产物输出 .debug/{bug-id}/ + debug.db 记录

.debug/ 输出目录约定

路径: <project-root>/.debug/{bug-id}/

{bug-id} 格式: BUG-YYYYMMDD-{seq} → 例如 BUG-20260807-01

目录结构:

.debug/
├── BUG-YYYYMMDD-{seq}/
│   ├── BUG-YYYYMMDD-{seq}-report.md       # Bug 排查报告（模板见「最终交付物」）
│   ├── BUG-YYYYMMDD-{seq}-debug-log.md    # 调试过程记录
│   ├── BUG-YYYYMMDD-{seq}-verification.md # 修复验证报告（zero-regression 矩阵）
│   ├── *.log                              # 日志文件
│   └── artifacts/                         # 截图、diff 等产物
└── tmp/                                   # 🔒 临时工作目录（gate 自动创建）

使用规则（🔒 强制执行，不可跳过）:
- 🔒 .debug/ 必须添加到 .gitignore，不提交到 git（中间产物，可能包含敏感信息）
- 🔒 每次修复必须新建目录，禁止覆盖旧目录，保证可追溯
- 🔒 临时工作目录 .debug/tmp/（防污染，重要）：
- 修复 debug 过程中产生的临时 py 脚本、中间数据文件、调试产物一律放入 .debug/tmp/ 运行与存放
- 禁止将临时脚本/中间数据写入项目目录（不污染项目源码树）
- 命令示例：python3 .debug/tmp/reproduce.py / python3 .debug/tmp/check_fix.py
- 该目录由 gate 命令自动创建，无需手动 mkdir

触发与预处理（🔒 强制执行，不可跳过）

🔒 D4 启动后，必须立刻由 O2 接管进行需求预处理，不出现断档。任何 Bug 排查请求都不允许跳过此步骤直接进入 Phase 1：

1. 🔒 用户输入: Bug 描述（自然语言）
2. 🔒 O2 预处理（规划路由 + 格式匹配）:
   - 多专家辩论 → 分类 Bug 类型
   - 选型：调用匹配的 references/ skill，skill 只产出子流程规划（不执行）
   - 格式匹配：O2 将规划转换为 G3 标准 DAG JSON（校验字段/依赖/风险等级）
3. 🔒 输出: 格式匹配通过的 JSON 任务 DAG → 交给 G3 执行（G3 是唯一执行者）
4. 🔒 记录: 将本次会话写入 debug.db（见下节），不允许静默开始排查

G3 执行

G3 按 DAG 拓扑执行任务，完成所有步骤后，所有输出产物写入 .debug/{bug-id}/ 目录。

记录与复检（debug.db，🔒 强制执行）

存储位置: <skill>/d4.db/{project_key}/debug.db（SQLite，按项目物理隔离，自动建库）
管理脚本: scripts/debug_db.py（21 个命令，完整速查见 docs/debug-db-guide.md）

🔒 数据隔离规则（强制执行）:
- 🔒 每项目独立数据文件，物理隔离杜绝串项目；所有命令必须指定 --project
- 🔒 project_key/bug_id 仅允许字母/数字/下划线/连字符，非法字符（含路径穿越）直接拒绝
- 🔒 项目首次使用任何命令自动建库，无需手动 init

🔒 每次 Bug 排查必须完成以下数据库记录（与 .debug/ 文件输出并行，不可省略）：
- gate 会话创建（自动化路径）｜session-end 总结+建议 ｜feedback 满意度/干预/情绪
- skill-call 每次调用 references/ skill 的记录
- plan-register/plan-progress/plan-check 规划进度与循环检查（🔒 每批后必须）
- batch-start/batch-end/batch-list 批次隔离（🔒 G3 每批必须）

复检机制（🔒 定期执行，仅限当前项目）:
- review --min-satisfaction 3 找满意度 ≤ 阈值会话 ｜ query 查看完整记录 ｜ stats 项目统计
- 🔒 修复完成后必须依据用户反馈复检：满意度、干预次数、情绪，据此调整后续排查策略

数据用途:
- 下次同类 Bug 先 query 查该项目历史，直接获取上次修复建议
- 满意度低 / 干预多的会话标记需改进，避免重复同样弯路

修复完成后的收尾对话（🔒 强制执行）

每次修复流程完成时，必须主动询问用户：

> 本次 debug 已完成。是否查看 debug skill 调用情况？

• 用户确认 → 运行 python3 scripts/debug_db.py skill-summary --project {project_key} --bug-id {bug-id}，展示本次排查调用了哪些 references/ skill、分别在哪个阶段、什么原因
• 也可运行 python3 scripts/debug_db.py skill-summary --project {project_key} --recent 10 查看最近若干会话的调用情况
• 无论用户是否查看，skill-call 记录必须在每次调用 references/ skill 时同步写入，不得遗漏（🔒 强制）

Phase 1: 证据收集（无证据不前进）

> 铁律：没有证据 = 不修复。复现不出 = 要求更多上下文，不能继续修。

日志解析命令速查（错误搜索/堆栈提取/多服务关联/JSON 日志/实时监控）→ references/log-analysis-snippets.md。
证据包模板：触发条件（输入/环境/时序）+ 可观察输出（错误/日志/截图）+ 关联 ID（requestId·traceId·sessionId）。

Phase 2: 根因分析（三法融合）

融合 debug-pro 七步、superpowers 四阶段、code-error-fixer 五步法，内核一致：复现 → 定位 → 理解 → 修复 → 验证。

2A 七步协议（操作顺序）：1 复现 → 2 隔离（git bisect/二分/注释）→ 3 假设（具体可检验）→ 4 插桩（日志/断点/断言）→ 5 验证根因（错则回 3）→ 6 最小修复（忍住不重构）→ 7 回归测试。

2B 四阶段纪律（superpowers）：根因调查 → 模式分析 → 假设与检验（"我认为 X 是根因，因为 Y"，一次改一变量）→ 基于证据的修复（先写失败测试）。3+ 次修复失败 → 停止并质疑架构（是否每处修复暴露新共享状态/耦合？是否需大规模重构？是则先与用户对齐架构方向）。

2C 五步法（code-error-fixer）：复现 → 定位（未定位到具体行禁止修复）→ 理解（不能解释根因不能修）→ 修复（一次一处）→ 验证（失败回 Step 1）。

语言特定调试命令 → references/debugger-commands.md（源自 debug-pro）；错误类型与诊断策略矩阵 → references/error-patterns.md（源自 code-error-fixer）。

根因确认闸门（R1） — 4 条件全满足才可修：可复现 / 因果（最小改动使 Bug 消失）/ 可逆（回退重现）/ 机制（能指出确切代码路径或状态转移）。

Phase 3: 范围与预测

范围准确性闸门（R3）：① 调用方清单（所有消费者已枚举）② 契约清单（接口/契约/行为已列）③ 不变量检查（须保持的不变量已列）④ 调用点枚举（所有调用点已枚举分类）⑤ 重复扫描（无并行实现漏改）。

副作用预测（R5）：改动蓝图 → 影响涟漪（L0 代码→L1 模块→L2 功能→L3 系统→L4 用户）→ 盲点检查（读 references/blind-spots.md 逐条核对）→ Go/No-Go 决策。

相似问题扫描（R4）：rg -n "function_name|similar_pattern" --glob "*.{ts,tsx,py,js}"

Phase 4: 修复

• 🔒 R11 只修当前 Bug，禁止顺带调整其它地方：修复动作严格限定在当前 Bug 根因范围内；发现其它潜在问题只记入 bug-patterns.md/bug-records.md，不顺手修改；超范围改动必须单独提出并与用户确认。
• 最小改动，优先 ≤50 LOC；超出需说明。一次只改一个，绝不批量无关修复。
• 分层规则（R2）：

• 模式匹配安全（R9）：正则/字符串/名称查找 → 始终考虑边界条件（词边界/锚点/精确）。
• 框架假设审计（R7）：列假设 → 读源码验证 → 注释中记录来源。

Phase 5: 验证与审查

5A 零回归验证（R6 前半）：测试整个影响链（L0-L3），不只原始 Bug。功能（单元+集成+API+E2E+手动）+ 性能（无 N+1/泄漏/变慢）+ 并发（线程安全/原子/无竞态）。矩阵 → references/regression-matrix.md。

5B 运行时生效验证（R6 后半）：① 清字节码缓存（__pycache__ 已删）② 重启服务（PID 变化）③ 健康检查 200（/docs 或等价端点）④ 走到修复路径（请求触发修复逻辑）。未部署 → 重启重验后再继续。

5C 代码审查（增强 · 源自 tvs-code-reviewer）：修复后必走审查 → references/code-review-checklist.md。原则：无证据不算发现；按严重度输出【发现/证据/影响/置信度】；只指问题不代改。

5D 测试生成（增强 · 源自 unit-testing-test-generate）：为 Bug 场景生成最小复现测试防回归 → references/test-gen-guide.md。

停止条件：代码审查干净 + 回归通过 + 运行时已验证 + 原 Bug 已修复。

Phase 6: 知识沉淀与自我反思

• 每次修复更新 references/bug-records.md；新模式/策略更新 references/bug-patterns.md；新盲点更新 references/blind-spots.md。
• 自我反思（R10） 评分(1-5)：首次正确性 / 范围准确性 / 最小改动 / 副作用预测 / 根因深度（合计 /25）。
• 回归解剖（引入回归时）：原 Bug / 引入的新 Bug / 为何没预测到（盲点）/ 分类（漏调用方·契约违反·边界 case）。

最终交付物

完成排查后生成 3 个新文件 + 2 个参考文件增量更新，模板全文见 references/deliverable-templates.md（按需加载）：

可分享 HTML 报告：需要时生成 BUG-XXXX-report.html，模板见 references/deliverable-templates.md §5（内嵌 CSS，单文件可分发）。

参考文件索引

references/ 目录共 23 个文件，与下表一一对应（括号内为来源 Skill，详见 ATTRIBUTION.md）：

日志/调试：
- references/log-analysis-snippets.md（log-analyzer）— 日志解析命令速查
- references/debugger-commands.md（debug-pro）— 语言调试命令
- references/error-patterns.md（code-error-fixer）— 常见错误矩阵
- references/git-bisect.md（通用知识整合）— 二分法定位引入提交

模式库：
- references/bug-patterns.md（bug-fixing，活文件）— 通用 Bug 根因模式（可增量追加）
- references/backend-patterns.md（bug-fixing）— 后端高频问题模式
- references/frontend-patterns.md（bug-fixing）— 前端高频问题模式
- references/system-rca.md（bug-fixing）— 跨进程/多层系统级 RCA
- references/security-patterns.md（security-best-practices）— 安全漏洞排查模式
- references/performance-debug.md（performance-bottleneck-debug）— 性能瓶颈调试方法论
- references/ci-cd-failure.md（ci-cd-failure-troubleshooting）— CI/CD 流水线失败诊断
- references/dependency-conflict.md（dependency-conflict-resolver）— 依赖版本冲突调试

测试增强：
- references/property-based-testing.md（property-based-testing-gen）— 属性测试边界探索
- references/visual-regression.md（visual-regression-guard）— 前端视觉回归测试
- references/diff-testing.md（diff-testing-checker）— 重构差分对比测试

防护/规则：
- references/blind-spots.md（bug-fixing）— 常见盲区清单
- references/regression-matrix.md（bug-fixing）— 零回归验证矩阵模板
- references/iron-rules.md（本 D4 自研）— 十一条铁律详解

增强：
- references/code-review-checklist.md（tvs-code-reviewer）— 代码审查检查清单
- references/test-gen-guide.md（unit-testing-test-generate）— 测试生成指南
- references/bug-records.md（bug-fixing，活文件）— Bug 记录沉淀（可增量追加）
- references/deliverable-templates.md（D4 自研）— 交付物模板库（报告/验证/HTML 按需加载）
- references/ui-style-guide.md（taste-skill 适配）— HTML 交付物 UI 风格指南（三参数驱动：DESIGN_VARIANCE / MOTION_INTENSITY / VISUAL_DENSITY）

技术文档（docs/）：
- docs/README.md — 文档索引与核心概念速览
- docs/architecture.md — 规划-执行分离架构（三角色分工）
- docs/execution-workflow.md — 完整执行工作流（门禁→循环→收尾命令序列）
- docs/debug-db-guide.md — debug.db 数据库指南（17 命令速查 + 表结构）
- docs/isolation-and-security.md — 隔离与安全机制
- docs/changelog.md — 变更记录（机制演进与提交对照）

禁止做的事

• ❌ 不收集完整错误信息就开始猜
• ❌ 不确认根因就改代码（霰弹式修改）
• ❌ 一次改多个无关问题
• ❌ 修复后不验证（含运行时生效验证）
• ❌ 对不确定问题直接建议"升级依赖/重装"而不分析根因
• ❌ 复杂问题不尝试构建最小复现
• ❌ 只修症状不修根因
• ❌ 跳过代码审查直接结案