learning-aggregator

学びの集約

すべてのセッションにわたる .learnings/ ファイルを読み込み、パターンを見つけて、昇格候補を優先順位順に一覧化します。これは外側のループにおける検査ステップです。

このスキルがないと、.learnings/ は書き込み専用のログになります。パターンが蓄積しても、誰もまとめません。誰も確認しないため、同じギャップが2週間後に再び発生します。

使用するタイミング

• 週次の定期実行 — スケジュールまたは手動で、蓄積された学びを確認する
• 重要なタスクの前 — タスク領域に既知のパターンがあるか確認する
• セッションが集中した後 — スプリントやインシデントの調査結果を統合する
• エントリの Recurrence-Count が昇格しきい値（>= 3）に達したとき — 全コンテキストを確認して候補を検証する

出力内容

ギャップレポート — 昇格しきい値に達した（または近づいている）パターンを、根拠と推奨アクションとともに優先順位順に一覧化したものです。

ステップ 1：すべての学習ファイルを読む

.learnings/ 内の次のファイルを読みます。

ファイル	内容
LEARNINGS.md	修正、知識のギャップ、ベストプラクティス、繰り返し発生するパターン
ERRORS.md	コマンドの失敗、API エラー、例外
FEATURE_REQUESTS.md	不足している機能
HEALS.md	self-healing によって記録された、検証済みの実行時の復旧 — 昇格に適した繰り返し発生パターンを示す Handoff ブロックを含む

各エントリのメタデータを解析します。

• Pattern-Key — 重複排除に使用する安定したキー
• Recurrence-Count — このパターンが確認された回数
• First-Seen / Last-Seen — 日付の範囲
• Priority — low / medium / high / critical
• Status — pending / in_progress / resolved / wont_fix / promoted / promoted_to_skill（記録者が使用する語彙です。昇格の準備状況はステータスに保存されず、Recurrence-Count から算出されます）
• Area — frontend / backend / infra / tests / docs / config
• Related Files — 影響を受けるコードベースの箇所
• Source — conversation / error / user_feedback / simplify-and-harden
• Tags — 自由形式のラベル
• Task-ID、Session-ID、Occurrence-ID、Source-Ref、Copied-From — 新しい記録者が使用する任意の来歴 フィールド

ステップ 2：グループ化と集約

グループ化する前に、正準出現を作成します。

1. 同じエントリー ID と正規化された内容を持つコピー済みのエントリーを、複数のリポジトリ内の場所に存在する場合でも統合します。
2. .learnings/、クラウド／ローカルのミラー、フォーク、転送されたトランスクリプト、トレースソース全体で、一致する Occurrence-ID の値を統合します。
3. Occurrence-ID がない場合は、明示された Task-ID、Session-ID、Source-Ref、Copied-From の系譜と正規化されたエビデンスを使ってコピーを特定します。ファイルパスやチェックポイント ID が異なることだけを根拠に、独立したものと推定してはいけません。
4. 同じタスクの発生を説明する .learnings エントリーとトレースイベントは、1つの発生として扱い、裏付けとなるエビデンスとして両方のソース参照を保持します。
5. 安定したタスク／セッションの来歴がないレガシーエントリーでは、系譜を unknown とします。宣言された再発回数は正準エントリーごとに1回、集計に含めることができますが、系譜が不明なエビデンスは、異なるタスク数として最大1件までしか数えられず、それだけでは複数タスクのしきい値を証明できません。

次に、正準出現を Pattern-Key ごとにグループ化します。各グループについて、以下を行います。

1. 正準出現全体で、重複を除いた再発回数を数えます。同じエントリーの重複コピーにある Recurrence-Count を合算してはいけません。
2. ソースファイル数ではなく、安定したタスク／セッションの系譜から異なるタスク数を数えます。
3. 時間枠を計算します。First-Seen から Last-Seen までの日数です。
4. 関連するファイルをすべて収集します。すべてのエントリーのファイル参照を統合します。
5. グループ内のエントリーのうち、最も高い優先度を採用します。
6. エビデンスを収集します。各エントリーの Summary と Details です。

Pattern-Key がないエントリーでは、保守的なグループ化のみを行います。

• 完全一致：同じ Area で、2つ以上の Tags が一致する
• ファイルの重複：同じ Related Files のパスを持つ（一部一致ではなく、パスが完全一致する）
• Summary テキストのあいまい一致は行わないでください。誤ったグループ化は、グループ化されないエントリーよりも問題です。

グループ化されないエントリーには、Pattern-Key を割り当てるよう推奨する別個のフラグを付けます。グループ化されないエントリーは一般的で、想定されるものです。単発の問題や、真に新しい問題である可能性があります。

ステップ 3：順位付けと分類

昇格のしきい値

エントリーは、以下を満たす場合に昇格可能です。

• グループ全体で Recurrence-Count >= 3
• 安定した来歴によって証明された >= 2 個の異なるタスクで確認されている
• 30-day window 内にある

ステータスは表示用メタデータだけでなく、昇格状態の一部です。

• promoted、promoted_to_skill、resolved、wont_fix は、記録された発生に対して終端状態です。履歴として保持しますが、終端状態のみのグループを昇格可能として表示してはいけません。
• 最新の終端イベントより後に新しい pending または in_progress の発生がある場合は、再発／再オープンしたパターンとして分類し、終端イベント後の発生に基づいて昇格可能かどうかを判断します。
• Handoff ブロックは、しきい値に以前到達したことを示すエビデンスであり、すでに終端状態のパターンを再昇格させる根拠にはなりません。

しきい値に近づいている状態

エントリーは、以下のいずれかを満たす場合にしきい値に近づいています。

• Recurrence-Count >= 2
• Priority: high/critical で、再発が1回以上ある

分類

各昇格候補について、ギャップの種類を分類します。

ギャップの種類	シグナル	修正対象
ナレッジギャップ	エージェントが X を知らなかった	プロジェクトの指示ファイルを更新する（CLAUDE.md、AGENTS.md、.github/copilot-instructions.md）
ツールギャップ	エージェントが不足している機能を独自に補った	MCP ツール／スクリプトを追加または更新する
スキルギャップ	同じ行動パターンが繰り返し失敗する	スキルを作成または更新する（/skill-creator を使い、quick_validate.py で検証し、skill-check eval を登録する）
曖昧さ	仕様／プロンプトの解釈が一致しない	指示を明確化するか、例を追加する
推論の失敗	エージェントは知識を持っていたが、誤った推論をした	明示的な判断ルールまたは制約を追加する

ステップ 4：ギャップレポートの作成

構造化されたレポートを出力します。

## Learning Aggregator: Gap Report

**Scan date:** YYYY-MM-DD
**Period:** [since date] to [now]
**Entries scanned:** N
**Patterns found:** N
**Promotion-ready:** N
**Approaching threshold:** N

### Promotion-Ready Patterns

#### 1. [Pattern-Key] — [Summary]

- **Recurrence:** N times across M tasks
- **Window:** First-Seen → Last-Seen
- **Priority:** high
- **Gap type:** knowledge gap
- **Area:** backend
- **Related files:** path/to/file.ext
- **Evidence:**
  - [LRN-YYYYMMDD-001] Summary of first occurrence
  - [LRN-YYYYMMDD-002] Summary of second occurrence
  - [ERR-YYYYMMDD-001] Summary of related error
- **Recommended action:** Add rule to project instruction files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md): "[concise prevention rule]"
- **Eval candidate:** Yes — [description of what to test]

#### 2. ...

### Approaching Threshold

#### 1. [Pattern-Key] — [Summary]
- **Recurrence:** 2 times across 1 task
- **Needs:** 1 more recurrence or 1 more distinct task
- ...

### Ungrouped Entries (no Pattern-Key)

- [LRN-YYYYMMDD-005] "Summary" — needs pattern_key assignment
- ...

### Dismissed / Stale

- Entries with Last-Seen > 90 days ago and Status: pending → recommend dismissal
- Terminal-only patterns → report as historical, not promotion-ready
- Legacy groups without enough stable task provenance → report as unverified cross-task recurrence

ステップ 5：引き継ぎ

ギャップレポートは、以下の用途に使用されます。

1. self-improvement スキル — メインエージェントが昇格ワークフローに従い、候補を再検証し、変更案を提示して、人間の承認を得たルールをプロジェクトの指示ファイルに適用します。Pattern-Key、根拠、再発状況、ギャップの種類、推奨アクション、関連ファイル、トラッカーを渡します。専用のエージェントプリセットは不要です。
2. eval-creator スキル — 評価候補を受け取り、恒久的なテストケースを作成します
3. 人間によるレビュー — 「reasoning failure」または「ambiguity」に分類されたパターンが対象です（これらには人間の判断が必要です）

フィルタリング

• --since YYYY-MM-DD — この日付以降のエントリのみをスキャンします
• --min-recurrence N — 昇格のしきい値を引き上げます
• --area AREA — 特定の領域（フロントエンド、バックエンドなど）に絞り込みます
• --deep — Entire を通じてセッションのトレースも分析します（以下の「セッショントレース分析」を参照）

セッショントレース分析

外側のループは、相互に補完する以下の 2 つのソースから情報を読み取ります。

ソース	内容	頻度	コスト
.learnings/	セッション中に自己改善機能が記録した明示的なエントリです。エージェント自身による振り返りであり、修正、知識の不足、気づいた反復パターンが含まれます。	毎セッション（ホットパス）	ほぼゼロ
セッショントレース	Entire が記録したセッション全体のトランスクリプトです。プロンプト、ツール呼び出し、出力、変更されたファイル、トークン使用量、チェックポイントが含まれます。	週次または必要に応じて（コールドパス）	高コスト — 定期的な実行のみ

デフォルトモードでは .learnings/ を読み取り、エージェントが明示的に記録した内容からギャップレポートを作成します。--deep モードではセッショントレースも分析し、両方のソースから得られた情報を統合します。

両方のソースが重要な理由

.learnings/ に記録されるのは、エージェントが気づき、記録すると判断した内容であり、厳選された一部の情報です。セッショントレースには、エージェントが対処したり、再試行したり、失敗だと認識しなかったりしたパターンを含め、発生したすべてのことが記録されます。

.learnings/ にはないものの、トレースから確認できるパターンの例：

• 再試行ループ：わずかに変化を加えながら、同じツール呼び出しを 3 回以上繰り返します。エージェントは最終的に正しく処理できましたが、最初の失敗は記録しませんでした。
• ユーザーによる明示されない修正：やり取りの途中で、ユーザーが「いいえ、それは間違っています」と伝えました。エージェントは軌道を修正しましたが、誤解したことは記録しませんでした。
• 回避されたテスト失敗：テストが失敗したため、エージェントは方法を変え、新しい方法でテストに合格しましたが、最初の失敗は忘れられました。
• コンテキスト引き継ぎの原因：引き継ぎが発生したという事実だけでなく、どのドリフトシグナルが実際に引き継ぎを引き起こしたかを確認できます。
• トークン／時間の異常：出力に対してコストが不釣り合いに高いセッションです。エージェントが自覚していない非効率性を示すシグナルとなります。

エージェント自身では報告できないため、これらのパターンは外側のループにとって非常に価値があります。セッショントレースだけがこれらを確認できる唯一のソースです。

--deep モードを実行するタイミング

トレース分析はセッションごとには行いません。定期的に実行します。

• 週次のスケジュール実行（最低限、推奨）：スプリントまたは複数セッションが続いた後
• インシデント後：問題が発生し、その原因を把握したい場合
• 昇格前：パターンをプロジェクトの指示ファイルに反映する前に、実際のセッションで繰り返し発生することを確認します
• 手動実行：/learning-aggregator --deep --since 7d

セッションごとにトレース分析を実行すると、セッションをまたいだパターンが複数のセッションを経て初めて明らかになるため、新たなシグナルを得られないままトークンを消費します。

Entire でトレースを読み取る

--deep が指定されると、このスキルは entire CLI を使ってシャドウブランチのデータを照会します。

# Check availability
entire --version

# List recent checkpoints as JSON (id, date, session_id, message, tool_use_id)
entire rewind --list

# Read a checkpoint's full transcript
entire explain --checkpoint <id> --full --no-pager

# Or raw JSONL
entire explain --checkpoint <id> --raw-transcript --no-pager

# Filter to one session
entire explain --session <session-id-prefix>

# Generate AI summary (expensive, use sparingly)
entire explain --checkpoint <id> --generate

entire がインストールされていない場合、現在のリポジトリで Entire が有効になっていない場合、または entire rewind --list が成功してチェックポイントを 1 つも返さない場合、--deep は .learnings/ のみを使うモードに切り替わり、ギャップレポートに制限の詳細を正確に記載します。チェックポイントの一覧が空であることは、セッションが発生していない証拠にはなりません。

トレースから抽出する内容

時間枠内の各チェックポイントについて、未加工のトランスクリプトを解析し、次の項目を確認します。

1. ツール呼び出しの繰り返し — 同じツールと類似した引数が3回を超える場合は、リトライループの可能性があります。パターンキー：retry-loop.<tool>
2. ユーザーによる修正のマーカー — エージェントのアクション直後に、ユーザーメッセージに「no」、「wrong」、「actually」、「instead」が含まれる場合。パターンキー：correction.<area>
3. ツール出力のエラーパターン — error、failed、Tracebackなどは失敗の候補シグナルであり、失敗の証明ではありません。記録されたツールのステータスと照合します。パターンキー：error.<category>
4. ハンドオフトリガー — context-surfing の終了イベントと、どのドリフトシグナルが発生したか。パターンキー：drift.<signal>
5. アプローチの変更 — 明示的な方向転換なしに、タスクの途中でエージェントが戦略を変更すること。パターンキー：approach-switch.<domain>
6. トークンの異常 — 類似したタスクタイプの中央値の2倍を超えるトークン数のセッション。パターンキー：cost.<task-type>

可能な場合は、各検出結果を自己改善と同じ分類体系（harden.input_validation、simplify.dead_codeなど）に正規化します。.learnings/ の証拠との重複排除に必要なトレースソース、チェックポイント、セッション、タスクの系譜は保持してください。

ギャップレポートで2つのソースを統合する方法

--deep を実行すると、ギャップレポートの各パターンに sources フィールドが追加されます。

promotion_ready:
  - pattern_key: "harden.input_validation"
    recurrence_count: 5
    sources:
      - .learnings/LEARNINGS.md (3 entries)
      - entire:traces (5 occurrences across 4 sessions)
    confidence: high  # appears in both sources
    evidence:
      - "LRN-20260401-001: Missing bounds check on pagination"
      - "entire:1ca16f9b: Retry loop on /api/search — pageSize rejected 4 times"
      - "entire:8bf2e4cd: User correction 'validate before DB query'"
    entire_checkpoints:
      - 1ca16f9bb3801ee2a02f2384f31355a54b81ea00
      - 8bf2e4cd63d01040b38df07c43f73e0f15d05ac9

両方のソースに含まれるパターンは、どちらか一方だけに含まれるパターンより確度が高くなります。.learnings/ にしかないパターンは、熱心なエージェントによる過剰な記録の可能性があります。トレースにしかないパターンは、ノイズの可能性があります。シグナルが最も強いのは、両者が重なる部分です。

トレースソースの互換性

デフォルト実装では、entire rewind --list と entire explain コマンドを使用するEntire（v0.5.4以降）を対象とします。この仕組みはソースに依存しません。環境から次の情報が取得できる場合は、ドキュメント化されたClaude、Copilot、Codex、またはその他のセッションソースを使用できます。

• 最近のチェックポイントの一覧（ID、タイムスタンプ、セッションIDを含む）
• チェックポイントのトランスクリプトを読み取る機能
• 頻度によるフィルタリングに使うタイムスタンプ

...これらを満たすソースは、トレースソースとして使用できます。他の記録ツール用のアダプターは、scripts/ または gh-aw の mcp-scripts を使って追加できます。

任意の非公開トランスクリプト保存場所をスクレイピングしたり、ドキュメント化されたソースがない場合にアダプターを作成したりしないでください。どのアダプターも、Step 2 で使用するものと同じ安定したタスク／セッション／ソースの系譜と、出現箇所のフィンガープリントを出力する必要があります。未対応または空のソースは、独立した証拠として扱わず、その旨を報告してください。

永続化

作業ディレクトリから .learnings/ を読み取ります。これが唯一の永続化モードです。このスキルは、対話型セッションでは外部メモリーバックエンドと連携しません。ワークフロー実行間でCI側のデータを永続的に保存する場合は、必要に応じて gh-aw の repo-memory（Gitブランチによる永続化）を使用できる learning-aggregator-ci を参照してください。作成されるブランチは通常のGitブランチであり、必要に応じてローカルにフェッチできますが、対話型スキル自体はローカルファイルのみを読み取ります。

ギャップレポートのトラッカーID

ギャップレポートの各昇格候補には、パターンキーを設定した tracker フィールドが含まれます。self-improvement の昇格ワークフローは、これをハンドオフ時に保持し、必要に応じてプロジェクトの指示ファイルにコメントとして追加します。eval-creator は評価ケースでこれを参照します。有効になっている場合、インラインの来歴を監査するには、リポジトリとGitHub全体で tracker:[pattern-key] を検索してください。

このスキルが行わないこと

• .learnings/ ファイルを変更しません（読み取り専用の分析です）
• 昇格を適用しません（人間の承認を必要とする自己改善ワークフローが行います）
• 評価を作成しません（eval-creator が行います）
• コードを修正したり、テストを実行したりしません
• 曖昧なパターンについて人間の判断に取って代わりません
• セッションごとのトレース分析に --deep を実行しません。定期的な実行または明示的な呼び出し時にのみ実行します
• Entireを必須としません。トレースソースが利用できない場合は、.learnings/ のみを使うモードにフォールバックします