---
name: poodle-session
description: >-
  Work-session context compression + knowledge harvest for coding agents.
  Instead of reading large materials (URLs, files, long tool outputs) into the
  context window, stash them into a LOCAL Poodle session and work from digests
  + targeted partial reads. Record decisions / error-solutions / rejected
  approaches as notes while you work. When the session wraps up, commit
  everything through Poodle's import pipeline so it becomes reviewable team
  knowledge. Nothing is sent to the Poodle server until commit.
hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "poodle session harvest"
          timeout: 10
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "poodle session harvest"
          timeout: 10
---

# Poodle Session Skill

## Purpose

エージェントの作業セッションを Poodle の「入口」にする。大きな資料を読む代わりにローカルへ stash してダイジェスト＋ハンドルで作業し（コンテキスト圧縮）、作業中に得た知見（決定・エラー解決・却下アプローチ）を note として記録し、セッションが一段落したら commit で既存の取り込みパイプライン（Source Document → 抽出 → 提案 → 人間レビュー）へ合流させる。

## When to use

- 長い URL / ファイル（md・txt・PDF）/ ツール出力（ログ・API レスポンス等）を**読む前** — 全文をコンテキストに入れず、まず stash する
- 作業中に「決定した」「エラーをこう解決した」「このアプローチは却下した」と言える瞬間 — その場で note
- 作業が一段落し、セッションで得た資料・知見をチーム知識として提案したいとき — commit

## Workflow

1. **stash**: 資料を読む代わりに保存する。返ってくるのはダイジェスト（タイトル・見出しアウトライン・冒頭・ハンドル）だけ
   - `poodle session stash url <url>`
   - `poodle session stash file <path>`（md / txt / PDF・10MB まで）
   - `<long output> | poodle session stash text --title "説明"`
2. **show**: 必要箇所だけ部分読み出しする（出力は 200 行 / 16,000 字で上限）
   - `poodle session show i1 --section "認証"`
   - `poodle session show i1 --grep "タイムアウト" --context 3`
   - `poodle session show i1 --lines 40:120`
3. **note**: 知見をその場で記録する（kind: decision / issue / howto / rejected）
   - `poodle session note --kind decision "リトライは指数バックオフで統一"`
   - `poodle session note --kind issue --item i1 "E1001 はトークン失効。再ログインで解決"`
4. **commit**: 一段落したら取り込む（**ここだけ POODLE_API_KEY が必要**）
   - `poodle session commit --dry-run` で送信内容を確認
   - `poodle session commit` で送信 → batch id が返る
5. 不要なら `poodle session discard` で削除（最終更新から 14 日で自動失効）

## Automatic Harvest (hooks)

PostToolUse / UserPromptSubmit hooks が有効な場合、知見パターンを自動検出して提案する。
提案は `[poodle-harvest]` プレフィックスでコンテキストに注入される。

**hooks の有効化について**: 上記 frontmatter の `hooks:` は `/plugin install` 経由のインストール
でのみ自動登録される（プラグイン同梱の `hooks/hooks.json` が使われる）。`poodle skill install` /
`pnpm skill:install` で SKILL.md だけをコピーした場合は自動登録されないため、
`.claude/settings.json` に手動で hooks を追記する必要がある。設定例は Poodle の
コンテキスト圧縮ガイド（`docs/pages/context-compression.mdx`）を参照。

### 提案を受けたとき
- テキストを確認し、有用であれば `poodle session note --kind <kind>` で記録する
- テキストは自由に編集してよい（提案はドラフト。正確な表現に直してから記録）
- ノイズと判断したら無視してよい（記録しない＝問題なし）
- セッションが未開始なら提案は表示されない（hooks は既存セッション前提）

### 検出カテゴリ
- **issue** (PostToolUse): コマンドの非ゼロ終了 + エラー解決ペアリング（同コマンドが後で成功したら解決提案）
- **rejected** (PostToolUse): エラーテキスト中の制約パターン（`not supported` / `permission denied` 等）
- **decision** (UserPromptSubmit): ユーザー発言の決定パターン（「〜を使おう」「Use X」等）
- **rejected** (UserPromptSubmit): ユーザー発言の却下パターン（「〜はやめて」「Don't use X」等）

### 注意
- hooks は提案のみ・自動記録はしない（確認なしで note を増やさない）
- 機密情報を含むエラー出力は編集してからノートする

## Commands

`poodle session --help` が正。主要: `start [name]` / `use <id|name>` / `list` / `status` / `stash url|file|text` / `show <handle> [--lines|--section|--grep]` / `note --kind <kind>` / `commit [--dry-run|--force]` / `discard`。すべて `--session <id|name>` で対象セッションを指定可能。

## Import mapping

- stash した item → Import Packet の document（URL は実 URL、file / text は `upload://<title>`。抽出済みテキスト全文＋見出し）
- note → finding（claim = 先頭行、suggestedKind: decision→decision / issue→issue / howto→howto / rejected→decision、confidence はノート指定値）
- **findings は抽出のヒント**であり、本物の LLM 構成では文言どおり提案になるとは限らない。このため**ノート全文は「セッションノート」ドキュメント（`session://<id>/notes`）として常に同梱**され、内容がレビューまで確実に届く
- origin は `agent_research`、`agent.sessionId` にセッション id が入る（帰属）

## Safety rules

- **secrets / credentials / 個人情報を stash・note しない**。機密を含む item は commit 前に `discard` する
- **commit するまで Poodle サーバーには何も送信されない**（stash / show / note / list はオフライン・API キー不要）
- commit しても **提案（レビュー待ち）止まり** — 検索に出るのは人間が `/proposals` でレビューして承認した後（AI は提案のみ作成、承認は人間）
- 推測をノートに書くときは `--confidence low` を付ける

## Expected result

- セッション中: 大きな資料がコンテキストウィンドウを占有しない（ダイジェスト＋部分読み出しで作業）
- hooks 有効時: エラー・決定・却下アプローチが自動検出され、note 記録の提案が届く（手動 note の負担が減る）
- commit 後: batch が作成され（`poodle status <batchId> --watch` で追跡）、資料とノートが提案としてレビューキューに入る
- 承認後: チームの検索・MCP（search_context / what_changed）から利用可能になる