---
status: accepted
date: 2026-08-23
deciders: jochen
reconstructed: false
---

# 20. Design is written in two layers: what is, and what is intended

## Context

HQ held only the intended mesh. Every reader had to already know the running system in order
to understand what the decisions were about, and a statement about current behaviour had
nowhere to live except inside a document describing an intention.

The consequence was invisible until looked for: an as-is claim inside a to-be document is
indistinguishable from the intention around it, so the document silently stops being true as
the system moves — and nobody can tell which half went stale.

The mesh also has a large body of shipped behaviour that nobody would choose again. It is not
design in the sense of "what we decided"; it is design in the sense of "what is there", and it
is exactly the part a person changing the system most needs.

## Considered options

1. **One layer, describing the target.** Rejected — the status quo. The running system goes
   undocumented and the target document accumulates unmarked claims about it.
2. **One layer, describing what runs, with intentions only in decision records.** Rejected:
   a decision record is an argument, not a specification, and a multi-part intention has
   nowhere coherent to live.
3. **Two layers, declared per document, never mixed.** Chosen.

## Decision

`03-DESIGN` holds two layers, and every document declares which it is:

| Layer | Describes | Written from |
|---|---|---|
| `00-as-is/` | The mesh that exists | The implementation and the operational record |
| `01-to-be/` | The mesh being built toward | Decision records |

An as-is document **records what is, not what should be** — including behaviour nobody would
choose again. A layer that keeps only the good decisions is a brochure.

When a to-be design ships it **does not move**. Its as-is counterpart is written or updated,
the to-be document's status becomes `implemented`, and both stand: one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning.

Where implementation and intention disagree, the as-is document records the implementation and
says they disagree.

## Consequences

- A reader can tell, from the folder and from one frontmatter field, whether they are reading
  a description or a plan. That distinction was previously unavailable at any price.
- Correcting an as-is document requires evidence from the implementation, not agreement — and
  needs no decision record, because nothing was decided.
- Two documents must be kept current per subsystem instead of one. This is the cost, and it is
  paid on every ship.
- Something that shipped differently from its design becomes a visible divergence rather than
  a silently wrong document, and may deserve an issue.

## References

- [`03-DESIGN/README.md`](../03-DESIGN/README.md) — the layer contract and frontmatter schema.
- [`03-DESIGN/00-as-is/`](../03-DESIGN/00-as-is/) — the first eleven as-is documents, written
  2026-08-23 from the monorepo and the operational memory.