brain-retro
Skill2 starsChanged 13 days agoMITView on GitHub
Record what went wrong when a skill failed on real work, or when work fit no skill, or which skills go unused, and propose the one change that fixes it: an edit to the brain's own skill, a missing gate rule, a missing router rule, or an upstream suggestion. Use when a skill just went wrong on real work, when output was written without its skill running, when the same kind of input went to different skills, when a router fell through to its default, or to review which skills are used. Does NOT write or edit the skill itself, which is brain-write-skill, and does NOT edit template-owned files, which is brain-upstream.
- Reads credentials
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- brain-setupSkill
- brain-syncSkill
- brain-upstreamSkill
- brain-write-modSkill
- brain-write-practiceSkill
- brain-write-scriptSkill
- brain-write-skillSkill
- template-intakeSkill
- template-make-brainSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
Run it right after the failure, on what actually happened.
- Very specific: line 57
Close the row: if the change lands in this session: Status fixed <YYYY-MM-DD>, or upstream <id> once brain-upstream has written its entry.
- Distinctive: line 80
Never re-route by judgement instead.
- Very specific: line 82
When the cause was a wrong stored fact rather than the skill, the fix is that practice, through brain-write-practice.
- Very specific: line 87
Before writing an UNCLASSIFIED-LOG.md row, read the log for the same kind of work and fill Seen before with the earlier row's date, or no.
≈ “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
brain-retro
A failure on real work is the cheapest moment to improve the brain, because the cause is still in view. This skill writes the failure down and proposes the one change that would have prevented it. It never makes that change itself: the skill that owns the file does, so the change is placed in the routing map, linted and gated like any other.
Where this sits
<!-- where:begin — generated by _meta/brain routing sync; do not edit -->Runs after: brain-setup
Hand to next: brain-upstream · brain-write-mod · brain-write-skill
Reserved output: writing docs/RETRO-LOG.md needs this skill to have run.
Reserved output: writing docs/UNCLASSIFIED-LOG.md needs this skill to have run.
<!-- where:end -->Call it directly when: a skill just went wrong, output was written without its skill, the same kind of input was routed differently, or a router returned its default; nothing needs to run first.
When it fires
- A skill went wrong on real work: wrong output, a skipped step, the person had to correct it.
- Output was written while the skill that owns it never ran, or a skill was read and imitated
instead of invoked.
_meta/brain gate statusshows which skills ran this session. - The same kind of input went to different skills on different occasions.
- A router fell through to its
default(which is this skill unless the brain says otherwise), or work came in that no skill fits. - A periodic look at what the brain is used for:
_meta/brain usagelists each skill's runs and the skills that never ran. A skill unused for months is a candidate to merge or remove, and the busiest are where an improvement pays most; propose one change for the person, as below.
Run it right after the failure, on what actually happened. A retro about a hypothetical has no evidence to test the fix against.
Sequence
- Say what happened in two lines: the skill (or none), the input, what it did, what it should have done. Take it from the output and the conversation. When the cause is not clear, ask the person rather than guess: a wrong cause produces a fix to the wrong thing.
- Pick the fix from the table below. One failure gets one change, the smallest that would have prevented it. Needing two changes for one failure means the cause is not pinned yet.
- Write one row: a failure goes in
docs/RETRO-LOG.md, work no skill fit goes indocs/UNCLASSIFIED-LOG.md. Readreferences/logs.mdfor both row formats. Write the row before proposing anything, so the failure is on record even when the fix is declined. - Propose the change in one or two lines: which file, what changes, and why it would have caught this case. Hand it on only on the person's yes.
- Hand it on to the skill the table names and let it do the work. Do not make the edit here: that skill places, checks and gates the change, and for a skill file the gate refuses it anyway.
- Close the row if the change lands in this session: Status
fixed <YYYY-MM-DD>, orupstream <id>oncebrain-upstreamhas written its entry; a declined fix getsdeclined: <reason>. Otherwise it staysopen, which is honest.
The fix table
| What happened | The one change | Made by |
The brain's own skill (its prefix is in brain.json) went wrong | One concrete edit to that skill: the missing step, rule or reason | brain-write-skill, on a yes |
A brain-* skill went wrong, or the fault is in _meta/ | An upstream suggestion; in the template's own checkout (role template, local/ present), a direct edit | brain-upstream; in the template, brain-write-skill for a skill |
| Output written while its skill never ran, or a skill imitated rather than invoked | A gate rule on that output's path in brain.json gates | brain-write-skill |
| The same kind of input went to different skills | A rule and a cases entry in that router's rules.json, or a router where the entry point has none | brain-write-skill |
A router fell to default although an existing skill fits | A router rule for that skill (a RETRO-LOG.md row) | brain-write-skill |
No skill fits the work, including a router default with nothing that fits | An UNCLASSIFIED-LOG.md row saying what a skill would need | this skill |
| The same kind of unclassified row appears a second time | A new skill, suggested to the person | brain-write-skill |
Why a gate and not a reminder: a skill imitated from memory skips its references/ silently,
and "always call the skill" is exactly the instruction that gets talked past. A gate rule does not
depend on the judgement that failed.
Why a rule and not a better reading: routing by reading is what sent the same input to different
skills. A router decides by rule (_meta/brain route <router>/rules.json --set <field>=<value>), so
the fix is the rule, plus a case that pins this input to its skill so a later edit cannot undo it.
Never re-route by judgement instead.
When the cause was a wrong stored fact rather than the skill, the fix is that practice, through
brain-write-practice; the skill was right to trust it.
Unclassified work
Before writing an UNCLASSIFIED-LOG.md row, read the log for the same kind of work and fill
Seen before with the earlier row's date, or no. At the second occurrence, suggest
brain-write-skill for a skill that covers both rows: two real cases say what the skill needs, one is
a guess. Recording the row does not do the work; say so, and carry on as the person chooses.
Rules
- Log, propose, hand on. Never edit a skill,
brain.json, arules.jsonor a template-owned file from here. RETRO-LOG.mdis history: never rewrite an old row except its Status.rename-skillleaves it alone for the same reason.- A row holds no secret, no
.envvalue and nothing.brain-privatelists; the pre-commit guard refuses those anyway. - Commit through
brain-sync.
Done when
- One row for this failure is in
docs/RETRO-LOG.mdordocs/UNCLASSIFIED-LOG.md, in the format ofreferences/logs.md. - The row names one change, or reads
openbecause the cause is not pinned yet. - The person said yes or no to the change, and on a yes it went to the skill the table names.
- The row's Status matches what happened:
open,fixed <date>,upstream <id>ordeclined: <reason>. - An unclassified row says whether it was seen before; a second occurrence produced a suggestion
for
brain-write-skill. - The log change is handed to
brain-syncto commit.
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.

