Directive Mining

---
name: directive-mining
description: セッションログのユーザー発話を全件マイニングし、指示ファイルの修正提案を作る。訂正（やってしまったことを止める規則）と繰り返し指示の既定化（言われなくてもやる規則）の2系統で出す。使用タイミング (1)「私の指示を全部拾って指示を改善して」「毎回言っていることを勝手にやれるようにして」等の依頼時、(2) /directive-mining 実行時、(3) 数週間ぶりの .claude 棚卸しで実データから改善点を出したい時。境界: skill発火数・tool頻度・compaction回数などの定量集計は session-analytics、単一セッション内の知見の自律反映は session-retro、実データを見ない静的品質監査は instructions-audit、メモリディレクトリのキーワード検索は findmem。本スキルは提案の作成までを担い、指示ファイルへの適用は update-inst / session-retro に渡す。
allowed-tools: Bash(python3:*), Bash(uv run:*), Read
---

# Directive Mining

`~/.claude/projects/**/*.jsonl` のユーザー発話を全件走査し、指示ファイル（AGENTS.md / context / skills / output style）の修正提案を作る。

出す提案は2系統。混ぜると優先順位が付けられなくなるため分けて出す。

| 系統 | 拾うもの | 提案の形 |
|---|---|---|
| **訂正由来** | ダメ出し・否定・禁止（「そうじゃない」「勝手に〜した」） | やってはいけないことを止める規則 |
| **既定化** | 毎回言われている指示・前置き・条件 | 言われなくても実行される既定値 |

## 既存設定との関係

- **session-analytics**: データ源は同じだが方法と出力が違う。あちらは skill 発火数・tool 頻度・中断数の定量集計。本スキルはユーザー発話そのものの全件マイニング。定量シグナルも欲しい場合は先に session-analytics を回して突き合わせる
- **session-retro**: 単一セッションの知見を自律反映する。本スキルは複数セッション横断で提案を作るところまでで、適用はしない
- **instructions-audit**: 指示ファイル自体の静的品質を rubric で見る。本スキルは実データ（ユーザーが何を言ったか）から見る
- **Phase 0-5（@context/workflow-rules.md）**: 本スキルは調査タスクであり Phase 0-5 の適用対象外。分析結果を残す場合は @context/memory-file-formats.md の構造に従う

## ワークフロー

### Step 1: 全件抽出と除外の会計

```bash
python3 ~/.claude/skills/directive-mining/scripts/extract_user_turns.py \
  --out <作業ディレクトリ>/user_turns.jsonl \
  --chunk-dir <作業ディレクトリ> \
  [--since YYYY-MM-DD] [--project SUBSTR]
```

ログの user ロールには、ユーザーの発話以外に tool_result・他セッションからのメッセージ・サブエージェント完了通知・compaction 要約・skill 読込の注記が混ざる。スクリプトはこれを理由別にカウントしてから落とす。

**会計表は必ず報告に載せる**。「何件を見て、何件を落としたか」を示さないと、後から網羅性を検証できない。

**完了基準**: 会計表の各行の合計がログ中の user イベント総数と一致しており、`user` 行の件数と、書き出された JSONL の行数が一致している。

### Step 2: 決定論的な頻度集計

```bash
python3 ~/.claude/skills/directive-mining/scripts/count_directives.py \
  <作業ディレクトリ>/user_turns.jsonl
```

出るもの:

- **同一文言の反復**: 完全一致で繰り返されている短い発話。毎回言わせている定型指示がここに出る
- **パターン別の件数 / インシデント数**: 連投を畳んだインシデント数を併記する
- **月別分布**: 直近に集中しているテーマは、既存ルールで未カバーである可能性が高い

PJ 固有の語で数えたい場合は `--patterns` に JSON を渡してパターン定義を差し替える。

**完了基準**: 反復文言の一覧とパターン別の集計が両方出力されており、次の Step でサブエージェント報告と突き合わせる基準値として使える状態になっている。

### Step 3: 並列クラスタリング

Step 1 が書き出した `chunk*.txt` を1体1チャンクで subagent に渡す。**2系統を別レンズとして扱い、同じチャンクに両方を要求しない**（片方に引きずられて他方の抽出が薄くなる）。

各 subagent への指示に含める要素:

- 対象ファイルを**全文**読むこと（cat または分割 read）
- 拾うもの / 拾わないものの列挙（訂正レンズなら単発の作業依頼を除外、既定化レンズなら一回性の作業内容を除外）
- 出力形式: 症状の一般形 / 出現件数と日付レンジ / 原文ママの引用（日付付き）/ 何が起きたか / 規則候補または既定化案
- 既定化レンズでは**機構タイプ**も選ばせる: 指示ファイルの既定値 / スキルの手順に組み込む / hook・設定値で強制 / 新規スキル / 自動化できない
- 推測で埋めず、引用は実在テキストから取ること

**完了基準**: 全チャンクの報告が揃い、各件に日付付きの原文引用が付いている。

### Step 4: 一次データとの突き合わせ

サブエージェントの件数をそのまま採らない。次の理由で実態とずれる。

- 同一文言の連投・複数セッションへの一括送信を別件として数える（インシデント数に正規化する）
- チャンク境界で分かれたテーマの頻度を過小に見る
- 除外対象（teammate メッセージ・完了通知）をユーザー発話として拾うことがある

Step 2 の集計と grep で件数を検証し、**インシデント数**に直してから採用する。

**完了基準**: 提案に載せる全件について、件数が Step 2 の集計または自分の grep で裏付けられている。

### Step 5: 既存指示との突き合わせ

各件を4分類する。分類が提案の形を決める。

| 分類 | 意味 | 打ち手 |
|---|---|---|
| **不在** | 規則がどこにもない | 追記で効く。最優先 |
| **事後検知** | 規則はあるが、失敗してから気付く設計になっている | 手順の差し替え（事前確認に変える） |
| **過剰適用** | 規則が広すぎて、適用されたくない場面にも発火している | 除外条件の追加 |
| **対応済み** | 既に反映されている | 提案しない。ただし「いつ反映されたか」と「以後に再発があるか」を確認する |

`git log` で該当ルールの追加日を取り、**叱責 → ルール追加で対応済み**なのか、**ルール追加後の再発**なのかを分ける。後者は追記では止まらないため、hook・permissions.deny・スキルの完了基準への格上げを検討する（@context/claude-customization-guide.md「3回言っても直らないルールはhookへ格上げ」）。

**完了基準**: 全件が4分類のいずれかに割り当てられ、「対応済み」に分類したものは反映先とコミットが特定されている。

### Step 6: 提案の作成と提示

- 提案文面は**一般化した規則の形**で書く（実例・日付・固有名詞を含めない。@AGENTS.md「指示ファイルの書き方」）。引用と日付は提案書の根拠欄に置き、規則文面には持ち込まない
- PJ 固有の既定値（そのリポジトリのブランチ戦略・ポート番号等）は user-level に書かない。PJ の `CLAUDE.md` に置く先として提示する
- トレードオフがある項目は「判断が必要な点」を明記する。判断軸を書けないなら提案として出さない
- kairan MCP が接続されている場合は、比較軸が3つ以上あるため HTML で publish する（@AGENTS.md「kairan MCP による情報提示・意思決定」）
- **担保していない範囲を明記する**: 件数の畳み方、長い発話の打ち切り、PJ-level 指示ファイルを見ていないこと

**完了基準**: 各提案に、実測値・既存ルールの分類・反映先ファイル・提案文面の4点が揃っている。

### Step 7: 採否の確認と引き渡し

提案の適用は本スキルでは行わない。採否をユーザーに確認し、採用分を `/update-inst` に渡す。

**完了基準**: 採否がユーザーから返っている、または返答待ちであることを報告している。

## Gotchas

- **fish のグロブは no-match でコマンド全体が失敗する**。`rm -f chunk*.txt` は該当ファイルが無いと後続まで実行されない。ファイル削除は Python の `glob` 側で行う（スクリプトは対応済み）
- **teammate メッセージ・サブエージェント完了通知・compaction 要約は user ロールで届く**。発話として数えると頻度が壊れる
- **compaction 要約を除外しても原発話は失われない**（要約前の user イベントが同一セッションファイルに残る）。要約を発話として数えると二重計上になる
- **多バイト文字列の集計に `sort | uniq -c` を使わない**（ロケール依存の照合で異なる文字列が誤って統合される）。集計は Python の明示的なカウントで行う
- **長い貼り付け（資料の全文投入）は先頭で打ち切って渡す**。打ち切った件数と位置を報告に書く
- **パターン定義の正規表現は過剰マッチしやすい**。「いい」「また」のような短い語を選択肢に入れると件数が桁で狂う。集計後に例を目視して、意図しないマッチが混じっていないか確認する
- **サブエージェントが「10件出せ」に応えて水増しする**ことがある。件数の下限を要求せず「最大N件」で指定し、該当が少なければ少ないまま報告させる

## 入出力例

```
入力: /directive-mining --since 2026-07-01
Step 1: user イベント 32,344件 → ユーザー発話 1,827件（除外内訳を会計表で提示）
Step 2: 同一文言の反復（最多8回「実装内容と手動検証すべき画面や挙動…をレポートして」）
Step 3: 3チャンクを並列で2レンズ分析
Step 4: サブエージェント報告の「conflict 8件」を grep で 13インシデントに修正
Step 5: 不在=11件 / 事後検知=2件 / 過剰適用=1件 / 対応済み=6件
Step 6: kairan に HTML で publish
出力: 訂正由来 8件 + 既定化 13件の提案書、採否の質問カード
```

## 既存設定への参照

- @context/claude-customization-guide.md（知識の置き場所判定・hookへの格上げ基準）
- @context/workflow-rules.md（Phase 0-5・完了報告の型）
- @context/memory-file-formats.md（分析結果を残す場合の構造）