---
name: poodle-doctor
description: >-
  Diagnose what is burning the user's model tokens (context waste, output,
  loops, cache misses) by analyzing the agent's own transcripts with
  `poodle doctor`, then propose the top remediations. Fire when the user asks
  (in any language) to コンテキストを診断して / トークン消費を調べて /
  diagnose context usage / why is this session so expensive / doctor を実行して.
---

# Poodle Doctor Skill

## Purpose

`poodle doctor` を実行してエージェント（Claude Code / Codex）のトークン消費を
原因別に実測し、**即効性のある削減施策を上位から提案する**。分析は LLM を使わない
決定論の静的ルールで、すべてローカルで完結する。サーバーに送られるのはサマリ
（トークン数・rule・repo 相対パス/コマンド署名）だけで、本文・コマンド出力・
絶対パスは送信されない。

オンデマンド型スキル（hooks なし）。自動レポートの有効化は `poodle setup`
が settings.json に SessionEnd / PreCompact hook を書き込む方式で、SKILL.md のコピー
だけで発火するものではない。SessionEnd はセッション終了時、PreCompact は compaction 直前
（作業が一段落した区切り）に発火し、compaction をまたぐ長いセッションでも作業区切り別の
usage（dimension='segment'）を残す。

## 使い方

1. **診断を実行**:

   ```
   poodle doctor                 # 直近セッション（R8 は直近セッション群を自動で追加読込して補完する）
   poodle doctor --all-sessions  # 直近 5 セッションを横断（明示的に母集団を広げたい場合）
   poodle doctor --codex         # Codex の rollout を対象にする
   ```

2. **結果を要約して伝える**。レポートの構造:
   - セットアップ診断: `[FAIL]` があれば最優先で対処を提案（hint のコマンドをそのまま提示）
   - 消費内訳: モデル別 usage 4 バケット（API 実測値）・ツール別バイト
   - Finding: R1〜R8（推定節約トークン降順）。上位 2〜3 件に絞って提案する

3. **上位施策の実施をその場で提案する**:
   - `[FAIL] intercept hook 未登録` / `[WARN] intercept hook が上書きされ発火しない`
     → いずれも `poodle setup` の実行を提案（未登録なら `~/.claude/settings.json`
     に登録される。`[WARN]` は登録済みだが `.claude/settings.local.json` 等の
     高優先スコープに同一イベントを上書きされ発火しない状態 —
     `poodle setup` が shadow を検知してそのファイルに追記する）
   - `[WARN] コンテキスト検索 hook（search-hook-activity）`: **`poodle setup` を
     一律に提案しない** — 登録有無は別チェック（`search-hook` / `search-hook-prompt`）
     が既に担当しており、activity の warn は「登録済みだが結果が芳しくない」ことを
     指す。summary の主因表記で処方を切り替える:
     - 「主因 = org 可視の承認済みナレッジ不足」→ 取込・承認でコーパスを増やす提案
       （`poodle-project-scan` / `poodle-github-research` スキル等で取込 → Web UI で承認）
     - 「スコアがフロア未達」→ `POODLE_CONTEXT_MIN_SCORE`（既定 0.03）を下げる調整を提案
     - 「PreToolUse の発火記録がありません」（片肺）→ hook の trust 承認待ち /
       matcher 不一致 / CLI 更新直後の可能性を伝え、しばらく使ってから再診断を提案
       （`poodle setup` の再実行では解消しないので誘導しない）
     - 「活動記録がありません」→ エージェント未使用なら無視してよい旨を伝える
   - R1/R2（再 Read・全文 Read）→ 該当ファイルを `poodle session stash` するか、
     以後は offset/limit の部分読みに切り替える
   - R5（未圧縮の大出力）→ intercept 有効化（上と同じ）
   - R8（ナレッジ化候補）→ Finding の hint をそのまま提示（v2 で対象に応じて hint が変わる）:
     - 安定したファイル: `poodle doctor` でそのファイルの要点を蒸留し、下書きをそのまま提案
       （import 不要・下記 5 の導線。承認は人間）
     - 内容が変化するファイル（schema.sql 等）: import せず `poodle session note` で要点を蒸留
     - 同一ディレクトリに候補が集中（領域候補）: `poodle session note` で領域の案内図を登録
     - コマンド結果・調査知見: `poodle session note` で記録して `poodle session commit`
     - 命令ファイル（CLAUDE.md / SKILL.md 等）や同セッションで編集した作業ファイルは
       v2 で候補から自動除外される（毎回読むのが正しい / 編集のための取得は登録で減らない）
   - R6（ループ）→ 再試行前の原因特定・結果の stash 再利用
   - R7（cache 失効）→ 長い離席を挟む作業はセッションを分ける

4. **チーム集計への参加を確認する**: セットアップ診断で SessionEnd hook が未登録なら
   `poodle setup` を提案する。以後セッション終了時と compaction 直前（作業の
   区切り）ごとにサマリが自動送信され、ワークスペースの insights「コスト原因分析」で
   「チームで最も効く改善策」に集計される。
   オプトアウトは `poodle setup disable`（または `--no-report`）。

5. **R8 候補の下書きをその場で見て提案する（対話実行のデフォルト）**: 診断後、TTY での対話実行なら
   「N 件の候補の下書きを生成して表示しますか？」と確認し、y なら R8 のファイル候補
   について title/要点(summary)/body/kind の下書きを生成して表示する（蒸留は `poodle doctor`
   の既定フローの一部で、専用フラグは不要）。表示後「この下書きで提案を作成しますか？」と確認し、
   y なら **その場で提案（proposed）として登録できる**（既存の `poodle propose` と同じ経路）。
   import コマンドは不要。下書きも提案するかどうかも人間が判断し、**承認も人間**が行う。

## 出力の読み方

- 数値は **API 実測の usage**（input / output / cache_read / cache_creation）と
  **実測バイト由来の推定節約**の 2 種類。USD 換算はしない
- 「Read 目的別」= 参照 Read（編集を伴わない = コンテキスト登録で削減可能な母集団）と
  作業 Read（同セッションで編集した = 登録では減らない）の内訳。参照 Read が大きいほど
  ナレッジ化の余地が大きい
- exit code: 0 = 問題なし / 1 = WARN あり / 2 = FAIL（セットアップ不備）あり
- `--json` で機械可読出力（Finding の targetKey・estimatedTokens を含む）
- 対象外ルールは agent 種別ごとにレポート末尾に明示される（Codex は R1〜R5 対象外）
- 「ゼロヒット検索の作業文脈」「圧縮された大出力の作業文脈」= Finding（R1〜R8）とは別枠の
  ローカル表示専用セクション（新ルールではなく exit code にも参加しない・イベントが
  0 件のセクションは表示されない）。ゼロヒットは MCP `search_context` の
  `results: []` 応答を、圧縮は poodle-intercept の digest を検知し、それぞれ直前の
  user prompt（秘密マスク済み）と直後の tool アクションを添えて表示する —
  **この表示自体は見出しどおりサーバーには一切送信されない**（同じ抽出ロジックの
  一部が次節の作業文脈共有 API の入力としても使われるが、送信されるのは別途
  フィルタ・上限を適用した payload であり、この表示セクションではない）

## 作業文脈の共有（既定 ON・オプトアウト）

ログイン中は既定で、3 つのシグナル（圧縮イベント・ゼロヒット検索・コスト診断の finding）の
記録に、`poodle doctor` が付ける **AI 要約の作業文脈（1 行）** が加わり、インサイトに
「AI による推定」として表示される（管理者/レビュアーのみ閲覧）。ゼロヒット検索は MCP
（エージェント）経由の検索のみが対象（UI/API 経由の検索には付かない）。**生のコマンド出力・
ユーザープロンプト全文は送信も保存もされない** — 送るのは匿名化した識別子（コマンド署名・
検索クエリ・相対パス等）・相関キー（不透明トークン）・マスク済みプロンプト断片（≤200字）と、
サーバー側 AI が要約した 1 行だけ。検索クエリ自体は検索実行時に既にサーバーへ保存済みのため、
この注釈で新たに露出するものではない。有効な状態で `poodle doctor` を初めて実行すると一度だけ
お知らせが出る（対象拡大時は既存ユーザーにも一度だけ再表示される）。無効化・確認は次のとおり:

- `poodle doctor work-context off` — 無効化（以後は 3 シグナルとも記録・送信しない）
- `poodle doctor work-context on` — 再有効化
- `poodle doctor work-context status` — 現在の状態

このサーバー AI 要約は、上の「ゼロヒット検索の作業文脈」「圧縮された大出力の作業文脈」
（doctor ローカル表示・verbatim・サーバー非送信）とは別物。ローカル表示はプロンプトを
そのまま手元に出すだけで送信しない。

## 注意

- 診断は transcript が残っている期間（既定 30 日 — cleanupPeriodDays）のみ全粒度で
  再現できる。自動レポート hook はサマリを消える前に回収する配管でもある
- ナレッジ登録は必ず提案（proposed）として作られ、承認は人間が行う