trace-requirement

Trace Requirement

Build a traceability matrix from specs/release-plan.yaml + epic capsule directories to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.

Pre-flight

HARD GATE — specs/release-plan.yaml + epic capsule directories must exist. If it doesn't, run plan-release first.

→ verify: test -f specs/release-plan.yaml && test -d specs/epics

Read specs/release-plan.yaml + epic capsule directories fully before proceeding.

Process

1. Extract story IDs

From release-plan.yaml, collect all story IDs (e.g. 1.1, 1.2, 2.1).

→ verify: grep -rho 'e[0-9]\+s[0-9]\+' specs/release-plan.yaml specs/epics/*/epic.yaml 2>/dev/null | sort -u | head -1 | grep -q .

2. Search for story tags in code

Look for // story: X.Y or # story: X.Y comments in source files and tests:

grep -rn "story: " . --include="*.ts" --include="*.js" --include="*.py" --include="*.sh" | grep -v node_modules

→ verify: [ "$(grep -rl "story: " . --include="*.ts" --include="*.sh" --include="*.py" 2>/dev/null | wc -l | tr -d " ")" -gt 0 ]

3. Build the matrix

For each story ID:

• Implemented: list files that contain // story: X.Y
• Tested: list test files that contain // story: X.Y
• Dark: story has no tag in any file — flag as unimplemented

For each tagged file with no matching story ID in release-plan.yaml:

• Orphan: code exists but story was removed or never planned — flag for cleanup

4. Write specs/TRACEABILITY_LATEST.md

## Story Coverage

| Story | Title              | Files | Tests | Status    |
|-------|--------------------|-------|-------|-----------|
| 1.1   | [title]            | 2     | 1     | Covered   |
| 1.2   | [title]            | 0     | 0     | Dark      |

## Orphan Code (no story tag)
- [file]: contains untagged implementation

## Gaps (dark stories)
- Story 1.2: no implementation found → run plan-work

## Coverage summary
Stories: [X] covered / [Y] dark / [Z] total

→ verify: grep -c "Covered\|Dark" specs/TRACEABILITY_LATEST.md

Suggest plan-work for each dark story found.