spec-verification

Spec Verification

Ensure code and tests still reflect the documented requirements. Detect and fix drift between specs, implementation, and tests.

When to use

• After implementation is complete (before marking work as done)
• When reviewing PRs that touch spec-covered code
• When work-review flags potential spec drift
• Periodically as a maintenance check

Steps

1. Find all specs. Locate .spec.md files in the project's specs/ directory:

   find specs/ -name "*.spec.md" 2>/dev/null
   

2. Validate structural integrity. For each spec, check that links resolve:

   • Verify each targets: path exists (expand globs, confirm matches)
   • Verify each [@test] link points to an existing test file
   • Confirm frontmatter has name, description, and at least one target

   # Use the bundled validation scripts:
   ./scripts/validate-specs.sh specs/
   ./scripts/check-spec-links.sh specs/
   

   If either script reports failures, record them as broken-link findings.

3. Run linked tests. Execute the test files referenced by [@test] links:

   # Extract test paths from specs and run them
   grep -rh '\[@test\]' specs/*.spec.md | sed 's/.*\[@test\] *//' | sed 's/`$//'
   

   If tests fail, diagnose the failure. Determine whether the test, the code, or the spec is wrong before proceeding.

4. Spot-check targets for drift. Read the files listed in targets: and compare against spec requirements:

   • For each requirement in the spec, confirm the target file implements it
   • Look for logic in target files that contradicts the spec (edge cases, error handling, data contracts)
   • Look for new behavior in target files not mentioned in any spec

5. Check for drift signals:

   • Behavioral changes in code not mentioned in the spec
   • Newly added tests without matching requirements (or vice versa)
   • Deleted or renamed files that still appear in targets: or [@test] links
   • New code paths in target files that aren't covered by any requirement