log-to-dosu-knowledge

ログ → Dosu ナレッジ

製品の説明（シンプルに保ちます）：

このスキルは、Dosu を導入する前のログを持つ初めて利用するユーザー向けです。

1. ローカルのエージェントログを読み取ります
2. 書き込む内容を決定します（ユーザーのプロンプトではなく、回答や注意点です）
3. 各項目を合成 dosu/log-backfill/<UTC-timestamp> ブランチに書き込みます
   （サーバーはそのプレフィックスの notes-upflow を自動的にキューに追加します。PR のマージ時と同じ経路です）
4. キャッシュされた内容、予想されるトークン節約量、バックフィルブランチをユーザーに伝えます
5. HTML レポートを開きます（generate_report.py --open）。推定コンテキスト節約量も含めます

**ドライラン：**同じ抽出を行いますが、write_knowledge は呼び出しません。出力するのは、（合成ブランチを入力した状態で）実行するはずの呼び出しの一覧のみです。

write_knowledge を使える Dosu MCP 接続が必要です。書き込み先には dosu/log-backfill/<timestamp> を指定してください。これにより自動的に昇格されます。現在のチェックアウトブランチにはフォールバックしないでください（そのブランチのメモは実際の PR がマージされるまで取り残されます）。

質問しないこと（必須）

このスキルでは、AskUserQuestion、複数選択式の質問、「スコープに関する 3 つの選択肢」を絶対に使わないでください。特に、次の点は質問しないでください。

• メモをブランチにどのように関連付けるか（main、セッションごと、など）
• メモの粒度や統合方針
• どこまでさかのぼって取得するか（ユーザーがすでに依頼していて、内容が曖昧な場合を除く）

既定値は固定されています。そのまま実行してください。

決定事項	既定値
時間 / 件数	親セッションのうち、最近のものから 50 件
各 write_knowledge 呼び出しのブランチ	実行全体で 1 つの BACKFILL_BRANCH=dosu/log-backfill/<UTC-timestamp>
粒度	アシスタントの結論ごとに 1 件のメモ（長いチャットでは多数のメモ）。同じ事実の場合に限り統合します。

MCP ツールのスキーマにある「git branch --show-current を使う」という指示は、ここでは適用されません。上書きしてください。使用するブランチをユーザーに尋ねないでください。whoami の後に、BACKFILL_BRANCH を 1 行で知らせてから続行してください。

• セットアップ：references/customer-setup.md
• 書き込む内容：references/write-criteria.md
• ログのパス：references/history-locations.md

書き込みの例

各メモは MCP の呼び出し 1 回分です。引数は次のとおりです。

引数	意味
title	名詞句のトピック（Slack PostgREST 1000-row channel picker cap）
content	将来のエージェントに必要な、自己完結した事実
repo	git remote get-url origin のリテラル値
branch	実行全体で使う合成 dosu/log-backfill/<UTC-YYYYMMDD-HHMMSS>
tags	任意。例：["from-agent-log", "cursor"]

**誤り：**ユーザーの最初のメッセージを title に使うこと、または一覧の行をメモとして扱うこと。

**正しい例：**要約を読んだ後、次のように結論を抽出します。

title:   Slack PostgREST 1000-row channel picker cap
content: slackChannel.getAll used an unbounded PostgREST select; hosted
         PostgREST silently returns ≤1000 rows so large workspaces miss
         channels that exist in slack.channel. Page the query.
repo:    [email protected]:acme/api.git
branch:  dosu/log-backfill/20260810-220015

ワークフロー

Progress:
- [ ] 0. whoami + REPO/BACKFILL_BRANCH/SKILL_DIR
- [ ] 1. Inventory (find sessions worth mining — internal)
- [ ] 2. Digest those sessions
- [ ] 3. Build the write_knowledge payload list (+ rediscovery token estimate)
- [ ] 4a. Default: write on BACKFILL_BRANCH (auto-promotes) → open HTML report (with estimated context savings) → reply
- [ ] 4b. Dry-run: print the payload list → stop (no writes, no finalize)

ステップ 0 — 対象

SKILL_DIR="$(find .claude/skills .cursor/skills .agents/skills \
  -type d -name 'log-to-dosu-knowledge' 2>/dev/null | head -1)"
REPO="$(git remote get-url origin)"
BACKFILL_BRANCH="dosu/log-backfill/$(date -u +%Y%m%d-%H%M%S)"
test -f "$SKILL_DIR/scripts/parse_agent_logs.py"

whoami を呼び出します。write_knowledge が利用可能であることを確認します。メモの送信先となる Library と、この実行で使用する BACKFILL_BRANCH を、ユーザーに 1 行で伝えます（情報提供のみで、質問ではありません）。whoami が内部向けの対象フィールドを返した場合、その単語はユーザーに繰り返さず、Library 名または組織名を使ってください。log-backfill のメモをチェックアウトブランチに書き込まないでください。ブランチ、日付範囲、粒度の選択のために処理を中断しないでください。

ステップ 1 — 一覧の作成（内部処理）

既定の対象範囲は、親セッションのうち最近のものから 50 件です。ユーザーから指定があった場合は変更します。

ユーザーの指定	フラグ
（既定）	(なし — 最近のものから 50 件)
「過去 N 日間」／「過去 1 か月」	--days 30（その期間内の全セッション）
「全件を監査」／「すべて」	--full
「上位 N 件」／「最近のものから N 件」	--limit N

python3 "$SKILL_DIR/scripts/parse_agent_logs.py" \
  --out /tmp/dosu-log-inventory.json
# examples:
#   ... --days 30 --out /tmp/dosu-log-inventory.json
#   ... --full --out /tmp/dosu-log-inventory.json
#   ... --limit 100 --out /tmp/dosu-log-inventory.json

一覧に含まれるすべての親セッションを使用してください。順位は順序付けのみに使います（candidate_score の高い順）。ユーザーのプロンプトや一覧の行を結果として表示しないでください。

ステップ 2 — 内容を精査する

python3 "$SKILL_DIR/scripts/parse_agent_logs.py" \
  --digest <id> --json > /tmp/digest-<id>.json

インベントリ内にある、ナレッジ化できる親セッションをすべて精査します。精査後は、最後だけでなく、すべてのユーザーターンを順番に確認します。長時間の調査（learning_tokens が 100k 以上、ユーザーターンが 50 回以上）からは、1～2 件ではなく、多くのノートが得られるはずです。

空または些細なチャット（実質的なユーザーの質問がないもの）だけをスキップします。subagents/ よりも親チャットを優先します。最初のメッセージがレポート、Sentry、SQL の貼り付けに見えるからといって、精査をスキップしないでください。

ステップ 3 — 書き込みリストを作成する

write-criteria.md を満たすアシスタントの結論が得られた各ユーザーターンについて、ペイロードを追加します。「このトランスクリプトからすでにノートを 1 件書いた」ことを、完了とみなさないでください。

{
  "title": "…",
  "content": "…",
  "repo": "<$REPO>",
  "branch": "<$BACKFILL_BRANCH>",
  "tags": ["from-agent-log", "cursor"],
  "transcript_id": "<source session id>",
  "approx_rediscovery_tokens": 12000,
  "investigation_lines": "128-131",
  "plain_english": "…",
  "how_found": "…"
}

plain_english は、チームメイト向けにアイデアを言い換えた 1～2 文です（関数名やテーブル名を並べ立てないでください）。レポート専用です。approx_rediscovery_tokens と同様に、write_knowledge からは省略します。 how_found には、どのような作業で発見したか（読み取り、SQL、Logfire、コードパス）を記載します。セッション共有トークンの計算式ではありません。レポート専用です。write_knowledge からは省略します。 investigation_lines は、compare_tokens.py --from-digest --lines に渡すものと同じ START-END です。各候補に必須です。指定しないと、HTML の学習に必要な作業の折りたたみ欄が空になります。レポート専用です。write_knowledge からは省略します。

実行中のすべての候補で、同じ BACKFILL_BRANCH を使用します。チェックアウト中のブランチやログごとのブランチ名は使用しないでください。

approx_rediscovery_tokens は、この事実を学ぶコスト、つまり、その事実にたどり着くまでに費やしたトークン数（質問＋情報取得＋思考＋結論）です。Decant のコンテキスト、計画なども含みます。Write／Edit／シェルによる変更は含みません。ノートで実装トークンを節約することはできないためです。100k 学習したなら、100k 節約できます。上限はありません。セッション全体の割合ではありません。

この事実に関する最初の質問／ツールから結論までの精査行をマークします。次の方法で測定します。

python3 "$SKILL_DIR/scripts/compare_tokens.py" \
  --from-digest /tmp/digest-<id>.json --lines START-END

その JSON の値を approx_rediscovery_tokens としてペイロードに設定します。調査範囲を特定できない場合に限り、このフィールドを省略します。セッション全体の割合を作り上げたり、コンテキストの区分だけを使ったり、セッションの予算を分割したりしないでください。

シークレット／PII、タスクの要約、推測、自明な単一ファイルの事実はスキップします。

書き込みリスト全体を /tmp/dosu-log-candidates.json に { "candidates": [ …payloads… ] } の形式で保存します。これにより、ドライラン、節約量の要約、HTML で同じ形式を共有できます。

ステップ 4a — デフォルト：書き込みと節約量

各ペイロードについて、title／content／repo／branch／tags を指定して MCP write_knowledge を呼び出します（approx_rediscovery_tokens、plain_english、how_found、investigation_lines などの補助フィールドは省略します）。すべての書き込みで BACKFILL_BRANCH を使用してください。サーバーは dosu/log-backfill/* に対して notes-upflow を自動的にキューに追加します（PR のマージ時と同じステップです）。個別の promote 呼び出しは不要です。

MCP による書き込みができない場合：

python3 "$SKILL_DIR/scripts/pending_knowledge.py" append \
  --repo "$REPO" --branch "$BACKFILL_BRANCH" \
  --title "…" --content "…" \
  --tags from-agent-log,pending-sync

次に、デフォルトのユーザー向け要約を作成します。

python3 "$SKILL_DIR/scripts/summarize_savings.py" \
  --candidates /tmp/dosu-log-candidates.json

この標準出力がデフォルトの返信です。これに、ノートが BACKFILL_BRANCH に書き込まれ、候補トピックのパイプラインに入ったことを示す 1 行を加えます。形式：

Cached N notes:
1. <title>
2. <title>

Expected savings: ~Y tokens per future agent read
(same model as analytics: rediscovery/generation cost reused on each hit)

Wrote on dosu/log-backfill/<UTC-YYYYMMDD-HHMMSS> (auto-promoted into the candidate-topic pipeline).

節約量の行を付けずに「ノートを N 件保存しました」だけで終わらせないでください。

その後、必ず HTML レポートを開きます（オプトインではありません）。推定コンテキスト節約量には、各ノートの approx_rediscovery_tokens が反映されます（調査範囲を特定できない場合に限り、このフィールドを省略します。セッション全体の割合を作り上げないでください）。

レポーターはノートが書き込まれていることを前提とします。write_knowledge を使わずに HTML を生成する場合に限り、--dry-run を渡します。

python3 "$SKILL_DIR/scripts/generate_report.py" \
  --inventory /tmp/dosu-log-inventory.json \
  --candidates /tmp/dosu-log-candidates.json \
  --pending .dosu/pending-knowledge.jsonl \
  --digest-dir /tmp \
  --org-name "…" --repo "$REPO" --branch "$BACKFILL_BRANCH" \
  --out /tmp/dosu-knowledge-report.html --open

このツールが存在する場合は、書き込みレシート ID を指定して finalize_session_knowledge を 1 回呼び出します。

ステップ 4b — ドライラン（ユーザーから依頼された場合）

write_knowledge は呼び出さないでください。それでも BACKFILL_BRANCH を設定し、一覧に記載するすべてのペイロードに含めます。次のようにペイロードリストを返信します。

Dry-run — would call write_knowledge N times:

1. title: …
   content: …
   repo: …  branch: …
   approx_rediscovery_tokens: …

2. title: …
   content: …
   repo: …  branch: …
   approx_rediscovery_tokens: …

このリストがドライランの出力そのものです。セッションプロンプトでも、インベントリスコアでもありません。必要に応じて、同じ summarize_savings.py のブロックを追加できます（これらを書き込んだ場合の予想節約量）。ドライランで HTML を開く場合は、--dry-run を渡します。

オプトインの追加機能

ユーザーの発言	動作
"PDF"	すでに開いている HTML レポートから PDF として印刷／保存します
"detailed token report"	貼り付けられた read_knowledge の応答を使った任意の compare_tokens.py 評価（デフォルトの推定値を上書きします）

Miner miss-mode（この言葉を顧客に言わないでください）

収集時に件数を過少に数えないためのエージェント向け指示：

1. トランスクリプトごとではなく、アシスタントの結論ごとに 1 つのメモを作成してください。最後の余談で止めないでください。
2. 最初のメッセージがレポート／Sentry／SQL の貼り付けに見えても、ダイジェストをスキップしないでください。
3. レポートの前に、必ず保留中の項目（generate_report.py --pending）を統合してください。
4. ブートストラップのみのセッションはパーサーによってデフォルトの 50 件から除外されます。表示された場合はスキップしてください。
5. ライブラリにすでにページがある場合（この実行の read_knowledge）、書き込みをスキップしてください。ステータス already_in_library は問題ありません。
6. HTML のベースラインは、effective_tokens や context_tokens 単独ではなく、インベントリの learning_tokens です。
7. すべての候補に investigation_lines を含め、レポートは --digest-dir /tmp を指定して生成してください（ダイジェストをディスクに残します）。両方がない場合、学習する内容は空欄になります。how_found では代用できません。

ガードレール

• デフォルトでは dosu/log-backfill/* に書き込みます（サーバーが自動昇格します）。また、必ず予想されるトークン削減量を含め、HTML レポートを開き、そのレポートの推定コンテキスト削減量を入力します。
• 現在のチェックアウトブランチにログバックフィルのメモを書き込まないでください。
• メモをブランチにどう帰属させるか尋ねないでください。常に BACKFILL_BRANCH を使用してください。
• 範囲を確認するための質問票を勝手に作らないでください。ユーザーがメッセージで上書きを指定していない限り、デフォルトを使用してください。
• ドライランは依頼された場合にのみ実行してください（書き込みません）。
• シークレット／PII／生のログダンプを書き込まないでください。
• write_knowledge の呼び出し 1 回につきメモ 1 つにしてください。メモは簡潔に保ってください。
• ユーザー向けの出力は常にメモ（書き込み済みまたは書き込み予定）と削減量について説明し、生のプロンプトについては説明しません。

簡単な例

• 「Dosu でナレッジをブートストラップしてください。」→ バックフィルブランチに書き込み（自動昇格）＋キャッシュされたタイトル＋予想される削減量＋HTML レポートを開く（推定コンテキスト削減量を含む）。
• 「エージェントのログを Dosu にマイニングしてください。」→ 同じデフォルトの書き込みフロー。
• 「ログを dosu knowledge にドライランしてください。」→ write_knowledge ペイロードの一覧（合成ブランチ）のみ。