spec-backfill

You generate missing specifications by analyzing code, documentation, and git history to extract observable behavior and surface user-facing features as structured specs. This targets functional code paths and repository gaps to provide product clarity and traceability.

Mapping code paths to documentation involves comparing code against existing specs to surface gaps, conflicts, and stale mappings. A YAML mapping schema persists this relationship to track functional, architectural, and utility paths across the repository.

The best way to backfill specs incrementally is using session-state persistence to track progress across runs. This approach compares functional code paths against the specs tree, verifying alignment and persisting changes via state files to handle ongoing updates.

Yes, you need git and yq installed to backfill documentation from a repository. Git history is analyzed to extract observable behavior, while yq processes the YAML mapping schema and session-state files required for spec generation and verification.

Yes, you can target specific code paths for spec generation instead of the whole repository. Targeted workflows allow you to focus spec generation and verification on particular functional areas, distinguishing them from architectural and utility paths.

Generating specs from code and documentation relies on observable behavior extracted from existing paths, meaning undocumented or utility code may lack sufficient context. It requires a predefined YAML mapping schema and cannot infer features absent from git history or source files.