# Execution — decision discipline — ORCHESTRATED · context **Everyone whose setup looks like this should read this file.** One agent, deep structured knowledge. Decisions are part of what it resolves, which means a superseded record is not stale text — it is a wrong answer that arrives with provenance. You are building now. Read the four files the interview wrote before you touch anything. --- ## Read first /DECISION-MAP.md where decisions live, what is broken, what loads always /INTERVIEW.md what they said, marked measured or stated /TIER.md the tier and the three dimension scores /DECISIONS.md what this module has already settled with them If any is missing, stop and say which. Building from a partial record is how you produce something that contradicts a decision already made — which, in this module, would be its own failure demonstrated. --- ## The pattern, in four rules — build every one of them 1. **A choice that is expensive to reverse gets a record, written before or with the change.** Anything else goes in the commit message. A records directory full of trivia is a directory nobody reads. 2. **A killed thing gets a kill record** — what it was, why it died, what replaced it, and what new information would reopen it. Disagreement is not new information. 3. **A superseded record is edited in the SAME COMMIT as its successor** — `Status: superseded`, `Superseded-by:` naming the new file. Never deleted. 4. **A limit is a measurement.** A number that caps something carries the measurement that set it, or a record saying it is unmeasured. --- ## What to build at this tier - **decisions as a closed type in the taxonomy, with Status and Superseded-by as fields rather than prose** — a resolver can follow a field; it cannot follow a sentence - **the checker inside the index or build step** — a broken link then fails where the knowledge is assembled, not where it is read - **a resolution rule — a lookup that lands on a superseded record returns the successor and says so** — the reader learns both the answer and that it changed - **kill records for approaches that were tried and dropped** — in a knowledge base, an absent record reads as an unexplored idea Build these where `INTERVIEW.md` showed appetite. Where it did not, say so and leave it — building against a gap the person does not have is how a durable system becomes an abandoned one. The template and the checker are files, not prose to paraphrase. Fetch both and copy them verbatim: https://docs.utopiamodels.ai/kit/patterns/decision-discipline/TEMPLATE.md https://docs.utopiamodels.ai/kit/patterns/decision-discipline/check-supersession.py Put the records where `DECISION-MAP.md` said they should go. Where `DECISIONS.md` already settled a question — the records directory, the pointer's scope — carry the settled answer and name the entry; do not ask it again. Ask only what it does not settle. Never edit a record in a tree `DECISION-MAP.md` marks as read-only reference, even a silently dead one. Leave the finding recorded where it is. --- ## The gate — the reminder that fires without anyone remembering it The occasion, and it is an occasion, never a topic: about to choose something expensive to reverse · about to rebuild or re-propose something that was removed · about to set or change a numeric limit When it fires, the agent lists the records directory BEFORE proposing anything, and writes or supersedes a record WITH the change. The resolution rule is the reminder, because it fires on every lookup without a trigger description to match. The checker in the index build is the check. No separate skill. Read `https://docs.utopiamodels.ai/kit/workflows/gates.md` before proposing a mechanism. Present the options ranked against what `DECISION-MAP.md` shows this harness actually has, **exactly one marked RECOMMENDED**, one line of why each. Do not offer a mechanism the harness does not support. 🔴 **The pointer is three lines or fewer.** It says where the records are and when to read them. It never holds the records or the rules above. 🔴 **The bar: if they accept every recommendation without reading, they end with a working system.** --- ## What closes this tier's gaps - **the resolver follows Superseded-by** — otherwise the most authoritative-looking answer is the dead one - **a stated value is bound to its source or not stated** — a number copied into a note outlives the constant it describes --- ## Prove it — four tests, with real output Do not report that it works. Run each and paste what it printed. **The gate, both directions.** Start a FRESH session of this harness non-interactively from the folder the work lives in (`claude -p`, `codex exec`, `gemini -p`, `opencode run` — whichever this is, with stdin closed by ` to " → it read the records and named the one that applies a sentence that should NOT e.g. "rename this variable" / "fix this typo" → it did not mention decision records at all 🔴 **A gate that fires on everything is as broken as one that fires on nothing, and only the negative test catches it.** If either fails, fix the pointer or description and run both again. If this harness has no non-interactive mode, say so and give them the two sentences to run in a new session. **The checker, both directions.** In a scratch copy of the records directory, never the real one: write a record that Supersedes an existing one, leave the old one untouched → check-supersession.py exits 1 and names the pair mark the old one superseded, pointing at the new one → it exits 0 Then delete the scratch copy, and run the checker once against the real directory. Then verify the rest against reality: every path in `DECISION-MAP.md` resolves, and the always-on total matches what the harness loads now that you have added to it. --- ## Finish Every file created with its path. The four test results with their real output. The always-on byte total before and after. Append to `DECISIONS.md`: what you recommended, what they chose, and what you did not build. Then say exactly this: "Decision discipline is in. The gate fires on [trigger] and stays quiet on [non-trigger]. The checker caught a one-sided supersession and passed the repaired one. Always-on went from [X] to [Y] bytes." Then stop.