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):

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):

def get_user(user_id: int) -> User:
    """Fetch user from database. Raises UserNotFoundError if no user exists
    with this ID. Result is cached for the duration of the request."""

The test: does the docstring tell you something you couldn't already read from the signature? If not, skip it.

Spec Clarity Assessment

Adequate (skip):

• Docstring with behavioral contract (return semantics, exceptions, side effects)
• Clear name + full type hints + small body where behavior is obvious

Gap (apply core heuristic):

• No docstring + (unclear name OR incomplete types OR non-trivial body)
• Vague docstring ("Process the data", "Handle the request")
• Type hints that lie (-> float but sometimes returns None)
• Undocumented side effects (mutation, exceptions, caching)