github-issue-driven

name	github-issue-driven
description	Use when starting work on a GitHub issue — scanning or claiming an open issue, or when the path from issue to merged PR isn't clear. Use BEFORE diving into implementation of an issue.

GitHub Issue Driven

处理 GitHub issue 的标准研发闭环：issue → 调研 → 设计 → 实现 → CR → 合并。JFox 知识库是调研中枢，superpowers 处理设计与实现，Zima 单 Bot CR 把关合并（cc/pi 版共存，按 review meta 前缀区分；kimi 已移除，见 [[Zima CR 体系单 bot 化]]）。

When to use

• 会话开始要找事做（扫 open issue）
• 认领了一个 issue，要从头走到合并
• 不确定某个 issue 该走什么流程

10 步流程（每步指向对应 skill / 命令）

1. 扫 issue：gh issue list --repo <owner>/<repo> --state open --json number,title,labels,body
2. 认领：gh issue edit <N> --add-assignee @me（评论说明开始处理）
3. 纯调研 → REQUIRED SUB-SKILL: Use issue-research（JFox KB + git + 过往 issue/PR；多轮，每轮一主题，结论评论到 issue；调研文件放 ~/.claude/github-issue-driven/<owner>/<repo>/issue-<N>/research/）
4. 路由：bug → systematic-debugging；新需求/功能 → brainstorming（均为 superpowers 包技能）。产 spec / 根因报告，draft 在 ~/.claude/github-issue-driven/<owner>/<repo>/issue-<N>/spec.md（和 research 一样不进 main）。⏸ spec 完成后暂停，等用户确认设计再继续。
5. 进 worktree（spec 批准后 · 强制）：写代码前的隔离关卡——
   • 首选（pi）：调原生 git_worktree 工具 action: "open"，path: "./.pi/worktrees/issue-<N>-<shortslug>"，branch: "issue-<N>-<shortslug>" → 工具在 <repo>/.pi/worktrees/ 创建 worktree，并开一个新 Pi session（cwd 落在 worktree 内）继续后续步骤。pi 的 session cwd 固定，不能用切目录的方式进 worktree。
   • 兜底（无 git_worktree 工具）：git worktree add <repo>/.pi/worktrees/issue-<N>-<shortslug> -b issue-<N>-<shortslug>，再 cd <path> && pi 开新 session。
   • 把 spec 落进 worktree 的 docs/superpowers/specs/<YYYY-MM-DD>-<slug>-design.md，作为首个 commit。（spec draft 在 ~/.claude，main 从无该文件 → 零搬运。）
   • 命名：issue-<N>-<shortslug>，shortslug 取 issue 标题转小写 kebab-case（只留字母数字与 -）；总长 ≤64 字符；无 feat//fix/ 前缀、无 /。例：issue #309「gem-synth dedup incremental merge」→ issue-309-gem-synth-dedup-incremental-merge。
   • 🚫 禁止 git checkout -b / git switch -c / git branch <name>（只是在当前 checkout 切分支，不是 worktree）。
   • 自检：pwd 在 <repo>/.pi/worktrees/ 下（或 git rev-parse --git-dir 指向 linked worktree），否则停下先建。
6. 写计划 → REQUIRED SUB-SKILL: Use writing-plans（在 worktree 内）→ docs/superpowers/plans/<YYYY-MM-DD>-<slug>.md。
7. 实现 → REQUIRED SUB-SKILL: Use subagent-driven-development（worktree 内，禁碰 main）。🚪 Gate：Step 6 的 plan 文档必须存在才能开始实现——spec 不算 plan。 派 implementer 时把 worktree 绝对路径填进 Work from:，别让 subagent 回主仓库作业。
8. 本地快速 CR → requesting-code-review（superpowers）或 pi 原生 workflow 工具的 code-review 模式（agent 按问题复杂度自选深度；必做，深度自定）
9. PR + Zima 单 Bot CR + 前台阻塞等待 → REQUIRED SUB-SKILL: Use zima-pr-monitor（开 PR、打 zima:needs-review、同 turn 立即前台阻塞等待 CR job 完成（禁止结束 turn，helper 见 zima-pr-monitor）、解析 review meta（cc-cr-meta / pi-cr-meta 前缀区分；kimi-cr-meta 忽略）、worktree 修、重打标签、收敛判定、合并）
10. post-merge：结束 worktree session（回主仓库 session）→ git_worktree action: "remove"（或 git worktree remove <repo>/.pi/worktrees/issue-<N>-<shortslug>）→ git worktree prune → git checkout main && git pull（release / 部署 / 配置 = 人工，不在自动化环内）

为什么高度可自动化

调研（步 3）做细 + JFox KB permanent 笔记够厚 → 步 4 brainstorming/system-debugging 基本已有答案（少澄清）→ 步 6-10 近乎自动。瓶颈是调研质量 + KB 厚度，不是流程本身——平时往 JFox 沉淀 permanent note = 给未来自动化攒燃料。

关键纪律

• main 永远干净：所有仓库产物（spec/plan/code）从 Step 5 起在 worktree 内产生并提交。Step 4 的 spec draft 在 ~/.claude/github-issue-driven/<owner>/<repo>/issue-<N>/（同 research 纪律），不落 main。该目录是全局约定目录，pi 与 Claude Code 会话共用同一份调研（跨 harness 可复用）。
• spec ≠ plan（不可混淆）：spec = 设计（决策表/数据流/组件契约/降级/非目标）；plan = 任务拆解（有序 task、文件级改动、每步验证）。spec 再详也不算 plan，Step 6 不可跳。
• worktree 命名：issue-<N>-<shortslug>，无 feat//fix/ 前缀、无 /、总长 ≤64 字符；禁止 git checkout -b / git switch -c 在主 checkout 切分支。
• git add <file> 按文件 stage，别用 git add -A（会把 untracked 临时文件 sweep 进 commit）。
• 调研/spec draft 不进项目目录（会污染 commit），放 ~/.claude/github-issue-driven/...。
• issue 的调研结论要评论回 issue 区（留轨迹）。