/learning-aggregator

name: learning-aggregator
description: "[Beta] Cross-session analysis of accumulated .learnings/ files. Reads all entries, groups by pattern_key, computes recurrence across sessions, and outputs ranked promotion candidates. This is the outer loop's inspect step — it turns raw learning data into actionable gap reports. Use on a regular cadence (weekly, before major tasks, or at session start for critical projects). Can be invoked manually or scheduled."

Learning Aggregator

Reads accumulated `.learnings/` files across all sessions, finds patterns, and produces a ranked list of promotion candidates. This is the outer loop's **inspect** step.

Without this skill, `.learnings/` is a write-only log. Patterns accumulate but nobody synthesizes them. The same gap resurfaces two weeks later because no one looked.

When to Use

• **Weekly cadence** — scheduled or manual, review accumulated learnings
• **Before major tasks** — check if the task area has known patterns
• **After a burst of sessions** — consolidate findings from a sprint or incident
• **When an entry's `Recurrence-Count` reaches the promotion threshold (>= 3)** — verify the candidate with full context

What It Produces

A **gap report** — a ranked list of patterns that have crossed (or are approaching) the promotion threshold, with evidence and recommended actions.

Step 1: Read All Learning Files

Read these files in `.learnings/`:

| File | Contains | |------|----------| | `LEARNINGS.md` | Corrections, knowledge gaps, best practices, recurring patterns | | `ERRORS.md` | Command failures, API errors, exceptions | | `FEATURE_REQUESTS.md` | Missing capabilities | | `HEALS.md` | Verified runtime recoveries filed by `self-healing` — including `Handoff` blocks flagging recurring patterns ready for promotion |

Parse each entry's metadata:

• `Pattern-Key` — the stable deduplication key
• `Recurrence-Count` — how many times this pattern has been seen
• `First-Seen` / `Last-Seen` — date range
• `Priority` — low / medium / high / critical
• `Status` — pending / in_progress / resolved / wont_fix / promoted / promoted_to_skill (the writer's vocabulary; promotion readiness is computed from `Recurrence-Count`, not stored as a status)
• `Area` — frontend / backend / infra / tests / docs / config
• `Related Files` — which parts of the codebase are affected
• `Source` — conversation / error / user_feedback / simplify-and-harden
• `Tags` — free-form labels
• `Task-ID`, `Session-ID`, `Occurrence-ID`, `Source-Ref`, `Copied-From` — optional provenance

fields from newer writers

Step 2: Group and Aggregate

Build canonical occurrences before grouping:

1. Collapse copied entries with the same entry ID and normalized content, even when they appear in multiple repo locations. 2. Collapse matching `Occurrence-ID` values across `.learnings/`, cloud/local mirrors, forks, forwarded transcripts, and trace sources. 3. When `Occurrence-ID` is absent, use explicit `Task-ID`, `Session-ID`, `Source-Ref`, and `Copied-From` lineage plus normalized evidence to identify copies. Do not infer independence from different file paths or checkpoint IDs alone. 4. Treat one `.learnings` entry and one trace event describing the same task occurrence as one occurrence, while retaining both source references as corroborating evidence. 5. For legacy entries without stable task/session provenance, label lineage `unknown`. They may contribute their declared recurrence once per canonical entry, but all unknown-lineage evidence counts as at most one distinct task and cannot by itself prove the cross-task threshold.

Then group canonical occurrences by `Pattern-Key`. For each group:

1. **Count deduplicated recurrences** across canonical occurrences. Do not sum duplicate copies of the same entry's `Recurrence-Count`. 2. **Count distinct tasks** from stable task/session lineage, not source-file count 3. **Compute time window** — days between First-Seen and Last-Seen 4. **Collect all related files** — union of all entries' file references 5. **Take highest priority** across entries in the group 6. **Collect evidence** — the Summary and Details from each entry

For entries without a `Pattern-Key`, use conservative grouping only:

• **Exact match**: Same `Area` AND at least 2 identical `Tags`
• **File overlap**: Same `Related Files` path (exact path match, not substring)
• **Do NOT fuzzy-match** on Summary text — false groupings are worse than ungrouped entries

Flag ungrouped entries separately with a recommendation to assign a `Pattern-Key`. Ungrouped entries are common and expected — they may be one-off issues or genuinely novel problems.

Step 3: Rank and Classify

Promotion Threshold

An entry is **promotion-ready** when:

• `Recurrence-Count >= 3` across the group
• Seen in `>= 2 distinct tasks` proven by stable provenance
• Within a `30-day window`

Statuses are part of promotion state, not just display metadata:

• `promoted`, `promoted_to_skill`, `resolved`, and `wont_fix` are terminal for the recorded

occurrence. Keep them as history, but do not surface a terminal-only group as promotion-ready.

• If a newer `pending` or `in_progress` occurrence appears after the latest terminal event, classify

it as a regression/reopened pattern and compute readiness from the post-terminal occurrences.

• A `Handoff` block is evidence that the threshold was previously reached, not permission to

re-promote an already terminal pattern.

Approaching Threshold

An entry is **approaching** when:

• `Recurrence-Count >= 2` or
• `Priority: high/critical` with any recurrence

Classification

For each promotion candidate, classify the gap type:

| Gap Type | Signal | Fix Target | |----------|--------|------------| | **Knowledge gap** | Agent didn't know X | Update project instruction files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) | | **Tool gap** | Agent improvised around missing capability | Add or update MCP tool / script | | *