| name | full-issues |
| description | Use when the user says "issue拆分", "问题分解", "issue decomposition", "方案对比", "tradeoff analysis", "优先级排序", or has finished system-architecture.md and needs to break it into prioritized issues with solution comparisons. Produces issues.md as a fog-of-war decision map. Step 3 of 6. Not for business requirements (Step 1) or architecture modeling (Step 2). Not for non-functional risk analysis (Step 4) or code-level design (Step 5). |
核心目标
将系统设计的初步结论转换为更细节的模块和更具体的问题，每个带 P0-P3 优先级（MoSCoW）和方案对比取舍。
取舍原则：优先长期、合理的架构设计，提供高可扩展性。较少考虑成本。
执行流程
按 ../full-shared/references/loop-skeleton.md（共享参考目录）的 6 步循环执行。（loop-method.md 的方法论仅 clarity 首次 read，本阶段无需 read。）
Step 1（交互+初稿）— Grilling 遍历 issue 决策树：
[状态追踪] 开始时调 design_status start_phase issues 标记阶段开始（会校验 architecture 已 completed）。
有 design_status tool 优先用 tool：design_status(action: start_phase, phase: issues)；无 tool（Claude Code/Cursor/shell）用 CLI：design-status start-phase issues。CLI 完整用法见 loop-skeleton.md「CLI 完整用法」。
[按 loop-skeleton Step 1.0] grilling 前先获取已确认决策：
[复杂度档位] 先读 _progress.md 的 complexity_tier：L1 档跳过 context-builder（主 agent 直读 decisions.md + 必问决策点引用的上游章节）；L2/L3 派 context-builder。追踪/审查/重建帧的降级见 loop-skeleton「复杂度自评与降级档位·三档执行矩阵」。本阶段上游较多，派 context-builder subagent（fresh）读 {topic_dir}/decisions.md（本 topic 已确认决策）+ 相关长期文档（NFR.md/ADR/ARCHITECTURE.md）+ 上游 .md，输出「阶段工作摘要」（不可推翻决策清单 + 设计树入口 + 接口契约）注入主 agent context。grilling 不得重新确认已 confirmed 决策；每个 D 类决策拍板后按 Step 1.2 即时 append decisions.md。
Issue 决策图（根：从 system-architecture 的挑战推导）
├── P0 阻塞项（前沿，必须先做）
│ └── 每 issue → 方案 A/B/C → 取舍（给强观点）→ blocked_by 依赖边
├── P1 核心项（同 P0 结构）
├── P2 重要项（迷雾，标注 ? 先不展开）
└── P3 延后项（后续迭代）
遍历纪律：先走 P0 前沿，方案对比做完再走 P1。迷雾中的 P2/P3 标注 ? 不强求展开。
生成候选 issue 先按 4 轴扫（见 references/fog-of-war.md「拆分维度 checklist」：状态§5/模块§7/边界§8/挑战§10 + 兜底）→ 再标 P 级。P 级不是拆分维度，先用轴扫再标 P 级，否则天然不 MECE。
从 system-architecture.md 的 §5 状态流转 / §7 模块划分 / §8 Context Map / §10 挑战推导 issue。
按 references/fog-of-war.md 构建决策图（不一次性列完）。按 references/issue-template.md 写方案对比。
复杂根本性 issue 用 DESIGN-IT-TWICE（3+ 并行 subagent 发散）。初稿用 references/deliverable-template.md（含「上游覆盖核验」表——每个②元素必须对应 issue 或标 N/A+理由，这是 Step2 独立重建能 diff 的前提）。
Step 1 必问决策点（代码答不了，逐个 ask_user；本阶段 agent 最易自作主张，务必逐条问）：
- P0/P1 划线 — 每个候选阻塞项问："不做它，后续真的无法推进 / 目标真的无法达成吗？" P 级依赖用户对业务优先级的判断，不能 agent 凭技术启发式定。这是本阶段最高频被 agent 吞掉的决策。【D】
- 取舍原则的局部例外 — 全局默认"长期架构优先、较少考虑成本"，但每个 P0/P1 issue 要问："这里是否仍然适用？有没有成本其实重要的例外？"【D】
- DESIGN-IT-TWICE 的最终选定 ⭐ — 凡触发并行 subagent 发散的根本性架构选择，最终选定必须 ask_user，不能 agent 给完 opinionated 推荐就记录进 issues.md。（当前 issue-template 让 agent "选择+记录"，这是最大的提问漏洞）【D-不可逆】
- 迷雾展开判断 — fog-of-war"前沿清晰即停"，但"够不够清晰 / 还有没有没说的需求"必须问用户，不能 agent 自判收敛。【K/D】
- P3 延后项逐条确认 — 每个标 P3 的问用户是否同意延后 + 理由（用户可能说"这个其实重要"）。【D】
方案对比的技术分析（改动/优点/缺点）= agent 产出，作为用户决策的参考材料。
Step 1 末尾 — 机器结构检查前置（零成本提速）： 初稿（含必问决策点定稿）写完后，主 agent 调 cw(action=clarify) / cw(action=detail) 触发 CW gate 的机器检查，FAIL 当场修低级硬伤（幽灵 #N、空 N/A、❌/待补残留、P0/P1 缺 ≥2 方案、P 级与 blocked_by 不一致），不必等 Step 6。
与 Step 6 审查的分工：此处只杀机器可证的结构硬伤（快、CW gate 自动跑）；Step 6 才是质量门（fresh subagent 跑，含语义/盲区/红队评审）。两者不替代——Step 6 审查前 CW gate 的机器检查 FAIL 仍硬阻断。
Step 2（追踪）— 派 fresh-context subagent，对抗主 agent 同源盲区：
主 agent 写 issues.md（含覆盖核验表）时带着某个盲区——它漏掉的元素，自己填表也填不进，表看起来 100% 覆盖实则是自证。Step2 用 fresh context 他证：subagent 从 ② 独立重建覆盖表，与主 agent 的表 diff，差异即真 gap。
派两个异质角色（认知帧不同，不是同名分身）：
| 角色 | 认知帧 | 输入 | 对抗什么 |
|---|
| A 覆盖重建者（必跑） | 规范帧（top-down：② 里每个元素该对应什么 issue） | 禁读 issues.md（重建阶段），只读 ② + CONTEXT.md | L1 注意力盲区 + 同源自证 |
| B 异常猎手（条件触发） | 失败帧（bottom-up：每个元素什么会坏、什么没人处理） | 读 ② + issues.md | L2 认知同构盲区（类别选择性） |
角色 B 触发条件（满足任一即开，否则只跑 A。判据量化见 loop-skeleton「复杂度自评」信号表）：
- 状态复杂度信号≥中（4+ 状态/单状态机）→ ② §5 含状态转换路径需失败帧扫死角
- 跨边界数信号≥中（2+ 外部系统依赖）→ §8 有跨进程/跨团队边界需扫异常路径
- ② §10 显含并发·时序·一致性挑战词（grep 确认）
- 无状态单一模块的小改动 → B 不触发，A 足矣。
角色 A 关键约束：重建覆盖表 T_recon 之前绝不能 read issues.md——读了就被锚定，回到自证。流程：先从 ② 按 4 轴（与主 agent 同一套，见 fog-of-war.md）独立枚举可拆元素建 T_recon → 重建完才读 issues.md → 两表逐行 diff。
gap = 三态 diff（MECE，覆盖问题的完整分类）：
- MISSING（漏项）：T_recon 有、issues.md 无对应 issue（②有元素没被拆）
- PHANTOM（脱锚）：issues.md 有 issue、② 查不到根（假冒/越界）
- MISMATCH（虚覆盖）：标了对应但内容没真解决（如只写了正常路径，异常分支空缺）
角色 A Task prompt：
你是独立覆盖重建 subagent。上下文与主 agent 隔离——**重建阶段禁止读 issues.md**。
**决策账本纪律：** decisions.md（作为 context 参数注入）里 status=confirmed 的决策是用户已拍板结论，已 confirmed 决策不得当 gap 重报；有下游新证据推翻须标 `[REVISIT of D-NNN]` + 附新证据走 Step 6b 反哺（D-不可逆须主 agent ask_user）。
1. read system-architecture.md（②，真相源）+ 项目根 CONTEXT.md
2. 按拆分维度 4 轴（状态§5/模块§7/边界§8/挑战§10）从 ② 逐条枚举每个可拆元素，
对每个判断：需不需要 issue、是什么 issue。建成覆盖表 T_recon。
（4 轴之外扫 ② 其余章节，凡可拆元素照同样规则处理）
3. **重建完成后**才 read issues.md 的「上游覆盖核验」表。逐行 diff T_recon vs 主 agent 的表。
产出三类 gap：MISSING（②有issue无）/ PHANTOM（issue有②无根）/ MISMATCH（标覆盖但内容未解决）。
4. 每条 gap 标类型（F/K/D）。写入 {topic_dir}/changes/tracing-round-{N}.md。
角色 B Task prompt（条件触发时追加）：
你是独立异常猎手 subagent。上下文与主 agent 隔离。假设 issues.md 是错且不全的。
**决策账本纪律：** decisions.md（作为 context 参数注入）里 status=confirmed 的决策是用户已拍板结论，已 confirmed 决策不得当 gap 重报；有下游新证据推翻须标 `[REVISIT of D-NNN]` + 附新证据走 Step 6b 反哺（D-不可逆须主 agent ask_user）。
1. read system-architecture.md（②）+ issues.md
2. 戴失败帧，按 hunting 清单对每个 issue/元素找未覆盖面：
异常路径(error/fallback/超时/重试/降级) / 边界值(空/单元素/极大极小) /
并发时序(race/幂等/乱序) / 状态机死角(不可达/缺转移/卡死) /
状态机终态矛盾(多入口/多 session 收口终态一致性/诚实态声明与行为矛盾) /
数据流跨层丢失(错误信息/上下文层间传递被吞/覆盖/降级) /
删除测试(对每个 issue 问「不做它会怎样」——抓伪 issue)
3. 产出「未处理清单」，每条标 F/K/D。追加到 tracing-round-{N}.md。
为什么 A、B 是真异质（非换名分身）：A 从 ② 往下推问「该有什么」抓漏项；B 从失败模式往上戳问「什么会坏」抓虚覆盖/伪 issue。同一元素，A 抓「完全没拆」，B 抓「拆了但没拆干净」。不重叠。
追踪原 4 视角的新归属：方案完整性 / 优先级一致性 / 前沿清晰度 由角色 A 在 diff 时顺带核验（读 issues.md 后）；原「覆盖性」视角已升级为 A 的独立重建 diff（更强）。
机器化降级空间：CW gate 的机器检查已覆盖「覆盖核验表形式」「P0/P1≥2 方案」「blocked_by 无幽灵」「P级一致性」——即角色 A（覆盖重建者）的机器可判子集，这些由 CW gate 在 cw(action=clarify) / cw(action=detail) 调用时自动完成，不占 subagent 预算。subagent 只做机器做不了的：从 ②往下的语义重建 diff（漏项/虚覆盖/伪 issue）+ 失败帧异常猎手（角色 B）。机器检查未覆盖前维持 A+B 双角色。
Step 3-4 — gap 分流(F/K/D) → 收敛复核。 按 loop-skeleton.md。
Step 5（定稿+HTML）— 按 references/deliverable-template.md 定稿 issues.md；派 fresh subagent 渲染 issues.html（机制见 loop-skeleton.md Step 5b）（主角图：决策 DAG 图，节点状态色标）。
Step 6（审查）— 派 fresh-context 审查 subagent（按 ../full-shared/references/review-agent.md 规范，CW gate 的机器检查 FAIL 硬阻断），6 维评审（含红队维度），报告写 changes/review-issues.md（frontmatter 含 verdict + machine_check）。APPROVED 后进 Step 6b 反哺检查（回扫 ①②上游），再交接。
Phase Loop 机制
- 收敛失败 → 回 Step 3 补充方案对比/追踪新 issue
- 审查 CHANGES_REQUESTED → 审查意见当 gap 回 Step 3
- 反哺触发上游修订（详见 loop-skeleton.md Step 6b）→ 上游 .md 更新后，本阶段可能需重新对齐 → 回 Step 2 重追踪
- Stagnation（连续 3 轮 gap 不降）→ 强制收敛
Self-Check
[MANDATORY] 禁止在未完成 loop-skeleton 全流程（含 Step 6 审查 APPROVED）时声称完成。
本地目录覆盖规则
- 主目录：
.xyz-harness/（项目根）
- 子目录：
${yyyy-MM-dd}-${主题简短标题}
- 路径：
.xyz-harness/${主题}/issues.md + .html
- 不同主题不同子目录，禁止混放。 单次写入超 1000 字优先拆分子文档。
下游衔接
审查 APPROVED 后向用户交接（按 loop-skeleton.md Step 6 格式）：
[状态追踪] 交接前调 design_status complete_phase issues 收尾——自动校验 issues.md + verdict:pass + review APPROVED，过了才标 completed。
有 tool 优先用 tool：design_status(action: complete_phase, phase: issues)；无 tool 用 CLI：design-status complete-phase issues。
✅ ③Issue 拆分 已完成并通过独立审查。
产出：issues.md + issues.html
审查报告：changes/review-issues.md（verdict: APPROVED）
下一步：④非功能性设计 — issue 解决方案的副作用分析 + 缓解（7 维度）
调用：/full-nfr
是否现在进入下一步？
用户确认后才加载下一 skill。
标记说明
| 标记 | 含义 | 修改约束 |
|---|
| [MANDATORY] | 流程强制要求 | 必须严格遵守 |
