Demand-First Review

Overview

In engineering, the first-principles starting point is the demand (the requirement). The biggest waste in review is providing high-quality polish suggestions for something that should not exist. First audit whether the demand is real (consumer archaeology); only review the implementation of what survives.

Iron ordering (the first three steps of Musk's five-step algorithm): question the requirements → delete → only then simplify/optimize. Reversing the order = optimizing something that should not exist.

Consumer Archaeology (core workflow)

For every newly added API / channel / parameter / type / field:

1. List consumers: trace ALL real call sites across branches and repos (git grep including feature branches). Do not trust the PR description.

2. Measure consumption: for each consumer, check which part of the return value / capability it actually reads. Consumer count ≠ consumption; a consumer that only reads one boolean consumes zero of an error taxonomy. Real consumption = the real size of the demand.

3. Judge pseudo-demand — two checks, both required:

   • Zero consumption → pseudo-demand;
   • Non-zero consumption but policy: does this dimension move a judgment the consumer could compute in one line into the contract (e.g. an expectedKind param vs. "read kind and compare")? Contracts carry facts; policy inlines back into consumers — delete even when it has real readers.

   Either hit → challenge the whole dimension instead of polishing it.

4. Check same-source capability: does an existing API already cover this, including "strict projection" relations (e.g. getFileSize ≡ getMetadata().size)? Never open a second entry point for the same capability.

5. Check responsibility: is the demand leaked from another layer (e.g. renderer interpreting fs errors, UI doing business validation)? Check-then-act queries usually should become try-the-operation.

After each question eliminates a layer, apply normal implementation review (validation, tests, types, docs) only to the survivors.

Rationalization Table

Red Flags — stop, return to step 1

• You have written five implementation-level comments without listing consumers
• Your report says "speculative" / "no consumers yet" / "unused" but concludes keep / note / add test
• You are finding reasons for an API to exist instead of finding its consumers
• You are about to suggest "add a comment explaining why this is needed" — first confirm it is needed

Real-World Impact

PR #15695 (2 new IPC channels): six implementation-level review agents produced 30+ polish comments, zero questioning existence. Three consumer-archaeology questions later: one channel rejected as a duplicate entry point, one parameter deleted, one channel classified as debt-to-remove — invalidating most of the polish comments.