headron — feed Headron's failure ledger

Portable across agents: a skill folder any skill-aware runtime can load, and plain instructions any other model can follow. The ledger is atlas.yaml/agent_failure_modes in Headron Software (github.com/HLIntel/Headron); work in a branch, never on main. One entry per SHAPE.

Before the change: read the lesson for it

headron failures --for <file-or-task> returns the few recorded shapes that share words with what you are about to change, each with its tell and the move that replaces it (do:). Make that move; headron successes --for <task> lists moves directly, each with when it applies and how to verify it was made. For broad discovery, headron find <query> provides instant search, and headron sweep maps architectural tiers and shards.

When to run it — people, agents and models alike

Run it the moment any of these happens, in the same turn, before moving on:

• a gate, test, build or check fails, or passes only after a retry;
• an answer, command, path or number turns out wrong, invented or stale;
• a guard fires on correct work, or stays silent on broken work;
• a document, count, name or version disagrees with the tree (drift);
• a result looks better than expected and nobody has attacked it yet;
• a person says "that's wrong", or you catch yourself undoing your own last step.

Steps

1. Name the shape, not the instance: a snake_case id starting a_ or an_ that names the mechanism, never the file it happened in.
2. Draft it: python scripts/atlas.py failures <id> --draft '<what happened>' prints a recorded id's bump, or the nearest shapes and an entry line. Same mechanism: bump sightings, sharpen tell, go to 5. A second sighting means a guard is now owed.
3. New shape, six lines or fewer: shape (the mechanism), looks_like (how it reads from outside, usually as success), tell (the one observable that separates it from its neighbours), sightings: 1, prevented_by, and EITHER enforced_by: [module.function] OR unenforceable plus closed_by plus intake: <contract version>. Fill the drafted line's blank fields and run it: it generates every value and reads the entry back — never hand-quote YAML.
4. Guard it now when you can: a check that fails on the shape, a planted case in scripts/atlas_test.py with its expected count raised, and a clean sweep of the whole tree. Intake must graduate within two minor versions; the build refuses it after that.
5. Fix the cause when the break is in work this session produced. Never caption a bad result.
6. Verify: stage, python scripts/atlas.py index --write, stage, then python scripts/atlas.py check and python scripts/atlas_test.py, judged on the exit code; land with python scripts/branchstate.py --land.
7. Report one line: id · new | sighting N · guarded | intake.

A chat that cannot edit files answers with the entry itself, ready to paste. Stamp the contract version, never a calendar date. Sweep with a scanner or command grep: an agent shell's grep may skip ignored files.

Success

One ledger entry exists, on a branch, naming a SHAPE:

• The entry is in atlas.yaml/agent_failure_modes on a branch — never main — and the branch or PR is named in the output. headron is the PUBLIC repo: no secret and no private path, ever.
• It names the SHAPE, not the instance, and states the one observable that separates it from correct behaviour. An entry a guard cannot be written against is prose.
• It carries the instance COUNT. A second sighting is a rule; a third means the evidence was there twice and nothing was built.
• A run that describes the failure in chat and lands no entry has failed, however good the description was.