The AI-Native Pattern Card Format
01Discipline v0.2 · status: BETA · T1 · supersedes part of GUIDE-SPEC-AUTHORING-v0.1
02Every pattern, scaffold, rule, and anti-pattern in the Discipline is authored as a card in this shape. True of the scaffolds, not yet of the rest — and the gap is registered rather than silent. Each stack's cards/ holds INDEX.md plus scaffold-a … scaffold-i and nothing else; the seven rule and anti-pattern cards this sentence covers (rule-closed-vocabulary-naming, rule-cell-closure, rule-contract-first-ordering, rule-position-is-a-resource, rule-uniformity, antipattern-god-file, antipattern-lying-prose) are listed by name under "Pending cards (named, not yet authored)" in every stack's index, deferred deliberately "to honor minimal sufficiency". Read this as the format's scope, not as a completed inventory.
03The format is a synthesis of three parents: the GoF design-pattern template (teaches WHEN to apply), the OpenJDK JEP template (teaches WHAT COUNTS AS DONE and at what cost), and a third operational layer with no precedent in either — because both predate AI readers.
0. Why three parents
- 04GoF → recognition & navigation. Its load-bearing sections for us are Applicability (how to RECOGNIZE the situation from the code) and the neighbour-pattern pointer GoF calls Related Patterns, which this format carries under the name Collaborations (§1 Band 2 — where to go if this feels wrong).
- JEP → accountability & tradeoffs. Its load-bearing sections are Goals/Non-Goals (scope discipline — the most-violated boundary in AI work), Risks & Assumptions, Alternatives.
- Operational layer → execution. GoF and JEP assume a human applying judgment once, at design time, with unlimited attention. We know three things they did not: the card is a runtime trigger, raid fuel, and will be read by a weak model that cannot hold all cards at once. So we add Trigger, Routine, Checker, Raid-role, Budget — and we make that layer machine-extractable, so the harness can deliver just the operational extract to a weak reader (the §6 minimal-sufficiency rule of the Manifesto). The authoring half is done; the extraction half has no extractor. All five fields are authored, in a fenced
key: valueblock that a parser could take as-is — so the layer is machine-extractable in the sense of being well-formed. What does not exist is anything that extracts it:card-ops,band_threeandcards/INDEXreturn no reader in any.rs,.ts,.go,.py,.js,.shor config file in the repository, so no harness can deliver the operational extract to anyone.
1. The three bands
05Bands 1–2 are prose for the strong author and the human reviewer (full card = authoring/review artifact).
06Band 3 is a machine-extractable block; the harness ships only Band 3 to a weak reader at runtime once a trigger fires. Specified, not built: nothing ships anything. There is no trigger evaluator, no band selector and no runtime delivery path for a card; a weak reader today is handed whatever a session chose to paste. The block is extractable and unextracted.
BAND 1 — Identity & Recognition (GoF)
- 07Card ID & Name — stable slug = a
spec://anchor (A1). - Classification — two axes (like GoF purpose×scope): layer ∈ {A language-shape, B names, C meta, D context, E verification, F spec-binding, G empirics, H weak-reader}; mechanism ∈ {scaffold class A–I, rule, anti-pattern}.
- Intent — 1–2 sentences, problem in most general form.
- Also Known As — synonyms, so a model trained on different terms still resolves the card.
- Applicability / Recognition — THE central section: how a reader RECOGNIZES the situation from the code (the smell, the syntactic signature, the metric threshold), written to seed a detector.
BAND 2 — Justification & Tradeoffs (GoF + JEP)
- 08Motivation — a concrete scenario of the pain and the fix.
- Structure & Participants — the code shape and the roles.
- Collaborations — interaction with other cards and the toolchain at runtime.
- Goals / Non-Goals (JEP) — explicit scope; what this card does NOT do (prevents weak-agent over-application).
- Consequences — benefits AND costs; what you can now vary independently.
- Alternatives (JEP) — other solutions and when each is actually better.
- Risks & Assumptions (JEP) — what makes it wrong; model/harness assumptions; the sunset condition (R-050).
- Evidence & Transfer-strength — backing
findings.jsonlIDs, evidence class, and the honest tag [E-strong]/[E-mid]/[E-hyp]. Keeps cards falsifiable. Correction to the source, not the field: the field ships and works — every shipped card carries it, and the ids it cites (R2C-008,R2C-003,DR2-019, …) resolve as `#FINDING-anchors inappendix/ATLAS.xml. Resolve them there. Nofindings.jsonl` exists to resolve them against (F-088).*
BAND 3 — Operation (no GoF/JEP precedent; machine-extractable)
09Authored as a fenced ```card-ops block of key: value fields so the harness can parse and deliver it without the prose. Authored as prescribed in 24 of the 27 shipped cards — and by no harness parsed. The three scaffold-d-differential-oracle cards, one per stack, author Band 3 as anchored prose (#TRIGGER, #MODE, `#ROUTINE-) with no card-ops` fence at all, which is the same fields in a shape this sentence does not describe. Since nothing parses either shape, the divergence has never cost anything; it would on the first day an extractor existed.* Fields:
- 10trigger — the precise, ideally machine-detectable condition:
WHEN <signal> THEN apply. - mode —
inline | gate | raid | review(where the trigger lives). - routine — ordered steps, target ≤7, each verifiable.
- checker — the machine verification (conform tier / clippy lint / test), OR
WISHif none yet (A5: a checkerless card is explicitly a WISH). - raid_role —
layer=<phase>,order=after:<cards>,batch=<cell|crate|seam>(how it joins a sweep). - budget — active-rule cost + first-signal latency (feeds lazy-push: when NOT to load this card).
2. The minimal-sufficiency contract (delivery)
11A weak reader at runtime receives the Band-3 ops block only (≈10 lines), selected by trigger match, capped to a small active set. Specified, not built, and the one number in it is already off: no trigger matcher and no cap exist, so nothing selects and nothing limits; and the ops block runs 13 lines in scaffold-a-generators.xml against the stated ≈10, with no checker that could have caught the drift. The rule below it — that shipping whole cards to a weak swarm is forbidden — is sound and is currently kept, when it is kept, by the reader.
12Bands 1–2 are consumed by the strong author when writing the card and by a human when reviewing it.
13This split is mandatory: shipping whole cards to a weak swarm reproduces the AGENTbench bloat failure the discipline forbids.
14If a card's Routine still overloads the weakest readers, it is either split finer or replaced by a Class-I codemod (the card becomes "invoke this checked operation" rather than "follow these steps").
3. Governance
- 15The format is a T1 artifact; changes are versioned and ratified, never silent (R-030). Versioned, not ratified. The version is real — the format carries v0.2 and ships inside a versioned package — but no ratification exists for it: no review gate, no changelog, no approval record anywhere covers this document, and R-030 itself is authored nowhere. Every occurrence of R-030 in the repository is a citation, including two ATLAS entries that say they refine it; the ATLAS roster carries no R-030 record to refine. A ratification mechanism does exist at a different grain — PROP-014's unit lifecycle, where
absent = ratified— and it governs spec units, not this format. "Never silently" is a promise with nothing that could notice a silent change. - A card is BETA until its checker exists and its evidence IDs are non-empty; beta cards are revised on pilot evidence only.
- Cards carry sunset conditions; when a Risk's "would render unnecessary" clause triggers, the card retires with its checker (R-050).
- Empty operational fields are a defect: a card with no trigger and no checker is prose, and prose is what AGENTbench penalized — complete it or mark it WISH. Specified, not built: nothing reads the operational fields, so an empty one is a defect by assertion only. No conform rule, CLI step or gate parses a
card-opsblock, which under the Charter's own A5 makes this a WISH rather than a rule. It is already costing something: three shipped cards —scaffold-d-differential-oraclein all three stacks — carry nocard-opsblock at all, and no gate noticed.