Retro
Teach your coding agent — Claude Code, Cursor, or any AGENTS.md agent — your project's conventions, and turn every correction into a team-shared, git-tracked lesson.
npx -y skills add BCGen/skills --skill retroAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Runs a post-task retrospective - detects user corrections, failures, and repeated mistakes, stages lessons as candidates, and proposes consent-gated improvements routed to their fittest destination (project rule, entry-file fact, memory, backlog, or skill update). Use when a task is complete or about to be marked done, before committing or closing out, or when the user says done, wrap up, or ship it.
SKILL.md
5.7 KB, as published. Nobody here has run it
Retro
Turn what went wrong this task into durable improvements — without letting one-off noise become permanent settings. Never act without user consent.
Step 1 — Detect signals
Scan the current conversation (the whole task, not just the last steps) for:
- Correction: the user overruled, redirected, or fixed your approach or output.
- Failure: a command failed, or an edit was reverted or redone.
- Repetition: the same mistake surfaced twice or more within this task.
No signals — or a retrospective already ran for this task → output at most 2 lines and stop. Write nothing; never double-write provenance.
Evidence rules: only externally observable evidence counts — a hunch with no correction or failure behind it is NOT a lesson. Use only the current conversation; do not read platform transcript files.
Step 2 — Stage candidates
For each evidenced lesson (formats in references/loop-file-formats.md):
- Scan
.ai/learnings/as an index only — filenames, H1 titles, andstatus, never bodies. Match by root cause; read a file's full body only to settle a borderline match (create/reconcile the dir + README per loop-file-formats). Title by root cause, not this task's change, so continued fixes match across tasks. Wording differences do not defeat a match. - Matches an existing file → recurrence: append a provenance bullet, carry it to Step 3.
- New lesson → recommend by evidence, user decides: one-off / no stated
rule → stage (
status: candidate, observe); recurring or the user says it's a rule → fix now (promote directly in Step 3, no observe period). Either way create the file; fix-now keeps it too (promote ≠ cure).
Step 3 — Build proposals (max 3, ranked by impact)
On recurrence, first ask about cure. Read the matched file in full, then
show the full trail (all provenance across tasks) and offer three choices: (a) cured — the user confirms the
problem is perfectly solved, no more adjustment → mark status: resolved
and DELETE the file; (b) harden for next time → promote (keep the file);
(c) keep observing → leave it. Never mark cured automatically.
For a lesson being fixed/hardened, decide its mechanism with the shared routing in references/routing.md — the SAME logic codify uses, so it routes to config / project doc / rule / tool-upgrade / pointer at full parity, not just "a rule." Reconciliation applies first: if the lesson already lives in a rule/doc/config, respect it (propose marking the candidate promoted to it, no duplicate).
retro-specific routes, on top of the shared table:
| Finding | Destination |
|---|---|
| Personal preference (how this user works, not project truth) | The agent's native memory |
| Missing capability or workflow repeated across tasks | New file under .ai/backlog/ (create/reconcile the dir + README per loop-file-formats) |
| An existing skill's gap caused the problem | Update that skill's mistakes/notes section |
Also check rules touched during this task for staleness, overlap, never-triggered content, or redundancy with a tool/hook now enforcing the same thing — when you escalate a lesson to deterministic enforcement, propose retiring the advisory rule it replaces. Deletions and merges count toward the 3.
Step 4 — Present and execute with consent
Present one proposal at a time: the finding, its evidence, the pre-drafted content, the destination, one line on why this destination beats the other routes, and one line on what declining means — phrased for the user's technical background, asked with the platform's option-prompt tool when it has one (Claude Code: AskUserQuestion). Then:
- Approved rule → hand the draft to rule-writing when installed (the
mandatory rule write path). Not installed → print the draft for the
user's own tooling; mention
npx skills@latest add <owner>/<repo>at most once per retrospective, never repeatedly. - Approved fact → fix at the fact's single source per Placement by loading (owning doc, e.g. README, or the entry file); diff first; only the fact, never the harness block.
- Approved memory / backlog / skill update → save or edit, showing diffs.
- Declined → the candidate file keeps
status: candidate; nothing else happens. Setstatus: dismissedonly if the user says so. - Promoted → only after the destination write actually happened, update
frontmatter:
status: promoted,promoted_to: <destination>(rule path, entry file,memory, orskill:<name>),promoted_on: <date>. A printed draft is not a write — the file stayscandidate. Promoted files are KEPT (a later re-promotion to a better mechanism updates them). - Cured → the user confirmed the problem is resolved: delete the learning file (its provenance is already in the destination and git).
Honesty rules
Be brutally honest about your own violations. Reject the rationalizations: "too simple" (simple tasks still produce corrections), "user seems rushed" (the check costs seconds), "nothing went wrong" (then say so in 2 lines), "I'll remember next time" (you won't — the next conversation starts blank).
Reports stay proportional: clean task → 2 lines; findings → short evidence bullets, never essays.