Design-Topic Session

Run a decision session on a Design Topic: present decisions one at a time with self-contained context, capture the operator’s rulings, and propagate every consequence to its home before moving on.

A Design Topic (DT-XXX) is the workbooks’ stable-ID unit for anything non-trivial that needs investigation or a ruling (see the Work Board section of /workbooks/CLAUDE.md). A session resolves the decisions of one topic. The conversation is the session surface; files are the durable record.

When to run a session

The follow-the-model tiebreak. “Follow the model” means: check what the system’s Alloy model says, and follow its semantics wherever the model is unambiguous and feasible.

Escalate a question into a session (rather than resolving it by the standing follow-the-model tiebreak) when any of these holds:

• The model is silent, ambiguous, or infeasible — the governing formal model takes no position, admits more than one reading, or prescribes something another constraint rules out, so the tiebreak has no answer and the decision is a product/policy call the operator must make.
• Model and runtime disagree in shape — following the model’s prescription literally would require restructuring something no other requirement wants changed (a reconciliation, not a transcription).
• The fix crosses a published contract — wire shapes, deployed defaults, documented laws, or anything a consumer already relies on.
• A premise of a decided topic fails on contact with a running system — the decision may survive; the reason given for it may not.
• The plan deferred the decision to this point — a topic marked “open until step N” convenes when step N starts, not when someone remembers it.
• A #proposed-topic comes due because the thing it was waiting on now exists.

If none holds, apply the tiebreak, record the application, and do not convene a session.

Style (binding for every part of the session)

• Succinct language. Short sentences. No filler. Prose over bullet chains where reasoning must flow; bullets or tables where items are enumerable.
• No bare identifiers, no unexplained lingo. Every ticket ID, DT number, law name, file symbol, or newly coined term carries an inline gloss or a link on first use — every session, even if it was glossed yesterday.
• Write for a context-switching human. Assume the operator is returning after days on other work, with limited attention. Restate the situation a question lives in before asking it. Never rely on “as discussed earlier”.
• Evidence is read, not remembered. Any claim about code or model text is quoted from the artifact at session time with path:line. A negative search result is verified (was the search itself sound?) before an absence is asserted.

Session flow

0. Agenda — always, even for a single decision

One message before any decision:

1. The topic, in one glossed sentence.
2. The decisions the session will take — one line each, ordered by dependency (a ruling that can moot a later decision comes first).
3. Questions to the operator, if disambiguation or clarification of the topic is needed before the decisions can be framed. Ask them here, not mid-decision.

The operator confirms or reorders. For a single-decision session the agenda is small, and it doubles as an independent confirmation that the session as scoped is consistent.

0.5. Establish the facts that determine the option space

Before the agenda is final, measure anything that could change what the decisions are rather than what their answers are: probe the running system, read the artifact, run the query. If measuring could reshape the agenda, the agenda is provisional until it is measured — say so in §0 rather than presenting options built on an unmeasured frame. When the measurement changes the set or order of decisions, return to §0: the operator confirms the revised agenda before §1 begins.

1. Per decision — the five-part exchange

Present one decision per exchange. Do not present the next until the current one is ruled. Never batch decisions behind cross-references — and never bundle related fixes into one recommendation: batching hides the item the operator would have questioned. A bundled recommendation gets a bundled answer, and the narrower half never gets the scrutiny that would have found a decision already recorded against it.

Part	Content	Rules
Context	The world this decision lives in, restated from scratch: what the artifact is, where the governing text or code lives (quoted, path:line), how the situation arose	Glossing and evidence rules above apply in full
Need	Why a decision is required now, what it blocks, which standing constraints bind (co-change rules, trace rules, deployment couplings)	If nothing truly blocks, say so — deferral is a legitimate option. A deferral records its reason and the check that would falsify it; picking the item up starts by running that check. A deferral reason is a claim with an expiry, not a permanent property of the work
Options	Enumerated (A/B/C…), each with description, consequences (what changes, where), cost, and what it forecloses. Rejected directions included, with why	Name the deciding authority per option: model prescription, product call, or deployment concern — and say explicitly when the model is silent. Mark how each cost was established: traced / measured / estimated. “Estimated” is a flag, not a value — if cost is the deciding factor between options, an estimated cost means the decision is not ready to be ruled on. Tracing callers of shared code is minutes of work
Recommendation	Exactly one, with the reasoning that selects it	Recompute it out loud when a follow-up answer changes the facts; never defend it past its premises
Ruling	The operator’s decision, captured in their framing (verbatim where the wording carries content)	An operator-proposed option is evaluated on equal footing. A ruling is a working hypothesis — reopening later is a consistency re-check, not an authority argument

1.5. Feasibility read — before propagating

Is the ruling implementable exactly as stated, and what does it imply that is not scoped? Report prerequisites to the operator before landing anything. A ruling that is right and requires unscoped work is common; discovering that mid-propagation is what makes it expensive.

2. Propagation — after each ruling, before the next decision

Close every ruling with a named consequence list, each item with its home, and land the items before presenting the next decision:

• Model edits (repo gate green before push; commit cites the DT).
• The workbook record (see Deliverables).
• Ticket scope / acceptance-criteria lines, under the per-cut Linear trace rule: every model change with a runtime counterpart gets, at the same cut, a Linear sub-issue, or an edit of the ticket that already carries the scope, recording the runtime change. The rule is stated in /workbooks/notebooks/procurement-V2/06_technical-notes/tn-010-model-update-candidates.md.
• Plan, brief, PR-body, or changelog truings — any living document the ruling contradicts is trued now, not “later”.
• The change-inventory row where the project keeps one, with a newly allocated ID and a link to the ruling that justifies it. Check ID density before allocating — a gap is usually a mistake, not a reservation.
• Any derived summary the ruling invalidates (counts, totals, rollups) is either updated now or relabelled a snapshot with its date. A stale total that reads as current is worse than no total.
• Published-documentation promotion candidates — flagged for the operator, never silently written.

3. Close-out — one message

• One line per ruling taken.
• The deliverables list, with paths or links.
• The topic’s status move on the work-board (open → decided, or what remains open and who owns it).

Deliverables

1. The DT file in the workbooks (/workbooks/notebooks/<project>/design-topics/dt-xxx-….md, a decision section or a post-closure addendum): finding → options as actually presented → ruling in the operator’s framing → rationale. Capture, don’t summarize away — the rejected options and the path to the ruling are the record’s value. When a later finding invalidates a premise, amend in place, dated, and state explicitly which changed: the decision, the reason, or both. A right answer kept for a wrong reason survives until the reason is reused somewhere else — recording “the decision stands, this justification does not” is the point of the amendment, not a footnote.
2. The consequence artifacts themselves, committed and pushed per each repo’s rules, each traceable back to its ruling.
3. A disposition table when the session sweeps many items: one row per item with its disposition and test obligation, positioned so a later implementation plan can absorb it verbatim.
4. Linear traceability per the per-cut Linear trace rule (see Propagation) — but route first, then record: a finding that shapes THIS project’s design is a DT; a finding that outlives the project’s scope is a ticket, filed with the evidence and the measured blast radius, not a one-line pointer. #proposed-topic is the holding pen until that routing is decided — not a third destination. A model change with a runtime counterpart gets its sub-issue at the cut; ruling summaries land as comments where an existing ticket carries the scope.

Presentation conventions

• Tables only for enumerable comparisons (option grids, disposition rows).
• Any text-driven diagram is PlantUML with a 1–3 sentence prose summary (see the PlantUML Guide, which the plantuml-diagrams skill loads); validate before committing.
• Long evidence is linked to a readable file, not dumped into the chat.
• The recommendation is a committed position, not a survey of possibilities.
• When an option’s consequences are cheaper to measure than to argue, apply it in a scratch state, run the suite, revert, and report the exact result. Revert before reporting; never leave the experiment in the tree. Report the failure count and the failures by name, not a characterisation.