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- — 
- **Why / origin:** 
- **Check:** manual review — 

• 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.

Route the signal to its right home (don't dump everything here)

golden-rules.md is specifically the home for failure → guardrail / anti-pattern signals. Other learning belongs elsewhere — routing keeps each artifact focused:

| Signal | Example | Goes to | |---|---|---| | Failure | "it keeps reintroducing this bug class" | golden-rules.md (this skill) | | Context | a fact / version / convention the AI keeps missing | AGENTS.md (Conventions / Project Context) | | Instruction | a prompt phrasing that reliably works | a skill, or AGENTS.md | | Workflow | a task sequence that reliably produces good work | AGENTS.md / session-handoff.md |

If it isn't a failure-class signal, route it and stop.

How to capture

Append a rule to golden-rules.md:

### GR- — 
- **Why / origin:** 
- **Check:** 

• Tie it to a real failure. The origin line is what makes the rule stick — and lets a future

reader judge whether it still applies.

• Make it checkable. Start with "manual review"; graduate the Check to a grep one-liner or a lint

rule only when the rule is violated often enough to be worth it (invest by frequency × impact — not every rule needs a tool).

• The mechanical convention (what makes a Check runnable by /gc): one backtick-quoted command in

the Check line → golden-rules-check.sh executes it (5s cap); its output is candidate-violation evidence, empty output = clean. Keep "manual review" in the line to stay human-judged — that takes precedence even when the line contains backticked prose.

• Keep IDs unique (GR-1, GR-2, …) so /gc and /status can reference and count them.
• [user] protects a rule. Put [user] in the Why / origin line of a rule the human

authored or explicitly endorsed — /session-end's consolidation offer must never merge, reword, or prune it.

The flywheel

review comment / recurring failure / drift
        │  capture (this skill)
        ▼
   golden-rules.md ──► /gc (drift-analyst) scans every change ──► surfaced before it ships
        ▲                                                            │
        └──────────── prune / refine when a rule misfires ◄─────────┘

golden-rules.md is startup-loaded (AGENTS.md points to it) — a feed-forward Guide — and the checklist /gc enforces as a Sensor. Closing that loop is the point: human taste, captured once, applied to every future change.

Prune — entropy applies to the rules too

Rules rot. Delete dead rules; resolve rules that contradict each other. A golden-rules.md nobody trusts is worse than none. Review it when it stops matching how the project actually works.

Anti-patterns

• Vague rules: "write clean code", "be consistent" — uncheckable, so unenforceable.
• No origin: a rule with no failure behind it is a guess; guesses accumulate as noise.
• Premature automation: a brittle lint rule for a once-seen issue.
• Unbounded growth: 50 rules nobody reads. Prefer few, load-bearing rules.

Related

• /gc + drift-analyst — scans changed code against these rules (the Sensor half).
• anti-hallucination-gates — a recurring "claimed done without evidence" is itself a capturable rule.
• self-correction-loop — a recurring fix pattern is a candidate rule.
• docs-lookup — when unsure how to phrase a Check command for an unfamiliar tool.
• /session-end — its flywheel reflection is the safety net for anything missed; the preferred capture moment is the turn the signal appears (see "When to write").

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Redtropig
• Source: Redtropig/harness-anchor
• License: MIT

Install and usage instructions live in the source repository linked above.