在已有 PRD/SPEC 后，把需求拆成可独立演示…

适用于需要把 PRD/SPEC 或粘贴需求转成 agent-ready、按依赖排序、每个都能独立演示的 Issue 卡片时。

适用场景

解决思路

1. 核心原则：使用 tracer bullet/纵向切片，不要按层做横向切片。横向切片是每个 ticket 只交付一层（所有 schema、所有 API、所有 UI），要等所有层落地才可用；纵向切片是一次交付穿过所有层的一条窄而完整的路径（schema + API + UI + 测试），落地即可独立验证。
2. 对每个 Issue 做测试：完成后我能演示什么？若答案是一层（例如数据库有了 priority 列）而不是一个行为（例如用户能设置任务优先级并看到持久化），就是横向切片，重新切片。
3. 尺寸下限：若整个变更能放进一个 context window，就不需要 Issue，直接说明并让用户使用 /goal。
4. 保持与 /prd-to-spec 在同一个 context window；不要在两者之间清空或压缩，否则 SPEC 需重新获取且可能截断。
5. 定位输入：询问用户基于什么创建 Issue：A 自动检测 tasks/ 中最近的 PRD 和 SPEC；B 指定 PRD 文件（如 tasks/prd-priority-system.md）；C 指定 SPEC 文件（如 tasks/spec-priority-system.md）；D 同时用 PRD 和 SPEC（最好：PRD 给需求，SPEC 给技术契约）；E 直接粘贴需求。
6. 若自动检测，列出可用文件让用户选择。
7. 若同时有 PRD 和 SPEC，以 SPEC 第 10.2 节 Issue Mapping 为主要指导，并用 PRD 的 User Stories 补充；若只有 PRD，直接从 User Stories 生成 Issue。
8. 先找 prefactoring：在切功能前，寻找机械性铺垫工作，使功能 Issue 更小更安全，例如抽取共享 helper、放宽类型、添加 seam、移动文件；把这类工作排在最前，作为独立 Issue。若没有就跳过，不要发明无意义工作。
9. 把行为拆成纵向 Issue：每个 Issue 是 tracer bullet，是穿过其涉及的每一层的一条窄而完整、可演示的路径；不是 X 的后端，而是 X 端到端的一个 case。
10. 每个 Issue 要能放进一个 fresh context window，由单个 agent 会话完成，不需要你在场。
11. 按行为拆分，不按层拆分：若 User Story 太大，拆成 2-3 个更窄的行为，每个仍然纵向，并声明显式阻塞边；绝不要拆成后端 ticket 和前端 ticket。
12. 合并微小故事：只有 1-2 个琐碎验收标准、不能独立演示的故事，合并进相关 Issue。
13. 显式声明阻塞边：每个 Issue 列出必须先完成什么才能开始；这些边是产物的重点。
14. 按依赖顺序编号 Issue：阻塞者在前，这样实现者或 tracker 总有可开始的 frontier。
15. 若有 SPEC，为每个 Issue 补充 SPEC 引用（API 契约、数据模型章节、错误处理）；但 Issue 正文中不要放文件路径和行号，它们会腐烂；改为描述行为和契约。
16. 可证伪验收标准：对每条标准，指出能证明它为假的观察，并确认在实现者起始 commit 上会失败。拒绝三种形状：在 base commit 已经为真的标准；只能由另一个 Issue 负责的工作满足的标准；仅复述请求的标准。纵向切片交付之前不存在的行为，所以按构造应在 base commit 为红。
17. Issue 格式：Issue #N: [Title — a behaviour, not a layer]；Description: [What behaviour this delivers, end to end, and why]；Demo path: [The one thing you can show working when this lands]；Acceptance Criteria: - [ ] [Falsifiable — names an observation that fails at the base commit]；Blocked by: [None / Issue #X, #Y]；Priority: [high / medium / low]；SPEC Reference: [Section X.Y — contracts only, no file paths; only if SPEC available]。
18. 向用户测验（不可跳过）：先以编号列表展示拆解结果，在发布前 quiz 用户；过度拆解和意外横向切片是两个最常见失败，此步用来捕获它们。
19. 测验检查点：Granularity：太细？例如 merge #3 and #4；太粗？例如 split #2。
20. 测验检查点：Demo path：任何 Issue 的 demo 是层而不是行为，就是切错了，让用户指出。
21. 测验检查点：Edges：Blocked by 链接是否真实？是否有缺失或虚假？
22. 测验检查点：Adjust：例如 change #2 priority to high、add an issue for a priority badge。
23. 测验检查点：Confirm：回复 OK 才继续；在确认前不要创建任何 Issue。
24. 选择创建模式：询问 A GitHub（通过 gh CLI，支持原生阻塞链接和可选 sub-issues）；B Local（每个 Issue 一个 markdown 文件，按依赖排序）。
25. GitHub 模式前置：gh CLI 已安装并认证，v2.94+ 以支持 --parent / --blocked-by。
26. GitHub 模式：先创建阻塞者，使其 Issue 编号在任何依赖它的 Issue 之前存在；捕获每个返回编号。
27. GitHub 模式：按依赖顺序对每个 Issue 执行 gh issue create --title [Title] --body [Description + Demo path + Acceptance Criteria + SPEC Reference] --label priority: [priority] --blocked-by [comma-separated blocker numbers, if any] --parent [spec issue number, if creating as sub-issues]。
28. GitHub 模式：边使用原生 --blocked-by；只有 tracker 拒绝该 flag 时，才回退到正文中的 Blocked by #X 行。
29. GitHub 模式：若 SPEC 存在于 GitHub issue 中，传 --parent <spec_issue> 使其成为其 sub-issues；事后接 parent 可用 gh issue edit <parent> --add-sub-issue <n>。
30. GitHub 模式：若 label 不存在，先创建 label，或跳过 --label flag。
31. GitHub 模式：报告创建的 Issue 编号和 URL。
32. Local 模式：询问 Issue 文件保存位置，默认 .autoresearch/issues/[feature-slug]。
33. Local 模式：如不存在，用 mkdir -p 创建 feature 文件夹；每个 feature 一个文件夹，避免并行 agent 在共享文件上竞争。
34. Local 模式：按依赖顺序为每个 Issue 保存 NN-[slug].md（零填充，NN 是真实 ticket ID，使 /goal 03 可用），内容格式：# [Title — a behaviour]；## Description；[What behaviour this delivers, end to end, and why]；## Demo path；[The one thing you can show working when this lands]；## Acceptance Criteria；- [ ] [Falsifiable criterion 1]；- [ ] [Falsifiable criterion 2]；## Blocked by；[None / #NN, #NN]；## Priority；[high / medium / low]；## SPEC Reference；[Section X.Y — contracts only; omit if no SPEC]。
35. Local 模式：按依赖顺序报告创建的文件路径。
36. 宽重构例外：有一种形状打破 tracer-bullet 规则——wide refactor：单个机械改动（重命名列、重定型共享 symbol）影响全代码库，一次编辑破坏大量调用点，没有纵向切片能单独变绿。此时按 expand → migrate → contract 排序。
37. 宽重构 Expand：在旧形式旁添加新形式，确保不破坏任何东西；一个 Issue。
38. 宽重构 Migrate：按影响范围分批迁移调用点（按 package、按 directory），每批一个 Issue，每个都 blocked by expand；因为旧形式仍存在，CI 保持绿色。
39. 宽重构 Contract：当没有调用者后删除旧形式；用一个 Issue，blocked by 每个 migrate batch。
40. 宽重构：若某些批次单独也无法保持绿色，让它们共享 integration branch，并共同 block 一个最终 integrate-and-verify Issue；只在那个 Issue 承诺绿色。
41. 总结报告：输出 Source: [PRD/SPEC path]；Mode: [GitHub / Local]；Issues created: N（按依赖顺序）。
42. 总结报告表格列：# | Title (behaviour) | Blocked by | Identifier；示例：1 | Extract task-mutation helper | — | #42 / 01-*.md；2 | Set & persist task priority | #1 | #43 / 02-*.md；3 | Filter task list by priority | #2 | #44 / 03-*.md；4 | Sort task list by priority | #2 | #45 / 04-*.md。
43. 总结报告：列出 Frontier（没有未关闭阻塞、可立即开始）：#1。
44. 总结报告：说明 Dispatch 是手动的——每个 fresh session 一个 Issue，会话之间清空；数出没有未关闭阻塞的 Issue 数量，开同样多会话，用 /goal 实现：GitHub 模式 /goal 42；Local 模式 /goal 01-*.md；并注意 /goal 可能不会自动关闭 ticket，完成后自行更新状态。
45. 检查是否有效：每个 Issue 都能回答完成后能演示什么，且答案是一个行为而不是一层。
46. 检查是否有效：任何发布前，列表已按编号返回，并且每个 Issue 有真实 Blocked by 行。
47. 检查是否有效：顶部 Issue 没有阻塞，可立即开始。
48. 检查是否有效：没有 Issue 正文携带文件路径或行号（除非是原型产生的片段）。
49. 检查是否有效：每个 Issue 读起来像一个 fresh session 能在没有你在场时完成的任务。
50. 检查是否有效：若找到 prefactoring，它位于顺序最前，而不是混进功能 Issue。
51. 检查是否有效：每条验收标准都指出一个在 base commit 会失败的观察。
52. 边界与回退：整个变更能放进一个 context window：说明并跳过 Issue，直接指向 /goal。
53. 边界与回退：tasks/ 中找不到 PRD/SPEC：要求用户提供文件路径或粘贴需求。
54. 边界与回退：PRD 没有 User Stories：改为从 Functional Requirements 推导 Issue。
55. 边界与回退：SPEC 有 Issue Mapping（Section 10.2）：用它作为主要来源，并与 PRD 交叉引用。
56. 边界与回退：模型产出了按层划分的 Issue：在 quiz 阶段捕获；任何 demo 是层的 Issue 都重新纵向切片。
57. 边界与回退：模型过度拆解（3 行改动 12 个 ticket）：在 quiz 阶段要求合并；若整个变更能放进一个 window，跳过 Issue。
58. 边界与回退：宽机械重构：使用上面的 expand → migrate → contract 序列。
59. 边界与回退：gh 版本太旧，不支持 --blocked-by / --parent：回退到正文中的 Blocked by 行；建议升级 gh 到 v2.94+。
60. 边界与回退：GitHub 模式下 gh CLI 未认证：显示错误，建议 gh auth login，并提供切换到 Local 模式。
61. 边界与回退：Local 模式下 Issue 文件夹不存在：自动创建 per-feature 文件夹。
62. 边界与回退：用户拒绝创建 Issue：将依赖顺序列表作为文本摘要打印，供之后手动创建。
63. 与其他技能衔接：/prd → /prd-to-spec（可选）→ /to-issues → /goal → /review-it → /ship-it。
64. 与其他技能衔接：/prd 产出 PRD（本技能输入）；/prd-to-spec 产出 SPEC（可选；与本技能保持同一 context window）；/to-issues 产出纵向切片 Issue（本技能）；/goal 逐个实现 Issue，每个 fresh session 一个。

适用边界 · 注意事项

• 整个变更能放进一个 context window 时，不要拆 Issue，直接说明并让用户使用 /goal。
• 宽范围机械重构（wide refactor）不适合普通 tracer-bullet 纵向切片；应改用 expand → migrate → contract 序列，或共享 integration branch 并 block final integrate-and-verify。