to-issues

Files (2)

• .decision-log.md
• SKILL.md

SKILL.md (first lines)

# To Issues

把正式文档中的未解决工作写入 `docs/features/<feature>/issues/`。本 skill 有两种模式：

- **Normal Mode**：把 `SPEC.md`、Plan 或 PRD 拆成可独立领取的 vertical-slice implementation issues。
- **BMad Control Mode**：当 BMad stories 是主执行队列时，只创建控制面板 issues：blocker、HITL decision、cross-story risk、tech debt、review follow-up、documentation fix。

核心规则：**不要让 local issues 和 BMad stories 同时充当执行队列。** 如果 feature 使用 BMad `sprint-status.yaml` / story files 作为执行主线，local issues 只记录影响多个 stories、需要人类裁决、改变长期契约或不适合塞进单条 story 的事项。

Document workflow、issue tracker 和 triage label vocabulary 应该已经提供给你；如果没有，运行 `/setup-ai-document-system`。

## Mode Selection

进入工作前先判断模式：

| 条件 | 模式 |
| --- | --- |
| 用户明确要求拆 `SPEC.md` / Plan / PRD 为可执行任务，且没有 BMad story cycle | Normal Mode |
| 存在与当前 feature / epic 相关的 `_bmad-output/implementation-artifacts/sprint-status.yaml` 或 BMad story files，或用户说当前 feature 用 BMad stories 执行 | BMad Control Mode |
| 输入来自 BMad review、readiness、dev-story 中发现的 blocker / risk / follow-up | BMad Control Mode |
| 不确定执行主线 | 先问一句：这个 feature 的实现队列是 local issues 还是 BMad stories？ |

BMad Control Mode 的硬约束：

- 不要为每个 BMad story 创建一个重复的 `ready-for-agent` issue。
- 当前 story 内可直接完成、只影响当前 story 的工作，应写入 BMad story follow-up，而不是创建 local issue。
- 影响多个 stories、需要人类决策、改变 PRD / SPEC / ADR / README 的事项，创建 local issue。
- 如果 issue 的解决会改变实现契约，`Resolution Target` 必须指向 `SPEC`、`ADR`、`PRD` 或 `README`。

## Gather Context

基于 conversation context 中已有内容工作。如果用户传入 issue reference（issue number、URL 或 path）作为参数，从 issue tracker 获取它，并读取完整 body 和 comments。

优先读取：

1. repo 中实际存在的 agent adapter，例如 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules/` 或 `.github/copilot-instructions.md`
2. `docs/agents/document-system.md`
3. `docs/agents/issue-tracker.md`
4. `docs/agents/triage-labels.md`
5. `docs/features/<feature>/SPEC.md`
6. `docs/features/<feature>/PLAN.md`（如果存在）
7. `docs/features/<feature>/PRD.md`

如果没有 `SPEC.md`，但任务需要实现行为、API、状态或数据契约，先运行 `/to-spec`，或只创建一个 HITL issue 要求人类补 Spec。

BMad Control Mode 还要读取相关材料：

- `docs/BMAD_INTEGRATION.md`
- `docs/LEVEL3_BMAD_WORKFLOW.md`
- `_bmad-output/implementation-artifacts/sprint-status.yaml`（如果存在）
- 相关 BMad story file、readiness report、code review 或 retrospective 输出

## Normal Mode

把计划拆成 **tracer bullet** issues。每个 issue 都是一个薄 vertical slice，end-to-end 穿过所有 integration layers，而不是某一层的 horizontal slice。

Slices 可以是 `HITL` 或 `AFK`。HITL slices 需要人类交互，例如 architecture decision 或 design review。AFK slices 可以无人交互地实现并合并。尽可能优先 AFK。

Vertical slice rules:

- 每个 slice 都交付一条窄但 COMPLETE 的路径，穿过每一层（schema, API, UI, tests）。
- 完成后的 slice 自身可 demo 或验证。
- 偏好多而薄的 slices，而不是少而厚的 slices。

把 proposed breakdown 作为编号列表展示。每个 slice 显示：

- **Title**：短描述名
- **Type**：HITL / AFK
- **Blocked by**：哪些其他 slices 必须先完成（如果有）
- **User stories covered**：覆盖哪些 user stories（如果 source material 中有）

询问用户：

- Granularity 是否合适？（too coarse / too fine）
- Dependency relationships 是否正确？
- 是否需要 merge 或继续 split 某些 slices？
- HITL 和 AFK 标记是否正确？

迭代直到用户批准 breakdown。

## BMad Control Mode

从 BMad 执行材料中提取控制面板 issues。不要拆 implementation queue；BMad story files 和 `sprint-status.yaml` 已经承担这个职责。

只创建这些 Issue Kind。写入 issue 时使用表格中的 canonical string：

| Issue Kind | 适合场景 | 通常状态 |
| --- | --- | --- |
| `blocker` | 不解决会阻塞一个或多个 BMad stories | `ready-for-human` 或 `needs-info` |
| `HITL decision` | 必须由人类裁决的产品、技术、设计或合规问题 | `ready-for-human` |
| `cross-story risk` | 影响多个 stories 的一致性、架构、测试或交付风险 | `needs-triage` 或 `ready-for-human` |
| `tech debt` | 当前 story 可完成，但留下跨模块或长期维护问题 | `needs-triage` |
| `review follow-up` | code review 发现的问题超出当前 story 修复范围 | `needs-triage` 或 `ready-for-agent` |
| `documentation fix` | PRD / SPEC / ADR / README 与实现或 BMad 输出不一致 | `ready-for-agent` 或 `ready-for-human` |

判断放 story 还是 issue：

| 问题 | 处理 |
| --- | --- |
| 当前 BMad story 内能直接完成，且只影响当前 story | 写入 BMad story follow-up |
| 影响多个 BMad stories | 创建 local issue |
| 需要人类裁决 | 创建 local issue |
| 改变长期契约或正式文档 | 创建 local issue，并设置 `Resolution Target` |
| 只是当前 story 缺少测试或实现细节 | 留在 story tasks / follow-up |

发布前展示 proposed control issues。每项显示：

- **Title**
- **Issue Kind**
- **Related BMad Stories**
- **Blocks BMad Stories**
- **Resolution Target**
- **Suggested Status**

询问用户这些事项是否真的应该脱离当前 story、是否遗漏受影响 stories、以及 resolution target 是否正确。

## Publish

对每个批准的 issue，把新 issue 发布到 issue tracker。对于本地 Markdown，写入 `docs/features/<feature>/issues/<NN>-<slug>.md`。

From pop1414/ai-native-doc-system, MIT.

More from pop1414/ai-native-doc-system