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.