plan-debug

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# /cc-code:plan-debug — bug 诊断编排器（不进 plan 模式，bugs.md 自动整理）

> ⭐ **不进 plan 模式，没有「批准方案」这道门。** 诊断是收集事实，不是做决定；plan 模式会让 qa 写不了文件，中途一断线记录就丢。所以 qa **复现一成功就写 B-n**，诊断每推进一步就地补全，记录不等主人批准。
> **定位：技术诊断编排器，不是需求规划器。** 与 `/cc-code:plan-feature` 的分界：那个处理「需求模糊」，本命令处理「需求明确但实现错了」—— bug 本身就是需求，期望行为要么主人说了，要么 `prd.md` 已有断言、`ux.md` 已有交互判定、`design.md` 已有设计数值、`ui-gates.md` 已有视觉规则、`.cc_code/test/visual/baseline/` 已有冻结基线。
> **主控只传话**：主控是编排者，不扮演任何角色——不读 `src/`、不跑 codegraph、不思考根因、不替主人回答、不写 `bugs.md`。复现取证与 B-n 登记归 `qa`，根因与方案归 `dev`（只读，不改任何文件）。
> **配对**：本命令把 B-n 整理到 `待修复` 后，修复执行走 `/cc-code:agent-debug`（增量定位 B-n → dev 修 → qa 复测 → affected 精准回归）。视觉规格本身写错 → 先走 `/cc-code:plan-uiux`（模式二）改规格；页面 / 交互规格（`ux.md`）要改 → 交回 `/cc-code:plan-feature` 由 uiux 补，再回 `agent-debug`。本命令 ⛔ 不直接派 uiux、⛔ 不让 pm 写 `ux.md`。

## ⛔ 五条铁律（违反任一即本次诊断无效）

### 铁律 1：期望行为唯一来源 = 主人原话 + 既有断言 / 判定 / 设计数值 / 视觉规则 / 基线
诊断时最容易犯的错就是拿实现当期望。

```
期望行为的合法出处：
  ✅ 主人在对话里的原话
  ✅ prd.md §1.5 的既有 A 断言
  ✅ ux.md 的既有 U 判定项（五态矩阵、页面结构与断点声明）
  ✅ design.md 的已锁设计数值与组件长相
  ✅ ui-gates.md 的视觉规则与阈值（规则号唯一出处）
  ✅ .cc_code/test/visual/baseline/ 的已冻结截图基线（只在视觉地基过门或「定了」后冻结）

  ⛔ 绝不许从「代码现状」反推「所以期望应该是 X」
  ⛔ 绝不许从 codegraph / 日志产出反推期望 —— 它们只答「代码 / 运行时现在是什么样」
  ⛔ 绝不许拿「当前页面看起来正常」当期望 —— 视觉期望来自 design.md 与基线，不来自现状
```

> 出处由 qa 定位并写进 B-n（写清文件 + 小节 / 规则号 / 基线文件名）；dev 诊断时期望行为一律取自 qa 报告里的出处，不自己推。

### 铁律 2：只有四种情况停下交人（裁决门）
qa 把 B-n 的状态写成 `待裁决`，并用**业务语言写一句要主人回答的问题**（写进 B-n 的「待裁决」字段）；主控把这句话原样问主人，⛔ 主控不自己判、不自己改。除这四种，一律自动往下走，不问主人。

| 编号 | 命中情形 | 谁发现 | 主人裁决后，主控派谁 |
| :-- | :--- | :--- | :--- |
| ① | 根因是**契约**错（api / data / project 本身错） | qa（读 dev 诊断后） | `architect` 改 L3 对应小节 |
| ② | 根因是**需求**或**视觉规格**错（prd / ux 的行为半边 / design.md 本身错） | qa（读 dev 诊断后） | prd → `pm` 改对应小节；ux → ⛔ 本命令不改、不派 uiux，交回 `/cc-code:plan-feature` 由 `uiux` 补（或主人裁决后走 `/cc-code:plan-uiux` 模式二）；design.md → 先跑 `/cc-code:plan-uiux`（模式二，锁后只有它能改 `design.md`），改完回 `agent-debug` 重判 |
| ③ | prd / ux / design / api 里**找不到期望出处**，无法判定是不是 bug | qa（复现阶段） | 主人说「这是新需求」→ 交回 `/cc-code:plan-feature`（业务需求由 `pm` 补，页面 / 交互规格由 `uiux` 在同一次落盘）；主人说「不是 bug」→ qa 把条目原文搬 `backup/retired/bugs.md` 后从 active 移除 |
| ④ | **复现不了** | qa（复现阶段） | 主人补充信息 → 续接原 qa 重新复现 |

> **纯实现层的 bug**（契约、需求、设计规格都没错，是代码没按它们做）**不需要主人批准方案**，状态直接到 `待修复`。
> 「深层 bug 牵涉多文件」**不是**停下的理由 —— 爆炸半径大小是事实问题，由 dev 沿调用链、qa 用 `affected` 算出。

### 铁律 3：落盘即时，四段告知只告知不落盘
落盘物仅两处：`bugs.md` 的 B-n 条目（qa 写，复现成功当场写、之后就地补全）+ `status.md` 一行指针（主控写）。dev 诊断报告里的四段告知（现象 / 根因 / 爆炸半径 / 修法）服务当轮对话告知，⛔ 本体不落盘（过程）；只有它的**结论**落进 B-n 对应字段（结果）。

### 铁律 4：B 编号独立序列
`bugs.md` 的 B-n 独立递增（qa 读已有最大号取下一个），**绝不复用 A / U / V 三个序列**（A、U 永久稳定；V 是视觉段行号，规则号另有 VH / VM / VS 前缀，见 `skills/cc-code/references/ui-gates.md`）。bug 断言生命周期是天级，条目修完由 qa 搬 retired，不占 active 篇幅。

### 铁律 5：越权红线
角色权限唯一出处：`active/Agent.md` §三（主控的写权限见 §一）。本命令不复述权限表，只补两条本命令特有的约束：

- `dev` 在本命令内**只读诊断**：不改 `src/`、不改测试、不写 `bugs.md`。plan 模式不再兜底，这一条靠主控任务说明明文约束（见下）。
- `architect` / `pm` 只在铁律 2 路由命中、主人裁决后才被派，各改自己的层；视觉规格错时主控改派 `/cc-code:plan-uiux`（模式二），由 `uiux` 改 `design.md`，⛔ 主控不直接派 uiux 改锁定的 `design.md`；页面 / 交互规格（`ux.md`）错时交回 `/cc-code:plan-feature` 由 `uiux` 补，⛔ 本命令不直接派 uiux、⛔ 不让 pm 写 `ux.md`。
- 因 ① 契约错派 `architect` 时，任务说明读清单另加三处经验 INDEX（`references/INDEX.md`、`~/.cc-code/lessons/INDEX.md`、`~/.cc-code/team/<仓库名>/INDEX.md`，不存在跳过）；用法与「采纳经验」一行见 `active/Agent.md` §四第 7 条，本命令不复述；该 architect 落盘完成后，主控后台派一次 curator 记采纳（见 `Agent.md` §五「派 curator」）。

---

## 一、生命周期总览

```
触发 /cc-code:plan-debug "<bug 描述>"（不进 plan 模式，无批准门）
  │
Step1 派 qa（全新上下文）复现 + 取证 + 定位期望出处
  │   qa 每轮交回「下一个问题（一次一个）」或「已复现」
  │   主控把问题原样展示给主人，主人原话原样续接给同一个 qa（SendMessage）
  │   复现按 ux.md §一 声明的端与视口、project.md §六 的视口集合与亮暗模式取证，
  │   记录「屏宽 × 亮暗 × 五态」；视觉 bug 另附截图与基线对比结果
  │   ├─ 复现成功 + 找到期望出处 → qa 立即写 B-n
  │   │                            （状态 = 待诊断；现象 / 复现步骤 / 期望出处 / 证据 / 需加探针）
  │   ├─ 找不到期望出处（③）     → qa 写 B-n，状态 = 待裁决 + 一句业务语言问题 ─► 去 Step5
  │   └─ 复现不了（④）           → qa 写 B-n（未复现 + 已试步骤），状态 = 待裁决 + 一句问题 ─► 去 Step5
  │
Step2 派 dev（全新上下文，只读）诊断根因 + 方案
  │   主控把 B-n 里 qa 的报告原样转交 dev（原样转交不算夹带），任务说明写明「只读诊断，不改任何文件」
  │   dev 交回诊断报告：四段告知（现象 / 根因 / 爆炸半径 / 修法，全部业务语言）+ 一行技术备注（影响文件清单）
  │   dev 说不清根因 → 交回「还缺什么证据」→ 主控原样交 qa 补取证 → 回 Step2
  │
Step3 主控把 dev 报告原样转给同一个 qa
  │   qa 就地补 B-n 的 根因 / 爆炸半径 / 方案（修法）（爆炸半径里的回归测试面用 affected 补算）
  │   ├─ 根因是契约错（①）→ 状态 = 待裁决 + 一句业务语言问题 ─► 去 Step5
  │   ├─ 根因是需求或视觉规格错（②）→ 状态 = 待裁决 + 一句业务语言问题 ─► 去 Step5
  │   └─ 纯实现层         → 状态 = 待修复（无需主人批准）
  │
Step4 主控写 status.md「下一步」一行指针（业务语言）
  │   待修复 → 「B-n 待修复，走 /cc-code:agent-debug」；四段告知主人后直接调用 /cc-code:agent-debug 自动开修
  │   （⛔ 不再停下等主人敲命令；Step5 裁决后回到「待修复」的同样自动开修）
  │   qa 补完 B-n 后，主控把四段原样告知主人（爆炸半径里的回归测试面取自 qa 补进 B-n 的结果）
  │   （现象 / 根因 / 爆炸半径 / 修法；告知，不等批准）
  │
Step5（仅 ①~④ 命中时）主控把 qa 写的那句问题原样问主人，status.md 指针写「B-n 等你裁决」
      主人回答后：
      ├─ ① 契约错 ─► 派 architect 改 L3 ────────────────────────┐
      ├─ ② prd 错 ─► 派 pm 改 prd ──────────────────────────────┤
      ├─ ② ux 行为半边错 ─► 交回 plan-feature 由 uiux 补 ux ────┤
      ├─ ② 视觉规格错 ─► 先跑 plan-uiux（模式二）───────────────┤
      ├─ ③ 新需求 ─► 交回 plan-feature 一次补齐 prd + ux ───────┤──► 续接原 qa 更新 B-n（删「待裁决」行，按新契约 / 新需求 / 新规格复核）
      │   ③ 不是 bug ─► qa 把条目原文搬 backup/retired/bugs.md，从 active 移除，本命令结束
      └─ ④ 复现不了 ─► 主人补充信息续接原 qa 重新复现 ─┘
                       更新后的状态：
                       ├─ 已有 dev 诊断（①②）→ 待修复；方案受新契约 / 新需求 / 新规格影响则主控再派 dev
                       │                        只读重估一次，报告原样转 qa 更新
                       └─ 还没诊断过（③④）  → 待诊断 → 回 Step2
```

> 视觉规格错不是「直接派 uiux 改 `design.md`」：锁定后只有 `plan-uiux`（模式二）能改，改完由主人重新「定了」，再回 `agent-debug` 复判。

### 主控写给 agent 的任务说明（格式固定）

| 只写 | 不写 |
| :--- | :--- |
| 读哪些文件（status、prd、ux、bugs.md、project.md §七 日志契约…） | 主控自己对 bug 的理解、猜测、根因 |
| 主人原话（逐字） | 任何技术内容、代码位置、修法建议 |
| 本轮要交回什么 / 要写什么（dev：只读诊断，不改任何文件） | 模型或工具选择 |

---

## 二、各 agent 的本轮任务

### Step1 · qa（复现 + 取证 + 期望出处 + 登记）

From weiyi88/cc-code, MIT.

More from weiyi88/cc-code