Lesson 0046 · Initiative Lead · Module 2
Compare Options and Record Decisions
Senior judgment is not having the first answer faster. It is exposing credible alternatives, buying evidence where uncertainty matters, and leaving a decision future teammates can reconstruct.
Mission tie-in: explicit forces turn architecture from personal taste into organizational reasoning. Decision records make that reasoning durable without freezing it.
Knowledge: design it twice, decide once
For any consequential choice, produce at least two genuinely different designs. “Kafka” versus “managed Kafka” is one mechanism with two suppliers. For carrier failure, credible options are: fail the whole request synchronously; accept and retry from a local outbox; or route work to an agent queue. Compare them against the drivers from lesson 0043.
| Option | Buys | Costs | Evidence |
|---|---|---|---|
| Synchronous failure | least code; immediate truth | outage blocks outcome; poor recovery | fails availability scenario |
| Persist intent + worker | accepted request survives outage | pending state; retries; operations | fits recovery and latency scenarios |
| Manual agent fallback | fastest pilot; human judgment | queue capacity; slower response | viable below 50 cases/day |
Designing it twice works because the first design is a product of availability, not of search. It is the nearest solution in your memory, and it arrives already feeling correct—which is precisely the problem, since the criteria that made it feel correct were never spoken. A second, genuinely different design forces those criteria into words, because you now have to say why one beats the other. Comparison is the only operation that reliably converts tacit judgement into an argument other people can check. This is also why two options from the same mechanism family teach nothing: they share the hidden assumptions, so comparing them confirms rather than tests.
Decision records work on a different mechanism: what is expensive to reconstruct later is not the choice but the rejected alternatives and the facts that were true at the time. Without those, the next lead either re-litigates a settled question or, worse, treats an obsolete decision as sacred because they cannot tell which of its premises expired. An ADR is a cheap way of making a decision falsifiable in the future.
Both practices degrade under their own success. Design-it-twice on a cheap, reversible, local choice is theatre that trains people to perform deliberation. An ADR that becomes a gate—required before merge, approved by a board—converts a twenty-minute memory aid into a queue, and teams respond rationally by making decisions without writing them down. Apparatus should scale with reversibility, and nothing else.
Use a spike only when evidence could change the decision. A spike has one question, a timebox, a result format, and a discard rule: “In four hours, measure carrier label p95 and duplicate behavior under timeout using the sandbox; publish numbers and throw away the harness.” “Explore the carrier API” is an unbounded implementation prelude.
Match decision apparatus to reversibility. A local class shape can be changed in a pull request. A public contract, data ownership boundary, expensive vendor, or privacy model deserves broader advice and a written record. Review with the people who carry the consequences: product for outcome, design for experience, security/privacy for trust, operations for failure, and affected teams for contracts.
Use an Architecture Decision Record (ADR) for one decision:
- Status
- Accepted · 12 September · owner: Returns team
- Context
- Carrier outages must not lose eligible requests; peak 40 rps; pilot team owns one deployable.
- Forces
- Availability scenario, 800 ms decision target, operational simplicity, no duplicate labels.
- Options
- Synchronous failure; local intent + worker; manual-only fallback.
- Decision
- Store intent transactionally, process from worker, make carrier call idempotent, expose pending.
- Consequences
- New worker and retry visibility; customer can continue; on-call owns queue health.
- Revisit when
- Volume exceeds worker capacity, carrier offers durable async API, or queue SLO misses twice.
Keep ADRs immutable as historical facts. If the decision changes, write a new one that supersedes it. A one-page record written near decision time beats a forty-page design document updated after everyone has forgotten the disagreement.
Name the decider before review. Advice should improve a decision, not create consensus veto. Record meaningful dissent and the evidence that would prove it right. Psychological safety and technical rigor meet here: a concern can survive even when its preferred option does not.
How the lead actually decided it
Week 7. The carrier-failure decision has been circling for four days in a chat thread. The lead's first move is not to open the carrier documentation; it is to reread the availability scenario from lesson 0043, because a decision without a driver is a preference contest. Then she asks the question the thread had never asked: what does the customer see between “accepted” and “label ready”? That question, not the technology, is what eliminates one option and creates another.
Synchronous failure is attractive and is rejected on evidence, not taste: it is roughly forty fewer lines, no worker, no queue to operate—but the availability scenario requires accepting eligible requests through a thirty-minute carrier outage at peak, and this design cannot. Manual-only fallback is the second rejection, and the arithmetic does it: the manual queue already runs near 46 of its 50 daily cases from ordinary policy exceptions, so a peak outage would push it straight through the guardrail.
The spike is scoped to one question and four hours: measure carrier label latency and duplicate behavior under timeout in the sandbox, publish the numbers, throw away the harness. It returns p95 1.9 s, p99 6.4 s, and duplicate labels in 12% of naive retries. Note which decision that evidence actually changed. It did not choose the outbox—the availability scenario had already done that. It chose the idempotency key, which nobody had been arguing about.
Tomas dissents, and his objection is the best one in the room: the worker adds an on-call surface for a failure mode nobody has yet seen. The lead does not talk him out of it. She writes it into the ADR and converts it into the revisit trigger—if the queue misses its service objective twice, or the carrier ships a durable async API, the decision reopens. Dissent that survives in writing is what makes it safe to disagree the next time.
Week 12 supplies the consequence. The carrier goes down for twenty-two minutes during scheduled maintenance. Sixty-one requests are accepted, sixty-one labels are created after recovery, and no duplicates appear. The honest cost is on the same page: the pending state generated four support contacts from customers who did not understand what “label pending” meant—a comprehension problem the design created and the copy had to solve.
| Smell | Underlying failure | Move |
|---|---|---|
| “Everyone agreed.” | Dissent or decider disappeared. | Name both explicitly. |
| spike becomes production | No discard rule existed. | Define evidence, timebox, disposal. |
| ADR describes only choice | Future readers cannot reconstruct why. | Record context, forces, consequences. |
| every change needs review board | Apparatus ignores reversibility. | Set decision thresholds. |
- Two options means two vendors.
- Self-hosted Kafka versus managed Kafka is one mechanism with two invoices. Genuinely different options differ in where the state lives and what fails—which is the only axis on which the comparison can teach you something.
- An ADR documents what we built.
- It records what was decided and why, at decision time. Written afterwards it becomes archaeology, and it quietly omits the alternative that nearly won—which is the single most useful thing in the document.
- ADRs need approval.
- The record is the residue of a decision, not a gate on it. Add approval and you have built a queue; teams then decide in chat and write the ADR to match, which is worse than not writing one.
- A spike is a prototype.
- A spike answers one question and is deleted; a prototype is kept and shown. A spike with no discard rule has a strong tendency to become the foundation of production, complete with the shortcuts you took because it was going to be thrown away.
When this is the wrong move
Do not write an ADR for a choice that is cheap, local, and reversible in a pull request; the code and its history already record it, and a log full of trivia trains people to stop reading the log. Do not run a spike when the evidence cannot change the decision—if a hard constraint means you will do X regardless, buying a number is procrastination with a timebox. And when a constraint genuinely leaves one option, record the constraint rather than staging a comparison; a fabricated alternative in a decision table is a tell that the decision was made elsewhere.
Skill: spend evidence where it changes decisions
A useful technical spike must have:
Which decision most deserves an ADR?
Why record a revisit trigger?
Practice: write one decision, not one design epic
Pick an initiative choice that would be expensive to reverse. Draft two meaningfully different options, compare them against named drivers, and identify the largest unknown. If evidence can change the choice, write a timeboxed spike. Then write the one-page ADR, including dissent and a measurable revisit trigger.
In the lab and the capstone. The lab's phase-4 checkpoint asks for an ADR covering one decision you actually make in the lab code—with its rejected option and a revisit trigger you could test. The worked artifact is the option comparison and ADR in the strong capstone packet, where the rejected options are the ones a reasonable team would have chosen. Compare with the weak version: one option, a decision stated as a conclusion, no forces, no dissent, and nothing that could ever reopen it.
Reveal: the ADR compression test
A teammate arriving in six months should be able to answer: what was true, what mattered, what alternatives were real, who decided, what was chosen, what price the team accepted, and which changed fact should reopen it. Everything else can be linked rather than copied.
- In two sentences, explain to a new lead why a second option is worth an hour even when everyone already agrees on the first.
- Take a decision your team made this month. Write its revisit trigger as a measurable condition—and check whether that condition is already true.
- Predict the failure: if a team records no decisions for a quarter, what happens the first time a new engineer proposes replacing something that was chosen deliberately?
Your win
You can compare real options, cap uncertainty with targeted spikes, scale review to reversibility, and preserve architectural reasoning in a decision record people will read.
Read and watch deeper
- A Philosophy of Software Design, Ousterhout — ch. 11: design it twice.
- Architecture Decision Record, Fowler — concise decision, context, ramifications, advice, and superseding records.
- Software Architecture: The Hard Parts, Ford et al. — trade-off analysis and architecture decision records.
- Documenting Architecture Decisions, Michael Nygard — the original ADR format: context, decision, status, consequences.
- Reference: Initiative Playbook · option, spike, and ADR templates.
Give the ADR and driver set to your agent-teacher and ask it to steelman the rejected option, find an unstated consequence, and propose a precise revisit trigger.