# Capturing Golden Rules > Use when the same mistake or bad pattern recurs, when a code-review comment is really a convention worth enforcing, or when you catch AI-generated drift/slop and want it to never happen again. Encodes the lesson as a durable rule in golden-rules.md — the feedback-flywheel / harness-layer-learning ratchet — instead of a one-off fix. Generic (language-agnostic). - Skill: `redtropig/capturing-golden-rules` (Agent Skill) - Install (CLI): `npx skillmds@latest add redtropig/capturing-golden-rules` - Raw SKILL.md: https://api.skillmd.com/api/skills/redtropig/capturing-golden-rules/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Redtropig (https://skillmd.com/u/redtropig) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/redtropig/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").