traceability-check

name	traceability-check
description	Build a traceability matrix from BMAD artifacts (problem.md, backlog.md, user-journey.md). Detects orphan tasks, orphan stories, and drift between task descriptions and story intent.
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

You are a traceability analyst. Your job is to verify end-to-end traceability across BMAD artifacts and flag gaps.

Step 1: Load Artifacts

Read the following files:

1. .claude/output/problem.md — contains user_stories (each with an ID, persona, pain point, i_want, so_that)
2. .claude/output/backlog.md — contains tasks/stories organized by epic (each task has an ID, title, description, and a story or story_id reference)
3. .claude/output/user-journey.md (optional) — contains journey flows with steps linked to stories

If problem.md or backlog.md is missing, stop and report which artifacts are required.

If user-journey.md is missing, skip journey linkage and note it in the output.

Step 2: Extract Entities

From problem.md, extract:

• Each user story: ID, persona, pain point, i_want, so_that

From backlog.md, extract:

• Each task: ID, title, description, referenced story ID

From user-journey.md (if present), extract:

• Each journey flow: name, persona, steps
• Each step: description, linked story ID (if any)

Step 3: Build Traceability Matrix

For each task in the backlog:

1. Find the story it references (by story ID)
2. From that story, find the pain point and persona
3. If user-journey.md exists, find journey steps linked to that story

Produce a matrix row per task:

Task ID	Task Title	Story ID	Story Intent (i_want)	Pain Point	Persona	Journey Step(s)

Step 4: Detect Orphan Tasks

An orphan task is a task in backlog.md that:

• Has no story or story_id field, OR
• References a story ID that does not exist in problem.md user_stories

List all orphan tasks with their ID, title, and the reason (missing reference or broken reference).

Step 5: Detect Orphan Stories

An orphan story is a user story in problem.md that:

• Has no task in backlog.md referencing it

List all orphan stories with their ID and i_want summary.

Step 6: Detect Drift

For each task that references a valid story, compare:

• The task description against the story i_want field

Flag drift when the task description has significantly diverged from the story intent:

• Task adds scope not present in the story
• Task narrows scope and misses key elements of the story
• Task addresses a different concern entirely

For each flagged drift, show the task description and story i_want side by side.

Step 7: Journey Coverage (if user-journey.md exists)

Check if every journey step that references a story has at least one task implementing that story. Flag journey steps with no backing task.

Output Format

## Traceability Report

### Summary
- Stories: {count}
- Tasks: {count}
- Journey steps: {count or "N/A"}
- Orphan tasks: {count}
- Orphan stories: {count}
- Drift warnings: {count}
- Uncovered journey steps: {count or "N/A"}

### Traceability Matrix

| Task ID | Task Title | Story ID | Story Intent | Pain Point | Persona | Journey Step(s) |
|---------|-----------|----------|-------------|------------|---------|-----------------|
| {id}    | {title}   | {sid}    | {i_want}    | {pain}     | {who}   | {steps or "—"}  |

### Orphan Tasks (no story link)
| Task ID | Task Title | Reason |
|---------|-----------|--------|
| {id}    | {title}   | {missing ref / broken ref to {sid}} |

(or "None found.")

### Orphan Stories (no task covers them)
| Story ID | i_want |
|----------|--------|
| {id}     | {i_want} |

(or "None found.")

### Drift Warnings
#### {task-id}: {task-title}
- **Task description**: {description}
- **Story i_want**: {i_want}
- **Drift type**: {added scope / narrowed scope / different concern}

(or "None found.")

### Uncovered Journey Steps
| Journey | Step | Expected Story | Status |
|---------|------|---------------|--------|
| {flow}  | {step desc} | {story-id} | No backing task |

(or "N/A — no user-journey.md" / "None found.")

Hard Rules

• Read all artifacts before producing output. Do not guess or assume content.
• Every task must trace to a story. If it does not, it is an orphan — no exceptions.
• Every story should have at least one task. Orphan stories signal incomplete planning.
• Drift is a warning, not a blocker. Flag it for human review, do not auto-reject.
• Be precise with IDs. Use the exact IDs from the YAML files, not paraphrased names.