incremental-refactoring

# Incremental Refactoring ## Fail-Fast Rule If any mandatory invariant, validation, or precondition fails, **stop and return a structured failure**. Never guess, infer, smooth, approximate, or "fix" business-critical data. ## Cardinal Rule Every change must be the **smallest correct diff** that achieves the goal. If a change can be split into two independent changes, it should be. Production systems earn trust through small, reversible steps. ## Do Not Touch Hot Path **Never refactor, optimize, or restructure hot-path logic unless explicitly instructed by the user.** The hot path is any code that executes on every incoming request or event (request handlers, normalization, cache update, response serving, background processors on the critical read/write path). If the user asks for a general refactor, clarify scope first: - "Does this include hot-path code?" - If no explicit confirmation, exclude hot path from the change. Changes to hot-path code require: - Explicit user instruction - Shadow mode validation before cutover - Rollback plan documented before merge ## Shadow Mode for Critical Logic For any logic change that affects a **critical computation** (numeric math, ranking, pricing, eligibility, score calculation — anything where a silent regression would harm users), a shadow computation **must** exist before replacing production logic: ```typescript function computeMetric(input: Input): MetricResult { const oldResult = legacyComputeMetric(input); if (FLAGS...