resolve-issue Skill

概要

1つのIssueを1つのPRで解決します。PRは2段階で育て、段階ごとに別のセッションで実行します（設計者と実装者を分けるため）。

• 正本は Issue の受入条件です。 テストはその写しで、設計ドキュメントはAIが実装を間違えないための補助です。どちらも合意の対象ではありません。
• 段階2のセッションは段階1の会話を持ちません。段階1で決めたことは すべて Issue と PR に書き残します。ファイル（PLAN.md など）には残しません。
• 段階2へ進む合図は、人がセッションを作り直す（または /clear する）ことと、同じIssueでこのスキルを呼び直すことです。

使い方

/resolve-issue <issue番号>

段階の判定

1. gh issue view <番号> --comments でIssueを読む。
2. 対応するPRを探す（gh pr list --head <ブランチ名>、見つからなければ gh pr list --search "#<番号>"）。
3. 状態で分岐する。
   • PRが無い → 段階1
   • Draft → 段階2。呼び直されたこと自体を、受入条件が承認された合図とみなす
   • Ready for review → 「Ready for review の後: 指摘に対応する」に従う

段階1を終えたのと同じセッションで呼ばれた場合は、段階2に進まず、セッションを作り直してから呼び直すよう伝える。

段階1: 受入条件を固める

1. ブランチを作る。AGENTS.md に指示（worktree を使わない、など）があれば従う。名前は fix/issue-<番号> または feature/issue-<番号>。
2. 受入条件を見直し、Issue本文を更新する。
   • 計算・変換・入力チェックなど、入力から結果が決まるものは 入力と期待結果の表 にする。表を書こうとして決まらない行（境界値、欠けたデータ、異常系）は推測で埋めず、期待結果を ？ のまま残す。
   • 振る舞いではない条件（「テストを書く」など）は受入条件から外す。品質は test-code が担う。
   • 見た目・操作感など表にできないものは、チェックボックスの箇条書きで残す。UATで人が参考にする項目になる。
3. 変更が設計に関わる場合は design-docs で該当ファイルを更新する。
4. コミットして push し、create-pullrequest で Draft PR を作る。設計ドキュメントの差分が無い場合は git commit --allow-empty で空のコミットを作る。本文の冒頭に、確認してほしいこと（受入条件の表、？ の行）を並べる。
5. 段階2の実装者が知る必要のあること（調べて分かった制約、選ばなかった案とその理由）を、PR本文か PRコメントに書く。
6. 人に受入条件の確認を頼んで止まる。確認が済んだら、セッションを作り直して同じIssueで呼び直すよう伝える。

段階2: 実装する

1. Issue本文、PR本文、Issue と PR のコメントを読み、段階1で決めたことと人のレビューを把握する。？ の行が残っていて答えも無ければ、実装に入らず人に問う。
2. 実装前のテストの成否を記録する（後で「元々失敗していたテスト」と「新たに壊したテスト」を区別するため）。
3. test-as-tdd に従い、テストとプロダクトコードを交互に書く。
   • テストの種類（単体、UI、E2E）と書き方は、プロジェクトの既存のテストに合わせる。受入条件のために新しい規約を作らない。
   • 受入条件の表の行は、テストのデータとしてそのまま写す。テスト名か説明に条件番号を含め（例: 条件2: JSONにない馬番は既存のまま残す）、人が Issue の表と見比べられるようにする。
4. 受入条件を自分の判断で変えない。 実装中に受入条件が間違っていると判断したら、理由と修正案をPRコメントで示し、人の判断を待つ。受入条件の変更は人が決める。
5. 実装後に設計ドキュメントとコードが食い違ったら、コードを正としてドキュメントを直し、その旨をPR本文に書く。
6. test-code で品質ゲートを通す。手順2で記録した元々の失敗は無視してよいが、新たに失敗するようになったテストは直す。
7. コミットして push し、PR本文を更新する（動作確認、受入条件ごとの対応するテスト）。Draft の間は、コミットのたびに push してよい。
8. Ready にする前に、push するものをすべて片付ける。品質ゲート、PR本文、自動チェック（セキュリティレビューなど）の指摘への対応まで終えて push してから、gh pr ready <PR番号> で Ready for review にする。Ready の後の push は CI のやり直しになるため（次節）。マージはユーザーの判断で、このスキルの範囲はここまで。

Ready for review の後: 指摘に対応する

Ready の PR への push は、ひとまとまりの対応ごとに1回 にする。push するたびに実行中の CI が取り消されて最初からやり直しになり、途中の状態でレビュアーに通知も飛ぶため。CI の所要時間など、リポジトリに固有の事情は各リポジトリの AGENTS.md に従う。

1. PR のレビューとコメントを読み、そのとき来ている指摘をすべて把握する。自動チェック（セキュリティレビューなど）の指摘も、人のレビューの指摘と同じに扱う。
2. 指摘をすべて直す。直し方は段階2の手順3〜5に従う。コミットは指摘ごとに分けてよいが、1件直すたびに push しない。
3. test-code でローカルの品質ゲートを通す。
4. 1回 push し、create-pullrequest で PR本文の動作確認を更新する。

まれに次の状況になる。

• 直している途中で新しい指摘が届いた: 新しい指摘も含めてすべて直し、品質ゲートを通してから1回 push する。途中で push しても、次の push で CI が取り消されるため。
• 指摘の一部が人の判断待ち: 直した分を先に1回 push し、判断待ちの指摘は PRコメントで問う。判断が出て直したら、もう一度 push する。判断を待つと、直した分の検証が止まるため。

コミット

コミットメッセージに Issue 番号を含める（Refs #<番号>）。PR本文に Closes #<番号> を書く。

出力形式

各段階の終わりに、PRのURLと人に見てほしいことを示す。

• 段階1: ？ の行と確認してほしい受入条件、そして「確認後にセッションを作り直して呼び直す」こと
• 段階2: UATで参考にする受入条件

他のスキルとの関係

サンプル対話

User: /resolve-issue 44

Agent: Issue #44 を確認しました。PRはまだ無いので、段階1から始めます。受入条件の2番目を表にしたところ、「既存のレースにあってJSONに無い馬番をどう扱うか」が決まっていなかったので ？ にし、Issue本文を更新しました。Draft PR を作成しました。URL: ... 表の ？ の行をご確認ください。確認が済んだら、セッションを作り直して /resolve-issue 44 を呼び直してください。

User: （Issueに「JSONに無い馬番は残す」とコメントし、/clear してから）/resolve-issue 44

Agent: Draft PR があるので段階2として進めます。Issueのコメントから、？ の行は「既存のまま残す」と読み取り、Issue本文の表を確定しました。TDD でテストと実装を進め、品質ゲートを通したうえで Ready for review にしました。URL: ... UATでは Issue の受入条件を参考にご確認ください。