Code Spec Backfill

What it does

Code Spec Backfill automates the detection and remediation of missing or weak function-level contracts across a codebase. The skill inspects files marked as stale or unreviewed, lists public callables, assesses whether a behavioral contract exists, and either backfills docstrings/type hints where safely inferable or records a misuse scenario when behavior is ambiguous. It intentionally never changes runtime behavior — only documentation and type information.

When to use it

Run incrementally to catch contract debt after commits or on a schedule; run in Files mode for targeted module audits. Use before onboarding new developers, after large refactors, or when test coverage reveals ambiguous API contracts. It’s designed for codebases where documentation and type hygiene matter.

What's included

• Scripts: none bundled in the skill directory (has_scripts=false).
• References: the skill includes guidance and reference files for state format and workflows (has_references=true).
• Instructions: a clear core heuristic (misuse-scenario quality gate), a no-tautology rule for docstrings, batching rules (10 files per run), stop conditions, and state update steps. It describes both incremental and files modes and how outputs are written.

Compatible agents

Best with developer-assistant agents capable of code analysis and editing (Codex, Copilot/Code, or Claude Code). Also integrates with CI-side tooling for automated audits.