retro

name

retro

description

Convert repeated failures, recurring review comments, and incidents into permanent system improvements — targeted diffs to instructions, skills, agreements, templates, or CI, delivered as small `retro:` PRs and logged. Use this when the same class of mistake or review nit appears a second time, after any incident or rejected agent PR worth learning from, and during periodic reviews of whether the always-on instruction files have gone stale.

Retro

Every guidance file in this repository (AGENTS.md, instructions, skills, templates, workflows) is itself version-controlled and PR-reviewable — which means the system can learn. Retro is the loop that makes it happen: a failure observed twice is not bad luck, it is a missing asset. Fixing the instance helps once; fixing the asset helps every future session of every agent.

Trigger

• The same failure class or review comment appears for the second time (twice is the threshold: once may be noise, and encoding noise bloats the always-on budget).
• An agent PR is rejected, an incident occurs, or a task fails twice — regardless of repetition.
• Scheduled hygiene: periodically ask "which always-on lines have not mattered recently?" and demote them (see Budget rule).

Candidate ledger

The trigger fires at the second occurrence — so first occurrences must be counted somewhere durable. That ledger is retro:candidate issues (AGENTS.md §1: GitHub, never chat or local notes).

1. Search before filing: gh issue list --label retro:candidate --search "<keyword>".
2. File if absent: title retro-candidate: <one-line friction>, body = link to the occurrence plus one line of context, label retro:candidate.
3. +1 if present: comment on the candidate with the new occurrence link. Occurrence count = 1 (the filing) + N (occurrence comments).
4. Promote at count >= 2: run the Procedure below; the retro: PR closes the candidate with a comment linking the fix.

The monthly hygiene job surfaces candidates overdue for promotion.

Classify the root cause, then pick the asset

Root cause	Fix lands in
Agents lacked a fact or decision	docs/agreements/ (via the agreements PR process)
A rule existed only in someone's head or a review thread	.claude/rules/*.md or AGENTS.md (mind the tier — see context-distillation §Tiering)
A multi-step procedure was improvised inconsistently	a skill under .claude/skills/ (new or amended)
The brief allowed the mistake	.github/ISSUE_TEMPLATE/ai-task.yml or the planner quality bar
Nothing would have caught it automatically	a CI check / lint rule / test in .github/workflows/ or the codebase

Prefer the most deterministic asset that can host the fix: a CI check beats an instruction line, because instructions are advice and checks are walls.

Procedure

1. Gather the evidence: links to the ≥2 occurrences (PR review threads, failed runs, issue comments).
2. Write the smallest diff that would have prevented the latest occurrence. Resist writing an essay; one sharp rule outperforms three vague ones.
3. Apply the Budget rule for always-on files (AGENTS.md, CLAUDE.md): they must stay lean (target well under ~150 lines each). When adding a line, look for a line to remove or demote to a scoped/on-demand tier. Unbounded growth of always-on context is how the system gets slowly worse while everyone follows the process.
4. Open a PR titled retro: <what it prevents>, containing the asset diff plus one appended row to docs/agreements/retro-log.md:

| 2026-07-03 | Cloud tasks kept claiming HIL criteria | verification skill + ai-task template: hardware criteria must defer to exec:ide follow-up | #142 #155 |

5. Human review approves — a retro PR changes how all agents behave, so it gets the same scrutiny as an agreement.

Upstreaming project-agnostic fixes

When the root cause is scaffold-generic — it would bite any project built from this template, not just this one — land the fix here first, then open a matching PR on the scaffold template repository and prefix the retro-log Fix cell with [upstreamed]. Project tunings (Sync Pair content, globs, layout maps) never go upstream. This closes the second improvement loop: instances feed the template that future projects inherit (SCAFFOLD-CHANGELOG.md documents versions and the upgrade path back down).

Anti-patterns

• Scar tissue rules: encoding a one-off into always-on instructions.
• Vague morals ("be more careful with tests") — if it cannot change a concrete next action, it is not a fix.
• Fix-without-log: the retro-log row is what lets future hygiene passes see why a rule exists; a rule with no traceable origin cannot be safely removed later.