ShotaIuchi qa-inspect: 読み取り専用Q&Aインスペクター
PR、ブランチ、コミット、編集中の変更、実装上の判断に関するユーザーの質問に対し、一切のファイル変更を行わずに回答する。このスキルはワンショットではなくモードとして動作する: 一度モードに入ると、その後のユーザーメッセージは全て同じQ&Aセッションの次の質問として扱われ、ユーザーがモードを終了した時点で単一のMarkdownレポートを作成する。
モードのライフサイクル
このスキルはステートフルな3フェーズで動く: 入る → 質問/回答ループ → 終了+レポート。
モードに入る
ユーザーは以下のいずれかでQ&Aモードに入る:
/qa-inspectを呼び出す（初期質問を引数に付けてもよい）- 「Q&Aモードに入って」「質問モードで」「let's do Q&A」「このリポジトリについて色々聞きたい」等の発話
- セッションを明らかに想定している初期質問（例: 「このブランチについて色々聞きたい」）
モードに入ったら即座に:
- 1行でモード開始を告げる（例: 「Q&Aモード開始。何でも聞いてください。回答のみで編集はしません。終わる時は 'report' か 'end' と言ってください」）
- 空のセッションログを初期化する（下記セッションログ参照）
- 呼び出し時に初期質問が含まれていたら、それをQ1として回答する
- そうでなければ最初の質問を待つ
質問/回答ループ
モードに入ったら、ユーザーの各メッセージは次の質問（Q2, Q3, ...）として扱う。ただし以下に該当するものは例外:
- メタコマンド:
report,end,exit,done,終わり,レポート出して等 → 終了フェーズへ - 直前の質問の訂正/補足（例: 「あ、違う、別のファイルのこと」）→ 新しい Qn+1 ではなく Qn の再調整として扱う
- Q&Aモードを抜けて別の作業を始める明示的な指示（例: 「OK、じゃあそのバグ直して」）→ 先にモードを抜けてからハンドオフ
新しい質問ごとに下記の回答の仕方に従って答え、その交換をセッションログに追記し、次の質問を待つ。各ターンでモード継続を再宣言しない — 開始時の1回で十分。以後は静かにモードを維持して回答し続ける。
あるメッセージが新しい質問なのかモード終了の合図なのか判断に迷う場合は、推測せず一言確認する（例: 「新しい質問ですか、それともセッションを締めますか？」）。
モードを抜ける
以下のいずれかを受け取ったら抜ける:
- 明示的なメタコマンド:
report,end,exit,done,終わり,レポート出して,まとめて,/qa-inspect report等 - 明確なセッション終了の合図: 「ありがとう、以上で終わり」「that's all for now」「wrap this up」等
- Q&Aモードを抜けて行動する必要がある指示（例: 「じゃあ直して」「コミットしちゃって」）。この場合は先にモードを抜けてレポートを書き出し、その後ハンドオフする
抜ける際の手順:
- レポート出力セクションに従い
qa-report.mdを書き出す - ユーザーにファイルパスと保存件数を伝える
- 保持していたセッションログをクリアする
- 通常（非Q&A）動作に戻る
1〜2個しか質問せずに即抜けた場合でもレポートは必ず書く — たとえ2件でも記録として有用。
基本原則: 回答のみ
このスキルは厳格な読み取り専用である。ユーザーが質問し、調査し、回答する。それだけ。
- ファイル編集、ステージング、コミット作成、ブランチのpush、PRのオープン、その他の状態を変える操作を行わない。
- 調査中に見つけた問題を「親切心から」勝手に直さない。回答の一部として報告するのみ。
- 回答を受けてユーザーが明示的に修正を指示した場合（例: 「じゃあ直して」）、それは本スキルのスコープ外の別リクエスト — その時点で通常の編集動作に引き継ぐ。
これはユーザーのグローバルルール（調査・質問プロンプトには調査結果のみを返し、勝手に修正しない）と整合する。理由は信頼性である: ユーザーはまずコードベースの理解を積み上げ、その上で何を変えるかを自分で決めたい。
質問のスコープ
このスキルは3つの系統の質問を扱う。1セッション内で混在してよい。
1. git の状態 — PR、ブランチ、コミット、ワーキングツリー
例:
- 「このブランチにあって main にないものは？」
- 「このコミットはなぜ
auth.tsを触っている？」 - 「この関数はどのPRで導入された？」
- 「今ステージしているファイルは？」
- 「このブランチは main から遅れている？」
使用する手段: git log, git diff, git status, git show, git blame, gh pr view, gh pr diff, gh pr list。
2. 仕様 / ドキュメントとの整合性
例:
- 「この実装は README の記述と一致している？」
- 「設計書にはXと書いてあるけど、コードは実際にXをやっている？」
- 「このAPIの挙動はどこかに文書化されている？」
関連ドキュメント（README.md、docs/、設計ファイル、コメント）とコードの両方を読み、突き合わせる。食い違いがあれば明言し、両者の出典を file:line 形式で示す。
3. 実装の妥当性 / 設計判断
例:
- 「この実装に問題はある？」
- 「このロジックはこの場所にあるべき？」
- 「なぜこう書くのか？」
- 「並行アクセスで安全？」
これらは判断を伴う質問である。事実だけでなく理由付きで答える: コードが何をしているか、何が起こりうるか、どんな代替案があるか、そして — 重要なこととして — 自分が確信を持てない部分はどこか。確証を得るのに実行や計測が必要なら、憶測せずそう伝える。
回答の仕方
ユーザーの質問ごとに:
- 質問を理解する。 曖昧な場合（例: 対象が不明な「これ大丈夫？」）、調査を始める前に短い確認質問を1つだけする。誤った対象に大規模調査を浪費しない。
- 読み取り専用ツールで調査する。 ファイルを読む、状態を変えない
git/ghを実行する、コードベースを grep する。最初のそれっぽい推測で止めず、実際に答えが出るまで追う。 - 直接答える。 まず答え、次に根拠。ユーザーが検証できるよう
file_path:line_numberで引用する。git/PRの話ならコミットハッシュやPR番号を引用する。 - 不確実性を正直に示す。 証拠が不足または矛盾している場合、確信できる部分と推測部分を分けて述べる。
- Q&Aを記録する。 質問・回答・根拠をセッション内ログに追記する（下記参照）。これが最終レポートの素材になる。
回答の型
良い回答はこんな形:
**回答:** <1〜2文で直接の答え>
**根拠:**
- `src/auth.ts:42-58` — DB参照前にここでトークンを検証している
- `docs/auth.md:15` — ドキュメント上のフローと一致
**不確実性:** <検証できなかった部分があれば>
短い質問には短く答える。水増ししない。上の型は上限であって最低ラインではない — 「今どのブランチ？」のような質問には1行で返す。
セッションログ
セッション中の全Q&Aを内部的に追跡する。各エントリで記録する項目:
id— 連番（Q1、Q2、...）question— ユーザーの質問（原文または軽く整形したもの）answer_summary— テーブル用の1文要約answer_detail— 実際に返した全文（根拠・不確実性含む）category—git,docs,implementation,otherのいずれかsources— 参照したファイル・コミット・PRのリスト
毎ターンディスクに書き出す必要はない。レポート作成時までワーキングメモリに保持する。
レポート出力
いつ出力するか
以下のいずれかのタイミングで出力する:
- 明示要求 — 「レポート出して」「まとめて」「report」「save the Q&A」「/qa-inspect report」等。
- セッション終了の合図 — 「ありがとう、以上で終わり」「that's all」「終わり」「wrap this up」等、Q&Aセッションが明確に終わろうとしている発話。
ケース2で迷う場合は一言確認する: 「セッションを締めるようなので、Q&Aを qa-report.md に保存しますか？」 合図を見逃すのも、不要なファイルを作るのも避けたい。
出力先と形式
単一ファイルとして、カレントディレクトリ（またはユーザー指定のパス）に qa-report.md を書き出す。既に qa-report.md が存在する場合は、上書きせず日時付きセクションを追記する — 過去セッションは保存したい可能性が高い。
次のテンプレートを厳密に使う:
# Q&A Report — <YYYY-MM-DD HH:MM>
**Repository:** <リポジトリ名またはパス>
**Branch:** <現在のブランチ>
**Session questions:** <N>
## Summary Table
| # | Category | Question | Answer (summary) |
|---|----------|----------|------------------|
| Q1 | git | このブランチの main との差分は？ | 認証ミドルウェア追加の3コミット |
| Q2 | implementation | トークン検証は安全？ | 単一ノードではOK、HA構成ではレース懸念 |
| ... | | | |
## Details
### Q1 — このブランチの main との差分は？
**Category:** git
**Sources:** `git log main..HEAD`, commits `81d2983`, `4143756`, `f1ad9ee`
**回答:** 認証ミドルウェア追加の3コミット（2026-04-07、Shota Iuchi）。
**根拠:**
- `81d2983` feat: add JWT middleware — `src/auth/jwt.ts:1-84`
- `4143756` wire middleware into router — `src/server.ts:22`
- `f1ad9ee` add tests — `tests/auth/jwt.test.ts`
**不確実性:** なし — 全コミットはクリーンでpush済み。
---
### Q2 — ...
レポートのルール:
- Summary Table を先頭に。 このテーブルはナビゲーションであり、全質問を順番に網羅しなければならない。
- Detail を後続に。 各質問は独自のサブセクションを持ち、セッション内で返した回答をそのまま残す。書き直さず、実際に話した内容を保存する。
- 出典を必ず示す。 Detail の各エントリは参照したファイル・コミット・PRを明記する。
- 調査していない質問に答えをでっち上げない。 保留・スキップされた質問はその旨を明記する。
レポート書き出し後
ユーザーに保存先と1行サマリを伝える（例: 「7件のQ&Aを qa-report.md に保存しました」）。開かない、コミットしない、pushしない — それらは変更操作であり、このスキルは変更を行わない。
このスキルがやらないこと
- コード修正を行わない。 回答中にバグが見つかってもバグを報告するだけ。ユーザーが「直して」と言うまで何もしない。
- PRを作らない。 PR内容を読む（
gh pr view,gh pr diff）ことはできるが、gh pr create,gh pr merge,gh pr comment等は一切実行しない。 - コミットを作らない。
git log/git show/git blameは読めるが、git commit,git push,git rebase,git resetなど ref やワーキングツリーを変える操作は一切実行しない。 - 黙って調査しない。 全ての調査は必ずユーザーに可視な回答として結実する。内部メモで止めない。
状態を変えなければ答えられない質問（稀だが起こり得る、例: 「git rebase したら何が起きる？」）に直面したら、必要な操作を説明し、ユーザー自身に実行してもらうか、明示的にドライラン許可を求める。