fix-github-issue reference

fix-github-issue は、既存の GitHub Issue 1 件を実装し、検証、review、PR 作成まで進める skill です。

対象読者と使いどころ

まず何が起きるか

1. Issue の担当者、依存関係、受け入れ条件、非ゴールを確認します。
2. 実装範囲と検証方法を決め、必要な場合だけユーザーに質問します。
3. 実装、通常検証、PR 前 simplify を行います。
4. PR 前 simplify とそこで生じた変更の commit の後、review、push、PR 作成の前に fix-code-comments skill を実行します。対応言語の変更が無い branch でも省略せず、review 指摘の対応で HEAD が変わった場合は push 前に再実行して run record を最新 HEAD に揃えます。
5. 指定された review を行い、PR を作成または更新して review と CI を確認します。
6. 指定された E2E を行い、結果を PR と完了記録へ反映します。

停止条件

• 別の担当者が claim 済み、または依存 Issue が未完了の場合。
• 受け入れ条件、非ゴール、公開 API、設定形式、画面上の挙動に複数の完了形がある場合。
• readiness gate、review、CI、E2E の required action が残る場合。
• Issue と linked Cosense design doc が矛盾する場合。
• dirty worktree や branch 衝突があり、安全に作業を続けられない場合。

詳細 contract

公開ページには、利用者が選ぶ option と停止条件だけを記載します。Agent が使う command、artifact schema、復旧手順は次の source of truth を参照してください。

人間判断 gate

• human action が必要な場合は次の該当経路へ戻す。

PR mode

• PR 作成後は最新 HEAD の review と CI を確認する。billing、runner、GitHub Actions service の障害は infrastructure failure として分けて報告する。
• drift-check で「変更してはいけない契約」と受け入れ条件を確認する。unmet は required action とする。
• design doc は作成時点のスナップショットとし、進捗と PR は GitHub Issue 側を source of truth とする。design doc 本文にも readability gate を適用する。

research packet

• packet が古い、複数ある、または対象 Issue と一致しない場合は自動採用しない。

design doc の記録

• Issue に design doc の実 URL がある場合は、repo-scoped record、flat compatibility record、page 本文の legacy record の順で authoring 記録を探す。
• 対象 Issue の record を先に探し、見つからない場合だけ Parent の共有 record を探す。flat record は repository、Cosense project、page title も一致する場合だけ使う。
• 同じ優先順位の候補が複数ある場合や記録同士が矛盾する場合は、readiness で停止する。
• Issue に design doc の実 URL がない場合は、flat record を推測で採用しない。

triage skip

• implementation brief が change_scale=trivial で、risk と未確定事項がない。
• acceptance、validation_commands、candidate_files がそれぞれ1件以上ある。
• Design doc section に実 URL または承認済みの省略理由がある。
• design doc を正当に省略した Issue に link は要求しない。
• 変更行数が 20 を超える（lines_added+lines_deleted<=20 を満たさない）、または変更ファイル数が 2 件を超える場合は通常の triage に戻る。
• readiness と drift 確認は省略しない。

review mode

local reviewer と GitHub reviewer

• agents= と reviewers= は別の selector とする。
• task ledger 開始時は pr_mode、review_mode、agents、e2e_mode、smoke_mode を同じ durable state revision に保存する。現在の Codex thread ID または Claude Code session ID を取得できる場合は、workflow kind / ID と role=implementation の session binding も保存する。resume 時は保存済み selector を優先し、部分的な legacy state だけ不足分を補完する。
• implementation-status は live binding の再検証結果を selector backfill と同じ revision に保存してから判定する。selector mismatch または保存失敗時は後続へ進まない。
• Stop hook は明示 workflow identity または current session binding と role=implementation を branch 推定より優先する。保存済み selector と canonical artifact ref を CompletionCheckOptions へ変換し、issue completion-check と同じ evaluator の結果を canonical_completion に記録する。reviewer、verifier、subagent、read-only research と、durable state が無い branch-only inference は no-op にする。
• required mode では issue completion-check と同じ canonical 判定を effective exit に使う。旧判定は legacy_decision に残し、shadow_decision と divergence に比較結果を記録する。
• issue completion-check は実行のたびに fix-code-comments の run record を照合し、comment-check-observation.v1 を state root の repository 単位 path へ保存して、stdout に summary を additive に含める。この観測は report_only で、required_action を追加せず完了判定と exit code を変えない。base は optional な --base-ref で明示でき、省略時は origin/main との merge-base を使う。
• review=once の agents= は codex、claude、copilot のいずれか 1 件だけを指定する。
• review=on で local reviewer と GitHub reviewer のどちらも実行できない組み合わせは停止する。
• no-copilot-bot は旧互換の Copilot bot opt-out とする。

E2E option

• e2e=final|both では、final E2E の成功またはユーザーが明示した skip がなければ完了扱いにしない。通常検証や review の成功は E2E の代わりにしない。
• e2e-apply=confirmed は handoff / checkpoint に保持し、resume command に e2e-apply=confirmed を復元する。
• 承認として使えるのは、ユーザーの直接入力と、その入力から同じ task 内で作成した handoff / checkpoint に限る。
• 単独の e2e_apply 値や handoff_context は承認根拠にしない。needs_user_decision として停止する。
• 未指定時は従来どおり実行前にユーザー確認する。

worktree option

• 既存 worktree を再利用する場合も、編集前に branch と clean state を確認する。

stacked PR の親

stack=<PR number|PR URL> は同じ repository の open PR を親として指定します。stack=auto または stack=true は、対象 Issue の親 Issue にある実装順序表と依存 Issue の PR から、親 PR が一意な場合だけ自動解決します。

解決した親 PR、base branch、base OID は worktree、review、PR 作成へ引き継ぎます。PR 作成直前に再検査し、親 PR の更新、複数候補、PR 未作成、fork、別 repository、既存 stack の途中への挿入が見つかった場合は停止します。

stack=auto は logical dependency PR と、検証済みの effective_tail_candidate を区別して返します。途中の sibling PR を観測しても legacy parent_pr_not_top を維持し、後続 coordinator が使う publication_order_snapshot、chain_root_status、stack_members を追加 evidence として残します。

publication coordinator を使う経路では、ready intent を凍結順に lease します。required mode は clean かつ未 push の branch だけを effective tail 上へ積み直し、restack 後の HEAD で validation、review、E2E をやり直します。conflict、tail drift、期限切れ、effect 不明では push せず、保存済みの resume または abort action に戻ります。

親 Issue の表が更新された場合は、未公開 intent の row と相対順を再確認します。相対順が同じなら snapshot と Phase を更新し、並び替えまたは row 消失なら publication_order_stale で lease と branch の変更前に停止します。

復旧するときは、親 Issue の表で元の相対順と欠けた row を復元してから、resolver と intent 登録をやり直します。順序変更を維持する場合は、既存 intent を resume または abort の手順で解決してから、新しい順序で登録します。

standalone の auto stack は、対象になる resolution を root owner の publication intent として登録します。commit 後に current branch と HEAD を ready にし、先行 intent がある間は status と heartbeat を続けます。順番が来たら prepare から同じ session で再開し、restack 後の HEAD が変わった場合だけ validation、simplify、review、E2E を再実行します。

計測と独立 review を通過したため、明示 stack=auto|true の publication gate と closing Issue gate は required です。generic resolver と selector 未指定経路の legacy 既定値は変更しません。

false stop、unsafe pass、duplicate publication、順序違反、closing Issue の誤停止または見逃しが 1 件でも観測された場合は、両 gate を report-only に rollback します。残存 publication intent は計測 artifact に記録して abort し、required registry へ持ち越しません。

required coordinator の worker は implementation と publication-finalization を分けます。implementation は commit までで止まり、finalization は保存済み intent から prepare を再開します。gate timeout は validation、simplify、review、E2E の有限上限を lease 用に合算するもので、gate 自体の実行時間を打ち切りません。

PR 作成前の再検査では legacy parent_pr_not_top artifact も読み直せます。ただし candidate の変化だけで resolved や stale に読み替えず、resolved artifact の parent PR、branch、OID が変わった場合だけ parent_pr_stale にします。

stack と stack-base は同時に指定できません。どちらも未指定なら default branch 起点の既存手順を維持します。

branch を直接指定する互換経路

stack-base=<branch> を指定すると、先に対象 branch を fetch し、origin/<stack-base> を worktree または branch の起点にします。同じ branch を review-profile-plan、local review、create-pr にも渡します。

既存 linked worktree は、clean で origin/<stack-base> が HEAD の祖先になっている場合だけ再利用します。条件を満たさない場合は、自動 rebase や追加 worktree の作成を行わず、必要な操作を案内して停止します。

未指定時は stack-base による上書きを行わず、作業起点、review base、PR base の各既存手順を維持します。

実行例

関連

• Issue workflow skill guide
• task-research reference
• implementation readiness contract
• E2E auto policy contract
• review operations