advanced 3 min answer

Review this proposal: 14 pages on moving order processing onto an event bus, a six-month plan with five phases, a cost table, two alternatives rejected in a paragraph each, and a final page asking for approval of the migration. It has been in review for five weeks with comments on phases four and five. What would you cut, what would you add and what would you leave alone?

technical-proposalsdecision-sizethresholdsreview-stallreversibility
Show the full answer Hide the answer

What is actually required

The reviewers are being asked for a decision they cannot make. Approving a six-month migration means pre-approving five decisions whose inputs do not exist yet, so the rational response from a careful reviewer is to probe the latest phase and defer. The comments clustering on phases four and five are not reviewer obstruction; they are the predictable result of asking for authority over a future the document cannot evidence.

The ask is the defect, not the length.

What I would cut, and why it is safe to

  • Phases three to five, down to a paragraph each. They are plans about a system that will have been reshaped by phase one. Detail there invites questions that cannot be answered and costs the proposal a week per round.
  • Any phase-level estimate past the first. A six-month plan with five phase estimates carries five pieces of false precision, and reviewers correctly discount the whole document when one of them is obviously invented.
  • The architecture background section, if the reviewers already know the system. It raises page count, which lowers the number of people who read to the ask.

The one change that matters

Resize the ask to the next decision and attach a threshold.

We are asking for three engineer-weeks to run order processing through the bus in shadow mode against production traffic. If shadow end-to-end p99 is under 400 ms and duplicate delivery is under 1 in 10,000 we proceed to phase two; above 700 ms or 1 in 1,000 we stop and keep the current path. Between those, we come back with the data.

That paragraph changes three things mechanically. The decision is now small enough to be reversible, because the cost of being wrong is three weeks rather than six months. The stopping rule is agreed before anyone is invested in the outcome, which is the only time it can be agreed honestly — a threshold proposed after a team has spent a quarter on something will be renegotiated, and everyone in the room knows it. And the proposal now has an expiry: unless the room decides, the shadow test does not run, and that is visible as a choice rather than as neutrality.

Shadow mode is also the part that fails safely. It runs against real production traffic and writes nowhere, so the worst outcome is three weeks of wasted effort rather than an order-processing incident.

What I would leave alone

The two rejected alternatives, even though they read like padding. They are what prevents the fourth round of "did you consider". Also keep the cost table: it is the only part that lets a non-engineer participate, and an approver who cannot participate defers.

When this is the wrong answer

When the decision is genuinely irreversible and the sequence is the risk — a database engine change, a vendor contract with a three-year term, a data model that other teams will build on — the full plan is the right artefact and a staged ask is a way of sneaking past the review that should have happened. The test is whether phase one can be abandoned without leaving the organisation worse off than before it started. If it cannot, write the whole plan and defend it.

Common weak answers

  • "Add more detail on the phases." This is what the comments literally ask for, and doing it extends the stall. The reviewers are asking for certainty the document cannot supply.
  • "Take it to a meeting." A meeting about an unbounded ask produces an action item.
  • "Add a do-nothing column." Useful, and it does not fix an ask that is too large to grant. Cost the status quo and shrink the request.