capturing-golden-rules

Capturing Golden Rules

A one-off fix repairs today's symptom. A golden rule repairs the whole class — it makes the harness learn so the same mistake can't recur. This skill is the ratchet: turn a recurring failure into a durable, checkable rule in golden-rules.md.

Hashimoto's principle: "Anytime an agent makes a mistake, engineer a solution so it never makes that mistake again." The fix is a guardrail, not a scolding — blame the process, not the agent. You're improving the environment, not the model.

When to capture

Capture when the signal is recurring, not a one-off:

• The same mistake or bad pattern appears a second time.
• A code-review comment is really a convention ("we always do X here"), not a one-time nit.
• /gc (the drift-analyst) flags drift that should have been a rule.

One-off edge cases and personal style stay personal — capture what recurs, or what any contributor would hit. (The archive's lesson: 3 rules, not 30.)

When to write — the same turn, not session end

Capture happens in the turn you recognize the signal — append the rule, then continue the task. Context is a volatile medium: compaction and attention dilution mean a deferred write gets reconstructed from decayed memory (bias) or never happens at all (the intent itself is displaced).

A rough stub written now beats a polished rule written later:

### GR-<n> — <one-line rule>
- **Why / origin:** <paste the evidence at hand: exact error text, file:line, commit sha>
- **Check:** manual review — <what to look at>

• Quote, don't summarize. An origin pasted at the moment of failure cannot be misremembered; a session-end reconstruction can. This is the anti-bias mechanism, not a convenience.
• A manual review Check lands in /gc's [MANUAL] tier — mechanically harmless until graduated.
• Polishing (Check upgrades, tighter wording) is idempotent — /gc adjudication and /session-end's flywheel do it later; a lost lesson cannot be recovered.