code-spec-backfill

**STATE_FILE** = `specs/.code-spec-backfill/state.yaml` tracks per-file review freshness: # Code Spec Backfill Constructive first, diagnostic second. Write the contract where you can infer it. Report what you can't resolve. # Core Heuristic Only act on a gap if you can write a plausible incorrect usage that a senior engineer might write based on the function's public interface. The misuse scenario IS the quality gate — if no one would get burned, it's not a gap worth addressing. **Misuse scenario format:** `[caller_assumption] × [actual_behavior] → [consequence]` Example: `"Returns empty list when no results" × "Raises NoResultError" → "Caller crashes on valid empty-result case"` # Hard Boundaries - NEVER modify behavior — only add/improve documentation and type annotations. - NEVER weaken existing contracts (e.g. broadening a type hint to accept None). - Unexported/private members: only if explicitly scoped. ## No-Tautology Rule A docstring that restates the function signature adds no value. Do not write docstrings that merely echo parameter names, types, or the function name as prose. **Tautological (do not write):** ```python def get_user(user_id: int) -> User: """Get a user by user ID. Args: user_id: The user ID. Returns: The user. """ ``` **Valuable (write this):** ```python def get_user(user_id: int) -> User: """Fetch user from database. Raises UserNotFoundError if no user exists with this ID. Result is cached for th...