learn

# Learn from a mistake ## 1. Name the mistake Write the mistake as a check: "a list command prints the id before the name", not "be careful with list output". Done when a script could, in principle, detect it. ## 2. Pick the strongest structure that holds it In this order, take the first that works: 1. **A type** the compiler rejects. 2. **A lint rule** in `.oxlintrc.json`. 3. **A test** that scans the code or the command tree, like `src/lib/root-options.test.ts`, which checks cli-core's argv scan agrees with commander. 4. **A script check** in `.agents/scripts/` (verify, a hook). 5. **A review check** in `.agents/checks/`, for judgment a script can't make. 6. **A line in `AGENTS.md` or a skill**, only if nothing above can hold it. A rule already written down that still got broken skips straight to 1–4. Done when you can say why the stronger options don't fit. ## 3. Prove it catches the mistake Make the mistake on purpose. The new structure must fail on it. Remove it: it passes. Run `npm run verify`. Done when you have seen both. ## 4. Delete what it replaces Remove instruction lines the new check makes redundant, in `AGENTS.md` or the skills. Update the rules table in `docs/agents.md`: the rule, what holds it, and how certain it is. ## 5. Ship it on its own One small pull request for the new structure, titled `chore:` or `test:` so it does not release. Done when its diff contains only this rule.