Issue Resolution Skill (Issue解決スキル)

概要

GitHub Issueを解決するための包括的なスキルです。 このスキルは単なる手順書ではなく、各フェーズにおける意思決定のフレームワークを提供します。 「どのように作業を進めるべきか」に迷った際、このスキルを参照して判断を行ってください。

基本方針

1. •Design First: コードを書く前に、必ず設計（既存ドキュメントの更新と実装計画の作成）を行う。
2. •Incremental Progress: タスクを細かく分解し、進捗を task.md で管理する。
3. •Visual Verification: UI変更や出力結果の変更を伴う場合は、必ず実環境へのデプロイ（/deploy）とURL報告を行う。
4. •No Regressions: マージ前に必ず main との差分を確認し、意図しない破壊的変更を防ぐ。
5. •Model Awareness: 要件定義・設計など思考力が求められるフェーズでは Claude4 Opus / Gemini 3 Pro 相当の深い思考を持つLLMを利用している。実装・テストなど手数が求められるフェーズでは Gemini 3 Flash を用いて低コスト、高スピードで実装できるようにする。
6. •デバッグ・モックの使い分け :原則デバッグモードで実行する。モックモードは本当にUIの微修正でのみ利用する。

🎭 意思決定プロセス

1. 準備フェーズ (PREPARATION)

• •Issueの理解: gh issue view <NUMBER> で背景と要件を深く理解する。
• •ラベリング: gh issue edit <NUMBER> --add-label "in-progress" で作業中であることを明示する。
• •ユーザへの通知(notify_user)
  • •賢いClaude4opusは実装まで見据えてポイントとなる点を質問するはずである。最低３つ質問する。必要に応じて大量に質問して良い。
  • •issueで理解したことを通知すること。

2. 計画・設計フェーズ (PLANNING & DESIGN)

• •設計ドキュメントの更新: docs/02_architecture/ 等を確認し、変更が必要なドキュメントを「事前に」更新する。
• •実装計画の作成 原則implementation_plan.md を作成する。実装・テストはgemini 3 Flashが行うため、詳細な計画とすること。原則モックモードではなくデバックモードでの確認を行う計画とすること。
• •タスク分割: task.md に具体的なステップを記述する。量が多い場合はphaseごとに分割すること。
• •ユーザーレビュー: 計画の妥当性について notify_user で承認を得る。

3. 実装・テストフェーズ (EXECUTION & TESTING)

• •ブランチ作成: feature/issue-<NUMBER>-<SHORT_TITLE> という命名規則に従う。
• •コード実装: 承認された計画に基づき実装を行う。フェーズごとに実装を行い、勝手に次のフェーズの実装まで進めないこと。フェーズ内のtaskは複数実行して良い。
• •実装の中断: 実装中に実装方針に迷ったら、すぐに実装を中断し、迷った点を通知すること。あなたは特に考えずに実装でるよう実装計画が作成されているため。
• •検証の実行:
  • •UIの修正のみの場合は/debug-run の設定（USE_MOCK_DATA=true）を選択する。具体的にはHTMLとtemplate、cssの修正である。
  • •GeminiGroundingの修正に関する修正の場合はUSE_MOCK_DATA=falseを選択すること。（デフォルトで良い）
  • •TARGET_DATE はスタメン確定済みの「2日以上前の日付」を指定する（詳細は /debug-run 参照）。
• •デプロイと確認:
  • •デプロイ前にcommitを行うこと。他のセッションも修正している可能性があるため、commitは修正したファイル・コードのみcommitする。
  • •/deploy ワークフローを使用して Firebase Hosting にデプロイする。
  • •デプロイ後のURLをcurlで取得し、デプロイされていることを確認する。
• •ユーザへの通知(notify_user)
  • •実装・テストフェーズが完了したことを通知する。
  • •ユーザーに walkthrough.md と共にWEB上のURLを報告する。
  • •実装するにあたって苦労したことも通知すること

4. 完了・レビューフェーズ (COMPLETION & REVIEW)

• •マージ前チェック (/check-close 相当):
  • •このタイミングではClaude4opusに切り替えて実施する。要件から改めて辿り直して実装・テストが妥当か批判的にレビューする。
  • •実装時のLLMの内部考察やテスト時のログから、要件からは外れているが、課題となることを洗い出す。
  • •要件の再照合: Issueの原文を再度読み返し、すべての依頼・提案・相談事項（特にデータの持ち方の提案など）に対応漏れがないかチェックする。
  • •残課題の確認: 会話の中で指摘された点に漏れがないか再確認する。
  • •差分確認: git diff main...HEAD を実行し、余計な変更がないか厳密にチェックする。
  • •ユーザの承認が得られるまで、マージフェーズの対応を行わないこと。

[!IMPORTANT] 📝 完了前のセルフチェックリスト

• • Issueのすべての要件（箇条書き以外の「相談・提示」等も含む）に応えたか？
• • 破壊的変更（パス・フォルダ名変更等）をした場合、実際に動かして（E2E）確認したか？
• • ユーザーに報告した walkthrough.md に、動作を証明するURLや実行結果が含まれているか？

• •ユーザへの通知(notify_user)
  • •解決状況の整理: 当該issueの課題と解決方針、結果を3列の表にまとめ、walkthrough.md に記載する。
  • •発見した要件外の課題を通知する。

5. マージフェーズ

• •4.におけるユーザの承認が得られてから進めること。ユーザはこの依頼をするときには、マージフェーズの対応をして、と言う。それ以外の場面では進めないこと。
• •マージとクローズ:
  • •commitされていない場合は修正内容とissue番号を明確にし、main にマージ・プッシュする。
  • •workflowの内容をもとに、Issueにコメントを追加のうえでクローズし、機能ブランチを削除する。
• •ユーザへの通知(notify_user)
  • •全体を振り返り、以下の観点でユーザーに通知する。
    • •事前指示文、AIとして与えられた指示文とやってみて無駄だったことや課題だったこと。

🛠️ 関連ワークフローへの参照

このスキルを実行中に、以下の固定手順（Workflow）を呼び出してください。

• •実行・検証: /debug-run
• •デプロイ: /deploy
• •クローズ確認: /check-close
• •プロンプト調整: /tune-gemini
• •不備修正: /delete-report

📝 コミットメッセージのテンプレート

feat(#123): 実装内容の要約

- 詳細変更点
- ...

Closes #123