agentleFS
Sn4kyGitSn4kyGit/qa-agent-blueprint/.claude/skills/retro-learn/SKILL.md

retro-learn

Skill2 starsChanged 7 days agoApache-2.0View on GitHub

Capture, groom, and promote learnings — the session-end step whenever something unexpected happened (selector broke, env oddity, user corrected the format), plus the periodic grooming pass that dedupes and promotes proven learnings into rules/skills/project files. Use at session end or "/retro-learn".

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 1 is distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before writing a new entry, choose its Pattern and distinguishing keywords, then search specifically in _inbox.md, the relevant scoped …

    line 28
  2. Very specific:

    If the condition changed, capture it normally and record that history in Cause.

    line 37
  3. Very specific:

    Only a genuinely new, non-rejected learning goes into memory/learnings/_inbox.md in the fixed format:

    line 43
  4. Distinctive:

    If the surprise was a mistake the agent itself made (not an environment quirk), do a compact 5-Whys first — target the system gap (a rule …

    line 61
  5. Very specific:

    Every run that produced evidence also declares what it learned, in execution_summary.json → learnings …

    line 67
  6. Very specific:

    Only promote when the entry has ≥ 2 distinct runs in execution_summary.json.

    line 101
  7. Very specific:

    Keep memory/INDEX.md in sync: new learning file or project → one-line entry.

    line 116
  8. Very specific:

    If a listed INDEX.md entry is empty or stale, fix or remove it — entries are promises, not decoration.

    line 117

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/retro-learn — Capture → Groom → Promote

The learning loop behind docs/architecture.md → "Layer 4". Three distinct operations; know which one you're doing.

Auto-trigger — groom without being asked

The session-start orientation prints an AUTO-GROOM directive when the inbox crosses any threshold: ≥ 5 entries, the oldest entry is older than 14 days, or the inbox is ≥ 16 KB. When that directive is present, grooming is not optional and does not wait for a /retro-learn command: run one bounded Groom batch plus its eligible Promotions at the end of the session, then report in one sentence what was promoted and whether a backlog remains. Users who never type slash commands are exactly who this exists for — the loop must not depend on anyone remembering one. All gates apply unchanged: seen: 2, the _rejected.md buffer, the validation gate for blueprint-side promotions, the routing re-measurement. Below all thresholds the directive stays a hint to the human, and this skill waits to be called as before.

Capture (every session with a surprise)

Before writing a new entry, choose its Pattern and distinguishing keywords, then search specifically in _inbox.md, the relevant scoped learnings files, and memory/learnings/_rejected.md. Capture is not append-first:

  • An active duplicate in the inbox or a learnings file gets its seen: counter bumped and the new sighting date and product appended (seen: 2 — 2026-10-01 STOREFRONT, 2026-10-08 ADMIN). Do not add a second raw entry.
  • A previously rejected or retired match whose "do not re-propose unless" condition still holds gets only the new sighting date in _rejected.md. If the condition changed, capture it normally and record that history in Cause.
  • Similar symptoms with incompatible causes or solutions are not duplicates. Preserve both sightings, mark the conflict unresolved, and keep it out of promotion until the conflict is resolved.

Only a genuinely new, non-rejected learning goes into memory/learnings/_inbox.md in the fixed format:

## YYYY-MM-DD — <TICKET or context> (<KEY>/<PRODUCT>, if a product was routed)
- Problem: <what happened, 1 sentence>
- Cause: <why, if known — otherwise "unknown">
- Working solution: <what actually worked>
- Pattern: <error-resolution | user-correction | workaround | environment | routing>
- Candidate target: <rule | skill | template | hook | docs | PROJECT.md <KEY> | PRODUCT.md <KEY>/<PRODUCT> | flow-map.md | learnings file>

The Pattern line is one word and pays off twice: it gives capture and grooming a dedupe axis (same pattern + overlapping keywords = duplicate candidate), and it pre-routes the entry — a user-correction always gets the 5-Whys below, a routing entry feeds the registry upkeep under Promote. If none of the five fits, the entry is probably not a learning.

If the surprise was a mistake the agent itself made (not an environment quirk), do a compact 5-Whys first — target the system gap (a rule that was unclear, a check that was missing), not just "I should be more careful."

Capture is declared, not remembered

Every run that produced evidence also declares what it learned, in execution_summary.json → learnings (.claude/rules/core/evidence-policy.md): either the new inbox entries or existing sightings/counters updated, or one sentence stating why there were none. The evidence gate blocks the session end when that declaration is missing — the same firmness the evidence rule has always had, because fifteen prose reminders to "run retro-learn" enforced exactly nothing.

The declaration is a pointer, not the entry: a genuinely new learning still gets the full Problem → Cause → Solution in _inbox.md; a repeat points to the existing entry whose sighting/counter changed.

Groom (weekly, on demand, or when AUTO-GROOM fires)

Batch of ≤ 10, oldest first. Dedup check per entry (inbox + scoped learnings + _rejected.md): duplicate → bump seen:, delete inbox copy. Previously rejected → drop unless its condition changed. Genuinely new → classify (different project → memory/learnings/*.md; sibling product → projects/<KEY>/learnings.md; otherwise → product learnings). Retire stale entries to _rejected.md, never delete. Clear only graduated/deduped/rejected from _inbox.md.

Verify sightings before promotion (0.19.7): run python3 .claude/scripts/verify-sightings.py --since 90 to count distinct execution_summary.json runs referencing each entry. Compare against the self-attested seen: N in _inbox.md. If self_attested > verified, the counter is inflated — do not promote until resolved (check for duplicate captures or non-independent sightings).

Full grooming rules, retirement format, and classification details: docs/rules/core/retro-learn.md → "Groom".

Promote (gate: verified seen ≥ 2 + human approval for sensitive targets)

At seen: 2, verify the sightings against evidence first (see Groom step). Only promote when the entry has ≥ 2 distinct runs in execution_summary.json. Then merge into its named candidate target — condensing replacement edit, not narrative append. Promotions into .claude/rules/, SKILL.md, hooks, or templates require explicit human confirmation — write the proposed change to a proposal file and wait for the user to approve before applying. This prevents poisoned learnings from becoming standing instructions. Promotions into PROJECT.md, PRODUCT.md, flow-map.md, and learnings.md proceed on the verified seen: 2 gate alone (flow-map additionally needs a second independent sighting with provenance note).

Full promotion targets, flow-map evidence gate, human-approval rule, sighting verification, and conflict handling: docs/rules/core/retro-learn.md → "Promote".

Housekeeping

  • Keep memory/INDEX.md in sync: new learning file or project → one-line entry.
  • If a listed INDEX.md entry is empty or stale, fix or remove it — entries are promises, not decoration.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.