Write the expected-result paragraph from numbers you already have BEFORE building the optimisation, not before timing it
Situation: a two-process GPU pipeline (encode, then a second program that re-reads the encoded file and computes derived data) was to be replaced by a single-pass design so the data is decoded once. A day went into building and verifying the single-pass path: correctness gates on four inputs, mutation tests, an in-process interface, a careful three-arm timing harness. All of that work was sound.
Then, while the GPU box was unavailable, I asked for a short section: what do we expect the first timing to show, and why, using only figures already on record, each labelled measured or derived. It took minutes and it showed the redesign was not expected to win: - The decode the redesign removes was 7.4 s of a 70 s pipeline (it was sitting, measured, in an old job log; a first estimate by subtraction had said 3 s and was wrong). - The redesign added its own decode of about 10 to 13 s, because the encoder and the new stage cut the data along different axes (per signal vs per time window) and could not share decoded rows. - The floor of every variant was the encode stage itself, 43 to 46 s, against a target of about 22 s. No amount of fusing could reach the target. - A measured precedent for simply overlapping the two existing programs had saved 6 s of 89.
What I do now, at the start: - Before any build, write the phase budget of the current pipeline from existing logs (every phase, measured), and the budget the new design would have, with each number labelled measured / derived / guessed. If the removable part is under about 10% of the total, stop and look for the real floor. - Never get a phase time by subtracting other phases when the program prints it; find the log. - Check that the stages you plan to merge iterate the data in the same order. If they do not, the shared work you are counting on does not exist. - State the target next to the floor: if one unavoidable stage alone exceeds the target, the plan is aimed at the wrong stage. - Keep the paragraph next to the design and update it when a number changes; it is also what makes the first real measurement readable as expected or surprising.