| name | issue-driven-dev-loop |
| description | Use when working through a backlog of issues one by one — picking up an issue, refining its design, implementing, opening a PR, updating issue status after merge, and moving to the next. Covers local file-based .issues/ trackers (meta.yaml, status-as-directory), design-confirm-implement loops, branch/commit conventions, draft PRs with CI follow-up, and parallelizing independent issues with subagents. |
Issue 驱动开发循环
围绕本地 .issues/ 目录（或 Linear 等外部 tracker）的完整开发循环：领取 issue → 细化设计并确认 → 实现 → 提交 PR → merge 后更新状态 → 继续下一个。
1. Issue 的组织方式（本地 .issues/）
.issues/
├── .config.yaml # prefix、init_number
├── backlog/ # 全局未排期
├── v0.5.0/ # 里程碑目录
│ ├── milestone.yaml
│ ├── backlog/ todo/ in-progress/ in-review/ done/ cancelled/
└── _archive/ # 已关闭里程碑整体移入
- 单个 issue 是一个目录（如
ISS-401/，前缀由 .config.yaml 定义），内含 meta.yaml（必需，唯一 source of truth）+ 按需的 design.md（既定方案）、discussion.md（时间倒序讨论日志）、notes.md（实施期偏差决策，不改写原始定义）。
- 状态流转 = 物理移动目录，同时必须同步
meta.yaml 的 status 字段（双冗余，两处都要改）。
meta.yaml 关键字段：id、title、type(feature|bug|chore|refactor|docs)、priority(P0-P3)、status、milestone、pull_requests[](url/status/branch)、depends_on/blocks、completed_at、summary。- 定位 issue 永远先
find .issues -type d -name "ISS-401"，不要假设它在哪个状态目录。
2. 开工序列（不要拿到 issue 就写代码）
- 读约束文件：issue-tracker 的 SKILL/格式说明、commit 规范、项目
AGENTS.md。
git status --short --branch 确认在干净的 main。- 盘点 backlog：读全部
meta.yaml + design.md。
- 按「谁为谁建立契约边界」推导依赖顺序，而不是按编号或优先级机械排序，写出处理计划。
- 已有详细设计的 issue 直接实现（用户可预授权「待确认项采用默认方案」）；需细化的走：扩写 design.md 并把不确定项标「待讨论决策」→ 用户拍板 → 先去代码核实再写回文档（避免写虚）→ 把「待讨论」改为「明确决策」→ 用户确认后才动代码。待确认事项必须固化进 design.md，不能只留在对话里。
3. 分支与 commit
- 模式由用户指令决定：
- 一 issue 一 PR：独立分支
feat/{issue-id}-{slug}（如 feat/iss-42-windowed-data-load）。
- 直接 main：不开分支，靠合理拆分 commit + issue 状态推进；commit body 加
Refs: ISS-xxx 追溯，可带 Verification: <验证命令>。
- commit 遵循约定式提交：类型前缀 + 可选 scope（
fix(web):），subject 祈使语气、首字母大写、≤50 字符、无尾标点。一个逻辑边界一个 commit，绝不混两个 issue。
- 修 bug 铁律：先加日志读运行时输出，再改代码——插临时标记日志（如
[ISS-42]），跑测试读真实执行顺序确认根因，不静态猜测。
4. 提交 PR
git push -u origin <branch>。- 创建 draft PR（默认 draft，不直接 open）；有
.github/pull_request_template.md 则套模板。
- PR 标题：约定式提交格式、英文小写；PR 正文英文，结构：
## Summary / ## Root cause(bug 类) / ## Impact / ## Validation(验证命令) + 结尾 Issue: ISS-42。
gh pr view <branch> --json number,url,state,isDraft 回读确认。- 建 PR 后立即回写 issue：status
in-progress→in-review，追加 pull_requests 条目，mv 目录到 in-review/。
- 跟进 CI：失败则读日志定位、本地修复补 commit push；根因具有普遍性时把预防规则写进 AGENTS.md 防复发。
5. Merge 后收尾与下一个
gh pr view <n> --json state,mergedAt 核实确已 MERGED。- 更新 meta.yaml：
in-review→done、PR status→merged、填 completed_at；mv 到 done/。
git switch main && git pull，从最新 main 建下一分支。- 按依赖顺序取下一个 issue，
mv 到 in-progress/，循环。
- 里程碑发布后经确认将整个里程碑目录
mv 到 _archive/。
6. 并行处理（大批量 backlog）
主 agent 先画依赖图，把写入文件范围互不重叠的 issue 分给 worker 子代理并行；每个子代理指令强制：不创建分支、不提交 commit、不改 .issues/、不 revert 他人改动、只改指定文件。返回后主 agent review diff 统一提交。会改同一文件群的 issue 必须串行。
7. 关键坑位清单
