# Design note template
By **Henos D** ([@4ktLuffy](https://github.com/4ktLuffy)) · <henosd19@gmail.com>
Design notes in this repository follow a fixed structure. The structure exists to force
every design decision to answer three questions that are hard to reconstruct later:
- **Why did we believe this?**
- **How would we know we are wrong?**
- **What should the next contributor actually do?**
A note that cannot answer all three is not yet ready to be written down.
---
## When to write one
Write a design note when a change **alters what the project's evidence means**, or when a
future contributor could plausibly undo it because the reason is not visible in the code.
Typical triggers:
- a verdict, tolerance or objective changes, so previously recorded results now mean
something different
- a constraint is discovered that is not obvious from reading the implementation
- a plausible-looking simpler design is rejected for a reason that will not survive in
anyone's memory
**Do not write one for routine changes.** A seven-section template applied to every commit
becomes bureaucracy, and the predictable result is that people stop writing notes at all.
Most changes need a good commit message, not a design note. If in doubt: would someone
reasonably revert this in a year because the reason was invisible? If no, skip it.
---
## Structure
### 1. Evidence
What was measured. Numbers, tables, and the exact conditions under which they were
produced. State what was *not* varied, so the reader can judge attribution — a result is
only attributable to the change if nothing else moved.
If there is a control in the data — a near-identical case that behaved differently —
put it here. Controls are what separate a mechanism from a coincidence, and they are the
part most write-ups omit.
### 2. Mechanism
Why the evidence looks like that. Derive it where possible rather than asserting it. If
the mechanism is a hypothesis rather than a derivation, say so explicitly and say what
would confirm it.
### 3. Rule
The general statement, framework-independent, in one or two sentences. It must apply
beyond the specific case that prompted it, and the note should give the wider class it
covers — otherwise the reader will apply it only to the example.
Relate the rule to existing concepts by name where they exist. Most rules are restatements
of something known in another field; saying so is more credible than implying invention,
and it gives the reader somewhere to read further.
### 4. Detection
How a contributor checks for this **before** trusting a result, and how the tooling
enforces it automatically where it can. A rule with no detection procedure will not be
applied — it will be agreed with and forgotten.
Include the diagnostic that made the problem visible, and state how to tell a true positive
from a misconfiguration. Both look the same at first glance.
### 5. Resolution
What was changed, and why it addresses the mechanism in §2 rather than the symptom in §1.
### 6. Limitations
What the resolution costs, what it does not cover, and how the resulting claims narrow.
State the degenerate case — the configuration in which the fix silently stops working — and
say plainly what can no longer be claimed without qualification.
This section is the one most likely to be skipped and the one most likely to matter.
### 7. Falsifier
How we would know the rule is wrong or the resolution insufficient. At least one concrete
observation that would overturn it.
A rule with no falsifier is a preference. If nothing could contradict it, it is not
carrying any information.
### 8. Lessons — optional
Include only when the note contains something transferable beyond its own rule: a
generalizable failure mode, or an interaction between defects that would recur elsewhere.
Most notes should not have this section. When one does, it is usually the most valuable
part, because it is the only part that applies to problems nobody has met yet.
---
## Closing line
End every note with the single question a contributor should ask before doing the thing the
note is about. One sentence. It is the part people will actually remember.
---
## Existing notes
- [`objective-observability.md`](objective-observability.md) — a verification objective must
depend on the outputs being verified. Includes the case where six operations were reported
clean across 349 cases without a single component ever being compared.