Audit Patterns

Overview

Grade a codebase against the Battle-Tested Patterns catalog: for each pattern it implements, fetch the canonical doc page and check the implementation against that doc's invariants — not against the name the codebase gave it. The most valuable output of an audit is not a score; it is the mislabel — code called a "semaphore" that is actually a mutex, an "MVCC" that keeps a single version. Those are the claims that mislead developers into expecting guarantees the code does not provide.

Companion skill: Inventory using the adopt-pattern skill's catalog, or the pattern docs at https://github.com/Totoro-jam/battle-tested-patterns/tree/main/docs/patterns. This skill is the inverse of adopt-pattern: that one runs the catalog forward (add a pattern); this one runs it backward (grade patterns already there).

When to use

• A reviewer asks whether a codebase's patterns are implemented correctly.
• Someone asks "is this really a <pattern>?" or "do we honor X's invariants?".
• A periodic conformance check after a release, to catch new mislabels/drift.

When NOT to use: adding a new pattern (use adopt-pattern), or general code review with no pattern claim in play.

Workflow

1. Inventory

List the catalog patterns the codebase implements. Match by shape, not name — a class named RateLimiter may be a different pattern, and a circuit breaker may exist unnamed. Hunt by shape: retry/backoff loops, lock or lease primitives, caches with eviction, state enums with transition switches, ring/circular buffers, breaker/trip counters, subscriber lists. Record the file(s) for each candidate. Only inventory patterns the codebase actually engages; do not pad the audit with absent ones.

2. Conformance — fetch the doc, never grade from memory

For each candidate, fetch the canonical doc page and read Core Idea (the invariant), When NOT to Use, and Production Proof (the reference shape). Then read the actual implementation. Grade against the doc's headline invariant.

3. Gap analysis — classify the deviation

Assign a verdict (scale below). The judgment is distinguishing faithful from divergent from mislabeled:

• Meets the invariant faithfully → ✅
• Meets the intent a different way (different algorithm/model) → 🟡
• The developer/framework enables it but does not provide it → 🔵
• It is actually a different catalog pattern → 🔁 (the mislabel — flag loudly)
• Not present → ⚪ (absence is N/A, not a failure, unless the pattern is clearly needed)

4. Evidence — cite code + doc

Every verdict cites a file:line in the codebase and the doc invariant it was graded against. A verdict without a citation is an opinion, not an audit.

Verdict scale

Scorecard format (the output)

Produce one table, optionally grouped by catalog category:

Then 2–4 headline findings, leading with the mislabels (🔁) and real gaps — those are what the audit is for. Faithful rows are reassurance, not the point.

Common mistakes

• Grading from memory instead of fetching the doc — invents invariants. Fetch every candidate's doc page.
• Accepting the code's own label — you will rubber-stamp a mutex called "Semaphore." Grade against the doc, not the class name.
• Treating absence as a bug — a pattern not present is ⚪/N-A unless the codebase clearly needs it.
• Verdicts without file:line — an audit is evidence, not vibes.
• Auditing all 46 — grade only the patterns the codebase engages.

Example (compressed)

Auditing an HTTP/MCP framework:

Headline: two over-claims (Semaphore→mutex, MVCC→single-version) that would mislead a developer expecting counting-semaphore or multi-version guarantees; one genuine gap (no circuit breaker).