/gaia-trace

Arguments

This command takes no arguments. All inputs are discovered from the project file layout: the PRD, epics-and-stories, and test plan are resolved via path-fallback rules (flat and strategy/ placements).

Wire-verification gate

The traceability matrix includes a surface_type column in both the FR and NFR tables. This column classifies each requirement's user-visible delivery surface using the surface-type taxonomy:

Enforcement (Step 6c): when any FR/NFR has surface_type != none AND zero linked integration-test rows, the wire-verification-emit.sh helper:

1. Emits a BLOCKED-severity finding to stderr listing all violating FR/NFR IDs.
2. Writes FAILED into the canonical "Test Review" row of the story's Review Gate table via review-gate.sh update.
3. The existing Review Gate dominance rule (any FAILED = composite BLOCKED) automatically refuses the review to done transition.

Forward-only adoption: stories without a surface_type: frontmatter field are treated as surface_type: none and produce no findings. Existing stories are tolerated without backfill.

FAILED does not auto-flip: a clean re-run of /gaia-trace does not reset a FAILED Test Review verdict to PASSED. The operator must re-run /gaia-review-all to restore the gate.

What it does

/gaia-trace generates a traceability matrix that maps every PRD requirement (FR and NFR) to its implementing story and covering test cases. It identifies gaps where requirements lack test coverage, flags orphan tests without requirement mappings, and computes an implementation-readiness gate decision.

When to use it

• You need to verify that all PRD requirements have at least one test covering them.
• You want a single document showing the requirement-to-story-to-test chain for audit or review.
• You are preparing for sprint planning and want to confirm implementation readiness.

Prerequisites

• A PRD must exist at .gaia/artifacts/planning-artifacts/prd.md with FR/NFR requirements. Run /gaia-create-prd first if missing.
• Epics and stories should exist at .gaia/artifacts/planning-artifacts/epics-and-stories.md for the requirement-to-story mapping.
• A test plan is recommended at .gaia/artifacts/planning-artifacts/test-plan.md (canonical location) for the story-to-test mapping. Legacy .gaia/artifacts/test-artifacts/test-plan.md is read-compat for pre-migration projects.

How to invoke

/gaia-trace

What it does step by step

1. Load requirements Reads the PRD and extracts all FR-xxx and NFR-xxx identifiers as matrix rows. Reads epics-and-stories.md to build the FR/NFR-to-story mapping.
2. Load test inventory Scans test-plan.md for test case IDs and their story/requirement mappings. Records test type (Unit, Integration, E2E, Manual, Performance, Security, Accessibility).
3. Build matrix Constructs the FR requirements matrix (FR ID, Description, surface_type, Stories, test coverage per type, coverage percentage) and the NFR requirements matrix (NFR ID, Description, surface_type, Category, Target, Tests, Status). The surface_type column is read from each linked story's frontmatter; stories without the field default to none.
4. Gap analysis Identifies requirements with no implementing story, requirements with stories but no tests, orphan tests with no requirement mapping, and high-risk stories without ATDD scenarios.
5. Generate matrix Writes the compiled traceability matrix with FR table, NFR table, story-to-AC detail, gap summary, and coverage statistics.
6. Gate verification Invokes the validate-gate script to confirm the matrix was written successfully. Reports PASS, BLOCKED, or CONDITIONAL based on coverage of high-risk requirements.
7. Dispatch-verb enforcement (Step 6b) For each story walked, runs trace-dispatch-verb-enforcement.sh to verify that dispatch-verb ACs in medium/high-risk stories have at least one integration-test row in the matrix.
8. Wire-verification enforcement (Step 6c) For each story walked, runs wire-verification-emit.sh. When any FR/NFR has surface_type != none and zero linked integration rows, emits a BLOCKED finding and writes FAILED into the story's Test Review gate. See the Wire-verification gate section for details.

Pre-create-story caveat. Steps 6b and 6c walk story files. If /gaia-trace is invoked before /gaia-create-story has produced any story files (for example immediately after PRD + epics authoring), there are no stories to walk — both steps emit [NOTICE] skipped — no story files to trace (run /gaia-create-story first) and exit 0, NOT a vacuous PASS. Treat zero-stories as "deferred until story-creation phase", not as "no violations found".

Inputs

This command takes no arguments. All inputs are discovered from the project file layout.

Outputs

Examples

1. Happy path -- full matrix generation

> /gaia-trace

Loading requirements from prd.md... 12 FRs, 5 NFRs found.
Loading test inventory from test-plan.md... 38 test cases found.
Building matrix...

Functional Requirements:
  FR-001  User login       command  E1-S1    Unit: 2, E2E: 1, Int: 1   100%
  FR-002  Password reset   command  E1-S3    Unit: 1, Int: 1            75%
  FR-003  Role management  none     --       --                          0%  [GAP]

NFR Coverage: 4/5 covered (80%)

Gaps found:
  - FR-003: No implementing story

Gate: CONDITIONAL (1 FR without implementing story)
Step 6b: dispatch-verb enforcement: clean.
Step 6c: wire-verification: clean.

Written to .gaia/artifacts/test-artifacts/traceability-matrix.md

2. surface_type column rendering

The matrix now includes a surface_type column read from each linked story's frontmatter. Stories without the field show none (forward-only adoption).

Functional Requirements:
  FR ID    | Description         | surface_type | Story(s) | Unit | Int | E2E | Coverage
  FR-001   | User login          | command      | E1-S1    | 2    | 1   | 1   | 100%
  FR-008   | Config validation   | config       | E8-S3    | 1    | 0   | 0   | 33%
  FR-010   | Audit log export    | output       | E9-S2    | 1    | 1   | 0   | 66%
  FR-012   | Legacy migration    | none         | E10-S1   | 2    | 0   | 0   | 50%

3. BLOCKED finding -- missing integration row for a wired surface

When surface_type != none and zero integration-test rows link to the FR, Step 6c emits a BLOCKED finding and writes FAILED to the story's Test Review gate.

> /gaia-trace

...
Step 6c: wire-verification enforcement:

HALT: wire-verification gate failed for E8-S3:
  FR-008 (surface_type: config) -- 0 integration-test rows.
  FR-009 (surface_type: warning) -- 0 integration-test rows.

  review-gate.sh update --story E8-S3 --gate "Test Review" --verdict FAILED

  The story cannot transition from review to done until integration
  tests covering these surfaces are added and /gaia-review-all
  restores the Test Review gate to PASSED.

4. Clean re-run after gap fixed (no auto-flip)

After adding the missing integration tests, re-running /gaia-trace produces a clean Step 6c. However, the Test Review gate does not auto-flip from FAILED to PASSED. The operator must run /gaia-review-all to restore the gate.

> /gaia-trace

...
Step 6c: wire-verification: clean (0 violations).

NOTE: Test Review gate for E8-S3 is still FAILED from a prior run.
      Run /gaia-review-all to restore the gate to PASSED.

Written to .gaia/artifacts/test-artifacts/traceability-matrix.md

5. Forward-only adoption -- existing stories without surface_type

Stories created before the surface_type column was introduced lack the surface_type: frontmatter field. These are treated as surface_type: none and produce no wire-verification findings.

> /gaia-trace

Loading requirements from prd.md... 20 FRs, 8 NFRs found.
Building matrix...

  FR-015  User preferences   none     E14-S2   Unit: 3, E2E: 1   100%
  (surface_type field absent in E14-S2 frontmatter -- defaulting to none)

Step 6c: wire-verification: clean (0 violations).
  18 stories scanned, 12 with surface_type field, 6 defaulted to none.

Written to .gaia/artifacts/test-artifacts/traceability-matrix.md

What to run next

• /gaia-ci-setup -- scaffold the CI pipeline once traceability is green.
• /gaia-readiness-check -- confirm implementation readiness when CI is already in place.
• /gaia-fill-test-gaps -- remediate coverage gaps identified by the matrix.

Troubleshooting

"PRD not found"

The PRD must exist at .gaia/artifacts/planning-artifacts/prd.md. Run /gaia-create-prd first.

"No FR/NFR requirements found"

The PRD exists but contains no requirements in FR-xxx or NFR-xxx format. The command generates an empty matrix with headers only.

Gate shows BLOCKED

A high-risk functional requirement has zero test coverage. Add tests for the flagged requirements before proceeding.

Wire-verification HALT

Step 6c found FR/NFR rows with surface_type != none and zero integration-test coverage. Add integration tests covering the listed surfaces, then re-run /gaia-trace to clear the HALT. After a clean run, invoke /gaia-review-all to restore the Test Review gate from FAILED to PASSED -- the gate does not auto-flip.

Test Review stuck at FAILED after clean re-run

This is expected behavior. /gaia-trace writes FAILED but does not write PASSED. Run /gaia-review-all to re-evaluate and restore the gate.

Related commands