jschoubben
90e4a368dc
Decisions were the one link the cycle checks skipped, and measuring found 19 of 70 records orphaned — the credential flow and the module-runtime cluster among them, which is how a stale premise about a settled decision survived in working memory. cycle.py now refuses an accepted record nothing cites; the 19 got true homes (design frontmatter, the playbook that implements 0021, META for the process records). The overview names the practice: spec-driven development with provenance. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
---
|
||
topic: how we work
|
||
status: accepted
|
||
date: 2026-09-17
|
||
deciders: jochen
|
||
reconstructed: false
|
||
extends: 0080-the-development-cycle-is-checked.md
|
||
---
|
||
|
||
# 81. A decision nothing cites is not yet in the chain
|
||
|
||
## Context
|
||
|
||
[ADR 0080](0080-the-development-cycle-is-checked.md) made the development cycle checked — but its
|
||
checks covered designs, issues and research, not the decisions themselves. Measuring showed why
|
||
that matters: 19 of 70 records were cited by nothing — no design doc's `decisions:`, no research
|
||
`became:`, no issue, no other record. Among them sat load-bearing decisions (the credential flow,
|
||
the module-runtime cluster), and the cost had already been paid once in practice: a stale premise
|
||
about an orphaned decision survived in working memory precisely because no pointer led to the
|
||
record that had settled it.
|
||
|
||
## Decision
|
||
|
||
Every **accepted** decision must be reachable from the cycle: cited by a design doc's frontmatter
|
||
(`decisions:` — a governing citation, not a prose mention), a research overview, an issue report,
|
||
a `00-META` document, or another record's `extends`/`supersedes` chain.
|
||
[`cycle.py`](../00-META/checks/cycle.py) refuses orphans. Proposed records are exempt — a record
|
||
under consideration has no home yet — and superseded records are reachable through their
|
||
supersession chain by construction.
|
||
|
||
The 19 orphans were given true homes in the same change: the module-runtime cluster
|
||
(0044–0049, 0053–0055) into the connectivity, controller, protocol, writing and model-access
|
||
designs; the build decisions (0072, 0076) into the building design; 0021 into the playbook that
|
||
implements it; the process records were already reachable once `00-META` counted as a source.
|
||
|
||
Taken together with 0080, the practice has a name the industry will recognise:
|
||
**spec-driven development, with provenance** — a decision is the *why*, the design doc is the
|
||
spec, `code:` names the implementation, and the lab beds are the conformance tests. What the
|
||
common form leaves implicit, the cycle makes checked: the spec itself must trace to a decision,
|
||
and the decision must be findable from the work it governs.
|
||
|
||
## Consequences
|
||
|
||
Following pointers now reaches every accepted decision, so a cleared session (or a person) can
|
||
trust the frontmatter graph as the whole map. The check is reachability, not truth: a citation
|
||
placed wrongly still lies, and reading remains the job.
|
||
|
||
## References
|
||
|
||
- [ADR 0080](0080-the-development-cycle-is-checked.md) — the cycle this completes.
|
||
- [`00-META/process/00-overview.md`](../00-META/process/00-overview.md) — the flow.
|