from liza124
Identify missing function-level contracts and backfill docstrings and type annotations; report ambiguous gaps with misuse scenarios. Incremental, state-driven w
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.
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.
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.
Code-spec-backfill is a well-crafted skill for incrementally backfilling missing docstrings and type annotations in codebases. It uses a state-driven approach (YAML state file tracking per-file review freshness) and applies a clever misuse-scenario heuristic as a quality gate — only documenting gaps where incorrect usage would actually cause harm. The no-tautology rule prevents low-value docstrings. No scripts included; purely instruction-based. Clean, no security concerns.
No scripts to execute — static analysis only. SKILL.md is thorough with clear workflow, stop conditions, and integration guidance. Misuse-scenario format is a strong design choice that prevents over-documentation.
