How the design was run

Roar Elias Georgsen, 27 August 2026

Part 3 of 13 in Federating a systems model, written for release v0.3.0.

The story so far

The demo publishes a SysML v2 model of a five-server query pipeline through a federated router. Two services that have never parsed a model file attach a throughput verdict and a requirements document to it, and The architecture in one sitting describes the result. This part goes back to before any of that code existed, to show how I ran the design and what each round of reading caught.

At the start, the repository held a Go module, a Makefile and a set of coding rules, and no product code at all. I ran the whole design before writing the first line of that code, in a fixed order:

1. use cases, drawn as a storyboard
2. requirements derived from them
3. an architecture, with a decision record behind each choice
4. a design for the one-page summaries that give a newcomer the whole thing at a glance

The order did more work than the documents. Written after the use cases, the requirements describe a demo someone would watch. Written before them, they would have described an adapter someone imagined.

The order also brought the one piece of real arithmetic into view early. The throughput rollup, the pipeline-wide figure computed from the servers, is the only global function in the system. Working out the rollup’s inputs fixed the minimum projection the adapter has to publish. That work put the analysis on the read path, with no copy of the model. It also settled that maximum flow would compute the rollup, because flow handles any wiring and explains the bottleneck.

Four gates

Key term Gate

A checkpoint where the work stops until its output is approved. Each of the four gates here ended with a set of documents, a reading that tried to find the faults in them, and my approval.

The reading is the point. I read each gate’s documents against their sources and against each other, and tried to break them. What the reading found went back into the design before the next gate opened. The first three gates each made a catch worth telling.

Gate 1 found a tie. In the first draft of the script, one step left two different sets of servers limiting the pipeline by exactly the same amount. The demo’s memorable moment, the bottleneck highlighted on screen, would have depended on which set the code happened to pick. I changed one number in the script to avoid the tie, and Twelve use cases and one moving bottleneck tells that story.

Gate 2 found three design errors. Two requirements with the same subject would have been judged by the same rule, which would have passed a latency requirement against a throughput figure. A SysML connection has no direction of its own, and the rollup needs one. And the reason strings would have used words the analysis can’t know. Each error went back to the brief as a decision of its own: the quantity read from the constraint, direction from the order of the ends and reasons from fixed templates. The same reading split nine requirements that each named two obligations, and added four the use cases needed, which took the count to forty-five. From use cases to requirements covers them.

Gate 3 found two decisions nobody had written down. The traceability showed six requirements with no decision behind them. Those six turned up two real decisions that I had taken and never recorded: the document owning its own structure, and the viewer app showing the model’s text beside a sketch of its wiring. Nothing in the reading overturned a decision. Five views and twenty-six decisions walks through the architecture.

The five views, each with its stakeholders and its question. Cut from the architecture views.

Gate 4 designed the one-page A3 summaries and drafted two of them, which An A3 sheet for a fifteen-minute reader covers.

Approving gate 4 closed the design phase. The plan that followed, one pull request per phase, is in Planning the build.

Where the record lives

An engineering log kept the narrative, one entry per gate. A brief kept the ledger of decisions, each with the alternatives that lost. What was worth publishing became a decision record. That’s the short form Michael Nygard proposed for context, decision and consequences, and mine add the alternatives that lost. One rule holds them together. A working document stops being the record once its content is promoted, so when two documents disagree, the record wins.

A few house rules shaped the code from the first commit. The gitignore is an allowlist, so nothing gets committed unless a rule names it. That’s why tracking two test helper packages needed a decision of its own, since tests import them and would otherwise fail on a fresh clone. Hand-written Go may not use an empty interface as the type of a value, because a value of that type can hold anything and the compiler can no longer check it. Generated code is exempt. Tests come first, and commits reach main only through a pull request.

What the method cost and bought

The method cost requirements. The plan aimed for 20 to 25 and got forty-five, because a statement that names two obligations is two requirements.

It bought three design errors caught in the requirements instead of in the code, and misattributed claims caught before they reached anything public.

It also bought a broken pass criterion, which I only caught because I tested the test. The check I’d written for the first spike of the build would have reported a broken model file as a pass. Five spikes before the first line has that story.

I still think the gates suited a project one person maintains. I’d change the shape of the plan, though. It ended up with one detail document per phase, but only as a repair, and that should have been its form from the first draft.

Previous: The architecture in one sitting · Index: Federating a systems model · Next: What the research overturned