agentleFS
derrickmehaffyderrickmehaffy/brain-template/.claude/skills/brain-retro/SKILL.md

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

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
  1. Distinctive:

    Run it right after the failure, on what actually happened.

    line 40
  2. Very specific:

    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.

    line 57
  3. Distinctive:

    Never re-route by judgement instead.

    line 80
  4. Very specific:

    When the cause was a wrong stored fact rather than the skill, the fix is that practice, through brain-write-practice.

    line 82
  5. Very specific:

    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.

    line 87

≈ “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

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 status shows 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 usage lists 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

  1. 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.
  2. 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.
  3. Write one row: a failure goes in docs/RETRO-LOG.md, work no skill fit goes in docs/UNCLASSIFIED-LOG.md. Read references/logs.md for both row formats. Write the row before proposing anything, so the failure is on record even when the fix is declined.
  4. 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.
  5. 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.
  6. 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; a declined fix gets declined: <reason>. Otherwise it stays open, which is honest.

The fix table

What happenedThe one changeMade by
The brain's own skill (its prefix is in brain.json) went wrongOne concrete edit to that skill: the missing step, rule or reasonbrain-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 editbrain-upstream; in the template, brain-write-skill for a skill
Output written while its skill never ran, or a skill imitated rather than invokedA gate rule on that output's path in brain.json gatesbrain-write-skill
The same kind of input went to different skillsA rule and a cases entry in that router's rules.json, or a router where the entry point has nonebrain-write-skill
A router fell to default although an existing skill fitsA 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 fitsAn UNCLASSIFIED-LOG.md row saying what a skill would needthis skill
The same kind of unclassified row appears a second timeA new skill, suggested to the personbrain-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, a rules.json or a template-owned file from here.
  • RETRO-LOG.md is history: never rewrite an old row except its Status. rename-skill leaves it alone for the same reason.
  • A row holds no secret, no .env value and nothing .brain-private lists; the pre-commit guard refuses those anyway.
  • Commit through brain-sync.

Done when

  • One row for this failure is in docs/RETRO-LOG.md or docs/UNCLASSIFIED-LOG.md, in the format of references/logs.md.
  • The row names one change, or reads open because 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> or declined: <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-sync to commit.

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.