| 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、実行環境などが不足している候補は課題にせず に分離する。
