issue-resolver

name	issue-resolver
description	不具合報告（GitHub Issue、フォーラム投稿、社内報告）を起点に、調査・再現・修正・検証・記録までを一貫実行するスキル。症状の切り分け、原因仮説の整理、最小再現、修正実装、ExecPlan作成、PR下書き、ナレッジ追記が必要なときに使う。

Issue Resolver

不具合対応を「再現可能な事実」ベースで前進させる。 実装規約はプロジェクトの AGENTS.md を最優先とし、必要に応じて project-worker の規約へ委譲する。

実行ルール

1. 先に現象と期待値を定義してから実装する。
2. 推測で修正せず、再現手順か観測ログを必ず作る。
3. 変更は最小単位に分割し、影響範囲を明示する。
4. 修正方針を先に判定し、軽微な修正は ExecPlan 作成を省略して implement-fix へ進んでよい（ただし調査報告への承認後に限る）。
5. 問題が分かりにくい場合、影響範囲が読みにくい場合、または実装が複雑な場合は .agent/PLANS.md に従って ExecPlan を作成する。
6. 不具合調査では手動確認より先に docker compose exec <app-service> php evo でシステムログ・設定・DB状態・キャッシュ状態を確認する。
7. このスキルはローカル開発環境専用とし、本番環境を前提にした慎重運用は行わない。本番環境にAIを常駐させたり、本番ログを直接解析したりする前提は置かず、開発環境で再現したエラーを構造化ログから調査する用途を主目的にする。
8. 調査と修正は効率優先・トークン節約優先で進め、過剰な説明や確認を省く。
9. 検証に必要な範囲でローカルDBの更新・削除・初期化を許容し、必要なら即時にリセットする。
10. フォーラムURLの本文取得は最初から制限外実行で行い、curl / wget を順に試す。
11. URL取得コマンド実行時は都度 require_escalated を使い、承認付きで実行する。
12. Could not resolve host や Temporary failure in name resolution はサンドボックス内制限として扱い、制限外実行へ切り替える。
13. URL取得に失敗した状態でローカルコードだけから原因を推測しない。取得不能時は必ずエンジニアへ対応（本文提供・制限外実行）を依頼する。
14. 原因が判明した時点で必ず先に調査報告を提出し、エンジニア承認前に修正へ進まない。
15. evo コマンドとDB参照はホスト側で直接実行しない。必ず Docker コンテナ内で実行する。
16. エラー隠蔽を目的とした修正を禁止する。警告/例外を消すための握りつぶしや無条件の値変換を行わず、原因となる不正データの発生源を修正する。
17. 例: strpos() に null が渡って落ちる場合、null を空文字へ変換して通すのではなく、null が渡る経路を特定して上流で是正する。

evo CLI（実用最小）

• docker compose exec <app-service> php evo log:tail [--lines=N] [--level=error]
• docker compose exec <app-service> php evo log:search <query> [--limit=N] [--level=error]
• docker compose exec <app-service> php evo config:show <key>
• docker compose exec <app-service> php evo db:describe <table>
• docker compose exec <app-service> php evo db:count <table> --where=...
• docker compose exec <app-service> php evo db:query "SELECT ..."
• docker compose exec <app-service> php evo cache:clear

詳細リファレンスは manager/includes/cli/README.md を参照する。 本番接続情報や本番データを扱う前提は置かない。

システムログ調査の使い分け

• 直近の失敗を確認する: docker compose exec <app-service> php evo log:tail --lines=20 --level=error
• 既知の文言・ファイル名・関数名から探す: docker compose exec <app-service> php evo log:search <query> --limit=20
• AI解析用に構造化データを確認する: docker compose exec <app-service> php evo log:tail --lines=5 --json
• ログ種別は既定で system。明示が必要な場合のみ --type=system を使う。
• 本番環境のログを直接読む運用は想定しない。必要な場合は、再現環境で同じ操作を行ってログを生成するか、ユーザーから貼り付けられたログ断片を入力として扱う。

管理画面のHTTP検証メモ（curl利用時）

• manager/index.php や manager/processors/login.processor.php へのリクエストには Accept-Language ヘッダを付ける（未指定だと 404 が返る）。

Workflow

analyze-issue <URL|テキスト>

1. 入力が URL の場合は、最初の取得を制限外実行（承認付き）で行う。
2. 取得コマンドは curl -fsSL -A "Mozilla/5.0" "<URL>" | php -r '$h=stream_get_contents(STDIN); $t=strip_tags($h); $t=preg_replace("/\s+/u"," ",$t); echo trim($t), PHP_EOL;' を使う。
3. curl が失敗した場合は、制限外実行（承認付き）で wget -qO- "<URL>" | php -r '$h=stream_get_contents(STDIN); $t=strip_tags($h); $t=preg_replace("/\s+/u"," ",$t); echo trim($t), PHP_EOL;' を実行する。
4. 取得したテキストから事実情報（環境、手順、実際結果、期待結果）を抽出する。
5. AGENTS.md のドキュメントマップを参照し、関連コンポーネントと確認ドキュメントを特定する。
6. 開発環境で再現済み、または直前に操作した不具合なら docker compose exec <app-service> php evo log:tail --lines=20 --level=error で直近の構造化ログを確認する。
7. 報告文にエラーメッセージ・ファイル名・関数名がある場合は docker compose exec <app-service> php evo log:search <query> --limit=20 で該当ログを探す。
8. ログから原因箇所を読む必要がある場合は --json を付け、context.error / context.exception / context.fatal / context.caller を優先して確認する。
9. docker compose exec <app-service> php evo config:show <key> で関連設定値を確認する。
10. docker compose exec <app-service> php evo db:describe <table> で対象テーブル構造を確認する。
11. 必要時のみ docker compose exec <app-service> php evo db:count <table> --where=... で件数を確認する。
12. 現象の要約、再現条件、観測ログ、原因仮説（最大3件）を作る。
13. 原因が判明した場合は、修正前に「原因・影響範囲・修正方針案」を短く報告する。
14. URL本文を取得できない場合は、失敗理由を1行で記録し、環境制限またはアクセス制限の種別を明記する。
15. 制限外実行でも取得できない場合は、投稿本文の貼り付けを依頼する。
16. URL本文が得られるまでは原因推測や修正方針の断定を行わず、エンジニアの対応を待つ。
17. 情報不足がある場合は、追加確認項目を短く列挙する。

reproduce

1. 失敗条件を固定し、最小再現コードまたは最小再現手順を作る。
2. 再現直前に docker compose exec <app-service> php evo log:tail --lines=5 で既存の直近ログを把握する。
3. docker compose exec <app-service> php evo db:query "SELECT ..." で再現に必要なレコード状態を確認する。
4. 再現前後で docker compose exec <app-service> php evo cache:clear を実行し、キャッシュ要因を切り分ける。
5. 再現後に docker compose exec <app-service> php evo log:tail --lines=20 --level=error を実行し、発生したログを特定する。
6. 必要に応じて docker compose exec <app-service> php evo log:search <message-or-file> --limit=10 --json で構造化コンテキストを確認する。
7. 再現できない場合は「再現不能」のまま進めず、前提差分を明示する。

create-branch

1. Issue 番号と症状からブランチ名を提案する（例: fix/10705-tv-saving-error）。
2. ベースブランチを確認してから分岐する。

draft-plan (必要時)

1. 問題が分かりにくい場合、影響範囲が読みにくい場合、または実装が複雑な場合にのみ ExecPlan を作成する。
2. analyze-issue の結果を、目的・制約・検証方法つきで計画へ反映する。

implement-fix

1. 調査報告に対するエンジニア承認を確認してから実装を開始する。
2. draft-plan に沿って最小差分で実装する。
3. 既存パターンを優先し、ヘルパー利用・DB安全性・イベント/キャッシュ影響を確認する。
4. 必要なテストまたは手動確認を実施し、結果を記録する。
5. 修正後に docker compose exec <app-service> php evo log:tail --lines=20 --level=error で同じエラーが増えていないことを確認する。
6. 必要に応じて docker compose exec <app-service> php evo health:check を実行し、基本健全性を確認する。
7. CLI 実行結果は検証ログへ要約して残す。

archive

1. 修正内容を再現条件とセットで要約する。
2. Conventional Commits 形式のコミットメッセージ案を作る。
3. 再発防止の観点で、必要なら assets/docs/troubleshooting/solved-issues.md を更新する。

pull-request

1. PR タイトルと本文を What / Why / How / Test の順で下書きする。
2. 破壊的変更、互換性影響、運用手順の有無を明記する。