| name | demand-first-review |
| description | Use when reviewing a PR, API, IPC channel, endpoint, parameter, type, or config that adds new surface area — BEFORE commenting on implementation quality. Also use immediately when a review surfaces signals like "no consumers yet", "unused export", "speculative", "additive", "forward-compatible", or "for future use". |
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:
-
List consumers: trace ALL real call sites across branches and repos (git grep including feature branches). Do not trust the PR description.
-
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.
-
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.
-
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.
-
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
| Excuse | Reality |
|---|
| "The API is clean / the types are elegant" | A clean thing that shouldn't exist still shouldn't exist. Question existence first. |
| "It has consumers" | Counting isn't enough. Check which fields each consumer reads — a zero-consumption dimension is still pseudo-demand. |
| "This parameter/field IS consumed" | Consumed ≠ should exist. Second check: fact or policy? A dimension that moves a one-line consumer-side judgment into the contract gets inlined back, readers or not. |
| "Found an unused export — add a test for safety" | Zero-consumption signals should trigger demand questioning, not test backfill. |
| "A technical constraint makes it necessary" | Ask whether the demand served by that constraint is itself real. Constraints are not axioms. |
| "The PR is additive, it breaks nothing" | Additive is exactly how pseudo-demands sneak in. New surface needs MORE existence scrutiny than modified surface. |
| "We may need it later / forward-compatible" | Zero consumption now means pseudo-demand now. Add it when a real consumer appears. |
| "Existence is the author's / architect's call" | Questioning demand is part of review. Downgrading existence questions to nits equals not asking. |
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.
