demand-first-review

# Demand-First Review ## Principle Audit this causal chain before implementation quality: `root outcome or invariant → normalized demand → owning layer → contract → consumer` A call site proves usage, not legitimacy or shape. No call site raises the burden of proof, not an automatic rejection. Real demand may still have the wrong consumer or abstraction. ## Workflow Apply every step to each added API, channel, parameter, type, field, config, or extension point. ### 1. Reconstruct the demand List every new surface and exact consumed dimension; one valid consumer does not justify unused fields. Trace current and linked consumers to their user outcome, business rule, or system invariant. Inspect adjacent implementations, then ask: without the current API and history, would the demand remain and would this contract still be natural? Do not rely only on the PR description. ### 2. Audit consumer legitimacy - **Legitimate**: uses the correct owner and boundary. - **Compensating**: uses the nearest API and adds workarounds because the right capability is missing. - **Legacy-shaped**: reflects obsolete formats, transitional architecture, or history. - **Misplaced**: serves real demand in the wrong layer. Parsing, retries, sequencing, duplicated state, check-then-act, or cross-layer access signal compensation. Treat these as unmet upstream demand, never endorsement of the current surface. ### 3. Normalize related demands Strip names, historical formats, and workarounds fro...