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".
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- accessibility-testingSkill
- agentswitchSkill
- api-testingSkill
- bug-reportSkill
- bug-reproductionSkill
- demoSkill
- deploy-to-stageSkill
- exploratory-testingSkill
- failure-analysisSkill
- model-setupSkill
- onboard-productSkill
- onboard-projectSkill
- perf-analysisSkill
- qa-helpSkill
- qa-metricsSkill
- qa-reportSkill
- re-boardSkill
- reconSkill
- release-readinessSkill
- report-to-jiraSkill
- retest-bugSkill
- risk-based-testingSkill
- scaffold-suiteSkill
- security-testingSkill
- skill-reviewSkill
- test-automationSkill
- test-case-managementSkill
- test-reliabilitySkill
- test-ticketSkill
- visual-testingSkill
- webdriverio-testingSkill
- whats-newSkill
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
- Very specific: line 28
Before writing a new entry, choose its Pattern and distinguishing keywords, then search specifically in _inbox.md, the relevant scoped …
- Very specific: line 37
If the condition changed, capture it normally and record that history in Cause.
- Very specific: line 43
Only a genuinely new, non-rejected learning goes into memory/learnings/_inbox.md in the fixed format:
- Distinctive: line 61
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 …
- Very specific: line 67
Every run that produced evidence also declares what it learned, in execution_summary.json → learnings …
- Very specific: line 101
Only promote when the entry has ≥ 2 distinct runs in execution_summary.json.
- Very specific: line 116
Keep memory/INDEX.md in sync: new learning file or project → one-line entry.
- Very specific: line 117
If a listed INDEX.md entry is empty or stale, fix or remove it — entries are promises, not decoration.
≈ “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.
Files
/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 inCause. - 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.mdin sync: new learning file or project → one-line entry. - If a listed
INDEX.mdentry is empty or stale, fix or remove it — entries are promises, not decoration.
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
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.

