gold-standard

Gold Standard

Answer: "For a project that does THIS — are rules/standards/features 100% vs world-class? If not, what's missing?"

Four acts: AUDIT → FILL → ADOPT → CONFORM. Stop at any.

Manual /gold-standard = interactive setup: read references/wizard.md (dual-audience — layman 1-question default · programmer order→bill→pay). The auto/keyword path (the Triggers table) skips it.

Triggers

Keyword	Act
"audit rules" / "gold-standard" / "are we world-class"	AUDIT
"fill gaps" / "complete our rules"	FILL
"work by these rules" / "follow from now on"	ADOPT
"conform old code" / "retrofit"	CONFORM
"fill and adopt" / ACTION=fill-adopt	AUDIT → FILL → summary → ADOPT → offer CONFORM

Acts

ADOPT and every CONFORM fix are gated through ask_question — never assume approval.

1. AUDIT — pick 3–5 named exemplars fresh at run time (the bar moves with the era — never reuse a remembered bar), derive the 100% checklist per dimension, score (✅/🟡/❌/N-A), give overall %. Previously filled/adopted rules are audit subjects too: a rule past its revalidate due date or contradicted by today's exemplars is a gap.
2. FILL — write missing MUST-HAVE rules into the project's rules home (.claude/rules/ → AGENTS.md → STANDARDS.md). Match project style + voice. Cite the exemplar. Invoke source-grounding for version-sensitive claims. Extend existing; never duplicate. Check the retired-rules record first — never resurrect a rule retired with a reason unless the user overrides. No overkill rules — only essential, practical, saturated ones. Stamp each rule: <!-- coalmine: verified <YYYY-MM-DD> · exemplar <name> · revalidate <30|90>d --> — 30d for fast-moving surfaces (agent platforms, model/API versions — ship weekly-to-daily), 90d for general engineering (stricter than every authoritative anchor: OWASP ~4y, NIST/FISMA annual → cheap early warning). CVE/advisory rules re-validate on the advisory EVENT first (Dependabot pattern); their 30d stamp is only the staleness backstop. Event override beats the calendar.
3. ADOPT — treat the completed ruleset as binding for the rest of the session. Code changes still need user approval — adoption governs how to work, not license to auto-edit.
4. CONFORM — scan existing code against adopted rules; report violations (path:line · rule · evidence). Fix on approval: checkpoint → one fix → build+tests → revert if newly red. Style Drift: conform minority patterns to the dominant style (highest average usage); never start a standalone style refactor.
5. RE-VALIDATE (runs inside every repeat AUDIT, or when offered on a past-due stamp) — verdict each CoalMine-stamped rule, all changes choice-gated:
   • still valid → re-stamp the date, touch nothing else (no churn);
   • stale but needed → rewrite against today's exemplar;
   • obsolete (subject removed, platform died, or substance merged into another rule) → delete the rule + record a one-line tombstone in the project's memory/decision log (retired <rule> <date>: <reason>) — dead rules burn context every session; the tombstone blocks the next FILL from resurrecting them.
   • CONSISTENCY (the agent trusts memory/rules it never verifies — so verify them): scan the memory/decision log and any in-repo rule register for (a) a prescribed fix/"decision" that contradicts a binding rule or another decision (e.g. prescribing randomness where a determinism rule forbids it) — a poisoned/stale entry; (b) references to a file, flag, or command that no longer exists. Flag each with the conflicting source quoted; correct only through the choice-gate. This is the semantic half; the mechanical half (node scripts/consistency.mjs: cross-document counts, byte-identical doctrine mirrors, well-formed stamps) runs without an agent.

Exemplar-picking rules, scorecard mechanics, stamp/tombstone formats: read references/method.md before the first AUDIT.

Method

1. Bar — name 3–5 world-class exemplars + why them (cite real programs, not "best practices").
2. Checklist — MUST-HAVE (table-stakes) vs EXCELLENCE (top-tier polish). Each tied to an exemplar.
3. Score — every criterion. 🟡 = half credit. N-A must be justified; unjustified N-A = ❌.
4. Gaps — prioritized: MUST-HAVEs first. Each: criterion · exemplar · effort · impact.

Dimensions (pick relevant)

Correctness · Security · Performance · UX/DX · Docs/onboarding · Testing/CI · Distribution/integrity · Observability · Governance/licensing · Maintainability · Compatibility · Error handling

Discipline

• Don't inflate. 85% should say 85%.
• Every criterion cites a real exemplar — "npm does X", "Cargo does Y". No unsourced "best practice".
• State dimensions not assessed + why.
• Blocked lookups: if sandbox/network blocks an external check, mark it N-A with justification — never guess.
• Multi-source grounding: never score from memory or a single source — cross-reference exemplars, registries, advisory feeds (GHSA/OSV/NVD).

Output

1. Bar — category + named exemplars
2. Scorecard — | dimension | criterion | tier (must/excellence) | exemplar | status | evidence |
3. Per-dimension % + overall % (list N-A exclusions)
4. Gaps — criterion · exemplar · effort · impact
5. Verdict — 1 line + top 3 moves