The Practitioner's Playbook.
Three checklists, three templates and one failure library — every entry traceable to something that actually happened here.
The narrative volume ends with four disciplines. This is the working version of them: the lists you run before you ship, the three artefacts that carry a judgment from a conversation into a repository, and a failure library in which every entry names the incident it came from. Nothing here is generic advice. Where a rule cannot be traced to an incident in this ecosystem, it was left out. For the underlying mechanism, read the engineering system; this volume only carries what the case itself taught.
Four disciplines, expanded
Each one is a habit, not a tool. Each has a failure it prevents.
1 · Definition before implementation
Acceptance criteria, non-goals and boundaries are written before the first line of code, and intent is phrased in business language that would still make sense with the word "AI" removed. Prevents: round-trips. The measured cost of an undecided direction is 17.1 turns per commit at its worst and 47.07 M tokens per commit last week on MRRC.
2 · Every incident becomes a rule
Fixing the bug is the first link of the chain, not the last. The chain is: field incident → design ruling → machine-readable constraint → pre-write interception. Prevents: the same class of mistake returning under a different symptom. This ecosystem's loops ran 13 and 7 days.
3 · Watch where uncertainty spends
Token peaks are a direction radar: wherever the spend spikes, the direction is undecided. Pair it with the snapshot habit — every important number gets two sources and a cutoff timestamp. Prevents: spending on the wrong problem, and quoting a number that has since changed underneath you.
4 · Keep the two ledgers apart
Product maturity and process evidence are separate books. A passing test suite never closes an open safety issue, and a beautiful registry never promotes a product claim. Prevents: the most comfortable form of self-deception available to an engineering team.
A discipline that is not habit-shaped will not survive contact with a deadline. These four were chosen because each maps to a single decision a person makes dozens of times a week: do I write this down first, do I close the loop, do I look at where the cost is, and do I keep the books apart. If you can only adopt one, adopt the first — the other three are cheaper once acceptance is written down.
Three lists, three moments
Before you accept a requirement, before an edit lands, before you call it released.
Before accepting a requirement
- Can I state the acceptance condition as something a machine could check? If not, the requirement is not ready to be delegated.
- What am I explicitly not doing? Non-goals written down now are the cheapest rework you will ever prevent.
- Does the sentence survive with the word "AI" deleted? If it does not, this is a technology demo wearing a business case.
- Which repository will own the result, and what evidence will the claim rest on — automated test, bench, or field?
Before an edit lands
- Does this change touch anything a registered constraint already covers? Two of the 52 rules exist because a plausible-looking edit was wrong:
cat-no-dnand the deploy-backup rules. - If it touches hardware, is the radio's transmit state known right now — not assumed?
- Is the vendor tree still read-only? Purchased decoder code is not ours to modify; adaptations belong in our own patch layer.
- If this is a fix, which constraint will it become? A fix with no follow-up rule is a fix that will be needed again.
Before calling it released
- Which rung of the product ladder is being claimed — automated test, bench verified, or field verified? Say the rung out loud.
- Is there an open known issue that contradicts the claim? FT710Mobile's unresolved P0 PTT issue stayed public exactly this way.
- Do the two ledgers agree with each other? They are not supposed to.
- If a number appears in the release note, does it carry a census date and a measurement window?
The pre-release item about the product ladder is what keeps the EFHW tuner's claim status at design target instead of "released" — no PCB exists yet. The pre-edit item about constraints is what makes the intercept reproducible, with an exit code, rather than a code review opinion.
Three artefacts worth copying
Copy them literally on Monday. They are shaped this way because a weaker version failed.
Template 1 · Acceptance condition
REQ <one-line requirement, business language, no "AI"> DO <what changes for the user> NON <what is explicitly out of scope> CHECK <how a machine decides pass/fail> RUNG design-target | simulation | automated-test | bench | field | released OPEN <known issues that this does NOT close, or "none">
Every rework spike measured in this ecosystem landed on a week where scope was still moving. The NON line is the cheapest instrument for holding it still, because it converts a boundary from something a human remembers into something an agent can read.
Template 2 · Constraint registry entry
id <short-slug, e.g. cat-no-dn> severity block | warn | info scope <glob of files this applies to> pattern <what to match in the edit> message <what the agent is told, in the imperative> sdd_ref <document + section + ruling id, e.g. AD-014> origin <the incident, with a date and a commit>
origin is the field that turns a style rule into an argument. Every one of the 52 registered constraints traces to a decision or an accident; a rule that cannot fill in origin is an opinion, and opinions get deleted by the next person who disagrees. sdd_ref is what lets the block message explain itself at the moment it fires.
Template 3 · Incident to constraint
1 REPRODUCE write the failing probe; capture the exit code 2 RULE write the design ruling into the SDD, with a ruling id 3 ENCODE add the registry entry: severity, scope, pattern, sdd_ref, origin 4 PROVE re-run the probe; it must now be blocked, with a nonzero exit 5 RECORD put the date and the commit hash in the origin field
Step 4 is the one teams skip, and skipping it is how a documented lesson becomes a documented lesson that nobody follows. If the probe still passes after the rule is written, the rule is decoration. The entire value of the contract era over the document era is that knowledge stops needing to be remembered and starts being enforced at the moment it matters.
Every rule here cost something
Symptom → root cause → what it cost → the rule it became → how to reproduce the check.
| Incident | Root cause | Cost | Rule it became | Reproduce |
|---|---|---|---|---|
| FT-710 frequency drift | DN; is a VFO step command, not a DNR query — polling it every 2 seconds | A live radio drifted about 20 Hz per call | cat-no-dn (ruling AD-014) | Run the guardian check added in 2498ec2 against a probe file; the block exits nonzero |
| Deploy backups filled the disk | Whole-site copies including the server-managed binary directories | Server /var/tmp reached 100% | Per-site backup, thinned and rotated | Compare the archive contents against the exclude list |
| Portal backups had never worked | An unquoted remote heredoc let the local shell expand variables first | Every run printed a backup path that did not exist | Remote heredocs must be quoted (067f565) | git log -S on the heredoc marker |
| The census was wrong by 1.6 billion | One tool's cached-input field is a subset of its input field; another's total already includes everything | A published figure that had to be corrected twice | Per-tool field semantics, written down | Sum both ways and compare to the independent store |
| A harness was published as "not recorded" | One table was queried; the totals lived in a different table | Understated by 485,213,348 | No "unrecorded" verdict until every table is listed | Walk the schema and sum every token column |
| The ledger shrank and drifted | Log retention on one tool; the measuring session included itself | The same script gave different totals 12 minutes apart | Snapshot discipline: cutoff timestamp and a written window for every figure | Run the census twice and diff the totals |
The first four rows closed within days. The last two were found while writing this series, which is why they are the newest rules and the least tested. A failure library that only contains old, comfortably-solved failures is a museum; the entries that matter are the ones you added this month.
Every entry above started as something that annoyed a person enough to write it down. That is the whole method: the annoyance is the raw material, the ruling is the refinement, the registry entry is the permanence — and the fourth step, proving the block actually fires, is the one that separates a lesson from a note. For how these pieces fit into a full engineering system, read the engineering mechanism; for the case that produced them, return to the main article.