# Doctrine — the epistemics of the surface

Load when: the first capture of a session; whenever you cannot say in one line how a fork, a decision, a decline or the thesis is shaped. The twin reads it on every dispatch.

Both seats share these rules: the facilitator captures to them, the twin distils and audits to them. They are the epistemic core of a decision record (thesis, forces, open questions, commitments with their declined branches, consequences) without its ceremony: no status lifecycle, no one-document-per-decision, no numbering committee.

## The governing bar

**Everything that matters in the session is noted down, and noted down distilled.** Distilled means claims, reasoning and implications, never verbatim transcription; the verbatim conversation stays in the untracked capture and dies with it. Two kinds of copying are integrity, not stenography, and are required: printing an enumeration a file cites, and excerpting an external source a file leans on.

## The surface

| Element | Is | Shape |
| --- | --- | --- |
| **Thesis** | the current design as composed prose a stranger can read | **Claim** (what the design is) · **Argument** (the forces and the reasoning chain that make the claim right) · **What changed** (the most recent shift and why); recomposed whole, never patched; stamped `Current as of:` |
| **Force** | a pressure shaping the design: a user constraint, evidence from the repo or the field, a platform reality, a cost, prior doctrine | no file of its own; it lives where the reasoning that uses it lives (the thesis argument, a decision's Why), stated concretely enough to check ("the CLI gates consumer refresh", never "deployment concerns") |
| **Fork** | an open question | a close condition stating what answer closes it (a pick, a confirmed fact, an accepted risk); a fork without one is not askable, so rewrite it until it is. Forks are the only convergence currency: a concern no fork carries cannot block or steer anything |
| **Decision** | a commitment | Decision · Why · How to apply · Resolves (the forks it closes) |
| **Declined line** | an option weighed and not chosen | inside the decision that declined it: the option, the evidence at decline time, and the condition under which it deserves another look |
| **Consequence** | what a decision obligates beyond itself: follow-on work, constraints on later decisions, where its knowledge must land | a new fork ("committing to X opens Y"), a backlog candidate, or fragment content; it keeps the ledger from being a list of verdicts with no forward pressure |
| **Park** | a fork deliberately left open | a named destination where its resolution will land |
| **Fragment** | a dimension with real content (domain model, tech, non-goals) | drafted in its destination's format, so harvest is a move, not a translation |
| **Aspect** | one thinking dimension on the map | a name, a gloss, and the forks, decisions or fragments that cover it |

- **A decision is real the moment it lands.** Amend by annotation; a reversal is a new decision naming what it reverses, plus a one-line `Reversed by D<n>` annotation on the reversed entry. There is no tentative, committed or rescinded state, and the meaning of a past entry is never rewritten.
- **Rejections live inline.** A declined option is a **Declined:** line in the decision's Why, never a separate rejected-options file. The re-evaluate condition is what turns a past rejection into a standing tripwire, so a decline without one is incomplete.
- **A tech fragment seeds from the repository's rules**, and every deviation from them is recorded with its why.

## Capture: what goes in

The facilitator captures both sides at the lowest bar. Four classes of facilitator substance are the known leak, because conclusions survive in every record while these do not:

| Class | Example of what to capture |
| --- | --- |
| Causal diagnosis | "Sync rotted because nothing forced it at close, not because the agent was lazy" |
| Informed rejection | the option presented, who declined it, the reason |
| Definition | every term a file will lean on, glossed in one line |
| Reasoning chain | the steps behind a recommendation, not only the recommendation |

User substance is captured as evidence: quote the user where their phrasing is the point, and never promote one phrasing into the frame. Residue (an idea mentioned and not pursued) stays in the capture; that is what the capture is for.

## Self-containment: no naked pointers

Nothing on the surface leans on anything undefined in the folder. A cited enumeration is printed once; a term gets a one-line gloss at first use; an external citation carries its excerpt. The test is a stranger reading cold, which only a reader without the session's context can run: a reader that already knows every term cannot see the gap.

## The scribe call and the design call

When the twin finds something to fix:

- **Scribe call:** the resolution does not change the design (wording, bookkeeping, a missing enumeration, a gloss). It applies the edit and lists it.
- **Design call:** the resolution changes the idea. It files a fork and never routes the question through a direct edit.

Filing an insight must never push the session away from coherent: orphan evidence is a note in the twin's report, never a fork, and a free-floating insight may feed an aspect of the thesis.

## Steering versus feature truth

A principle the session establishes informs many decisions and changes slowly; a fact about one feature belongs to that feature's document and changes at code speed. Keep them apart on the surface, and the harvest links between them and never duplicates prose across them.

## Field lessons — capture and converge

Each was measured on a live session; each blocks a move that looks correct mid-session.

- **Separate the user's voice from your re-derivation before anything is ledgered.** When the user states a segregation and you re-derive a whole architecture from it in the same turn, only the user's half is a decision. A re-derivation that re-reads an existing decision into a new shape is a fork carrying a named amendment to that decision, never an edit: a decision recorded in the user's words is amended only by the user.
- **Stamp in UTC, from `date -u`**, never from the runtime's injected local date. The two disagree for part of every working day in some offsets, and the detector compares stamps as strings, so a local stamp runs the ledger a day ahead of the capture.
- **Run a blindspot pass right after a converge burst, before the manifest gate.** When several picks land in one sitting, the strain migrates between them: two decisions taken within the hour collide, and only a reader holding both sees it. The burst is the cheapest moment to catch that and the last before it freezes.
- **A pick that answers three of a fork's four close-condition clauses closes the fork, and the residue becomes a new fork in the same pass**, named in the resolving decision. Closing silently loses the fourth clause; leaving the fork open loses the three.
- **A decision whose Why says "already" rests on a fact; verify it before the manifest.** Declining to build something because it exists is checkable only while the session is open.
- **Verify a doctrine claim against disk before arguing from it.** Truth docs drift from rebuilds: a guardrail can name a guard path that exists nowhere. When a session's centre is a recorded prohibition, list the guard path, read the owning package's config, and confirm the package is in the tree.
- **Read the decision records before framing a session around a contradicted pillar.** A recently accepted architecture decision may already contradict it, and a session convened to decide a reversal is then ratifying one that shipped: a different conversation.
- **Give the opening aspect map at least one aspect organised by seam.** A map organised by system layer owns none of the questions that land between two planes or two phases, which is where the real design questions sit.
- **Check the decision prefix against the product's vocabulary.** `D<n>` reads two ways in a product whose database is called D1; add a disambiguation line to the ledger header and spell the colliding term out inside entries.
- **The repository's rule files are a blindspot source.** They carry platform facts a design can contradict unnoticed (a registry answering `404`, not `401`, to a restricted read turned "containers hold no credentials" into an open question). Read the rules touching the session's substrate against new decisions, not only against the basis.
- **Absence in this repo is not absence.** Evidence for a premise often lives in a sibling repository; a grep that finds nothing proves only that this repo does not own the fact. Check the owning repo before filing a fork as unevidenced; when the fact is confirmed there, the harvest cites the external doc rather than restating it. A doc saying "this surface reports, it does not enforce" does not contradict "the platform enforces": different layers, both true, neither edited.