| name | issue-finder-playbook |
| description | Issue Finder agent がコードベースを変更せず、指定された finder 分野の課題を根拠付きで調査し、優先順位付けした Markdown を指定ディレクトリへ出力するときの共通手順、安全制約、品質基準、出力 contract を定義する。 |
Issue Finder Playbook
対応する role-*-finder-playbook と併用する。分野別 playbook は「何を課題と判定するか」、この playbook は「どう調査し、どう出力するか」を所有する。
制約
- ソースコード、設定、既存ドキュメントを変更しない。
- 書き込みは依頼で指定された出力先だけに限定する。未指定時は
/tmp/issue-finder/ を使う。
- 指定先へ安全に書き込めない場合は、別の場所へ無断で出力せず、利用者へ報告する。
- ビルド、テスト、静的解析などの非破壊的な検証だけを実行する。リポジトリ内に生成物や更新を残すコマンドは避ける。
- 認証情報や秘密情報を収集・記録しない。外部サービスへ書き込まない。
- 最新情報が必要な場合だけ読み取り専用の web search / browser を使う。shell command から外部通信せず、公式情報や一次情報を優先し、URL と確認日を記録する。
入力 contract
依頼から次を確定する。
- finder 種別: 対応する分野別 playbook で決定する。
- 調査対象: 指定がなければ現在のリポジトリ全体。パス、差分、commit、PR などの指定があれば限定する。
- 出力先: 指定がなければ
/tmp/issue-finder/。指定先を canonical path に解決し、symlink を含まず、解決後も $TMPDIR または /tmp 配下にある場合だけ使う。それ以外が指定された場合は、system temporary directory 配下の出力先を利用者に指定してもらう。
- 最大課題数: 指定がなければ10件。
調査対象、除外対象、未調査領域を成果物に明記する。「リポジトリ全体」は完全性の保証ではなく、実際に確認した範囲を併記する。
調査
- リポジトリの指示、README、仕様、構造、実行・検証方法を確認する。
- Git repository では開始時の status と diff を記録し、既存変更を識別する。
- 分野別 playbook の探索観点から候補を集める。
- 各候補について、該当箇所、関連する contract、呼び出し経路、テスト、履歴を必要な範囲で追跡する。
- 再現、静的な因果関係、仕様との不整合など、第三者が追跡できる根拠を確認する。
- 参照可能な既存 Issue、TODO、課題文書との重複を確認する。GitHub Issue はリポジトリが接続され、読み取り可能な場合だけ確認する。
- 課題を重要度、確信度、影響範囲で優先順位付けする。
- 終了時の status と diff を開始時の記録と比較する。検証コマンドが生成・変更したファイルを区別し、コードベースへ新たな変更が残った場合は完了扱いにしない。
件数を満たすために弱い候補を課題へ昇格させない。
判定
課題
再現可能な事象、仕様との矛盾、またはコードから追跡できる因果関係があり、影響と解決方針を説明できる候補だけを課題とする。
調査継続候補
問題の可能性はあるが、成立条件、contract、実行環境などが不足している候補は課題にせず investigation-needed.md に分離する。
重複
既存課題と実質的に同じ候補は新規課題にせず、duplicates.md に既存課題への参照と今回得た追加根拠を記録する。
評価尺度
重要度は Critical / High / Medium / Low、確信度は High / Medium / Low を使い、判定理由を必須にする。重要度の具体的基準は分野別 playbook に従う。
- Critical: 広範囲または不可逆な重大影響が直ちに成立する。
- High: 主要な利用経路、データ、運用、安全性に大きな影響がある。
- Medium: 条件付きまたは限定範囲だが、計画的な対応が必要である。
- Low: 影響は小さいが、放置すると明確なコストや不整合が残る。
出力 contract
課題ごとに <finder種別>-<対象名>-<YYYYMMDD-HHMMSS>-<slug>.md を作成する。finder種別、対象名、slug はそれぞれ英小文字、数字、ハイフンだけへ正規化し、先頭・末尾のハイフンを除去する。path separator、.、..、空白、絶対 path を含めず、正規化後のファイル名が出力先直下にあることを確認してから書き込む。slug は課題ごとに一意にする。
各課題ファイルへ次の順で記載する。
- タイトル
- finder 種別
- 概要
- 調査対象と確認範囲
- 根拠: ファイル、行、symbol、コマンド結果、仕様、外部資料を追跡可能に示す
- 発生条件または問題になる状況
- 影響
- 重要度と判定理由
- 確信度と判定理由
- 既存課題との重複確認
- 解決方針
- 未解決事項
最大件数を超えた有力候補は additional-candidates.md に概要、根拠、優先順位を記録する。課題がなければ no-findings.md に調査範囲、実施した検証、未調査領域を記録する。補助ファイルが不要なら作成しない。
Modification Design
変更方針が一意に明確で、利用者の仕様判断が残らず、現在の責務、公開 interface、contract、依存関係を根拠から確定できる場合は、modification-design を使い、その規定8章を課題ファイルの「Modification Design」以下へ完全に含める。境界判断では lego-programming を併用する。
複数の解決案から利用者の判断が必要な場合や、設計を左右する情報が不足する場合は Modification Design を推測で作らず、選択肢または不足情報を「未解決事項」と investigation-needed.md に記録する。
完了報告
出力先、作成した課題数、補助ファイル、最重要課題、未調査領域を利用者へ報告する。コードベースを変更していないことを確認して明記する。
