---
name: project-traceability-review
description: Use when reviewing whether brainstorm, PRD, architecture, implementation plan, decisions, and evidence artifacts are consistently linked by IDs.
---

# Project Traceability Review

Use this skill to find missing or weak links between project artifacts.

## Review Targets

- Brainstorm records
- PRDs
- Architecture docs
- Implementation plans
- Decision records
- Evidence records
- Document branches
- Agent memory and tracking state under `.prd_plugin/state/`
- Request, issue, bug, and compatibility intake records under
  `.prd_plugin/state/requests.json`
- Project health findings under `.prd_plugin/state/health.json`

## Checks

1. Every `PRD-REQ-*` has a source.
2. Every major `ARCH-*` item maps to a requirement or decision.
3. Every `IMP-TASK-*` maps to requirements and architecture.
4. Every completion claim maps to evidence.
5. IDs are unique within their prefix.
6. Open questions are not silently treated as resolved.
7. Mainline docs do not contain unproven `DBR-*` branch claims as settled truth.
8. Promoted document branches have evidence, anchors, merge decisions, and
   regression conditions.
9. Promoted `MEM-*`, `TRK-*`, and `CHG-*` records include source references,
   `AGENT-*` and `SES-*` provenance, and no raw local session content.
10. Every `SES-*` maps to an `AGENT-*`, and promoted memory can be traced
    through observations where applicable.
11. Every open `HLT-*` finding cites affected IDs or source files, and resolved
    findings have evidence or source changes that justify closure.
12. Every accepted `REQ-*` record links to the `TRK-*`, `DBR-*`, `PRD-*`,
    `CHG-*`, or other artifact that carries the accepted work.
13. Every `MSG-*` record belongs to exactly one `REQ-*` thread, includes
    agent/session provenance, and respects repo/upstream visibility.
14. High-severity bug or compatibility `REQ-*` records include enough
    reproduction, environment, source, or health links to investigate.
15. Version-impacting or method-impacting changes have release/change coverage:
    version state, companion docs/templates for skill changes, or an explicit
    `HLT-*`/`REQ-*` follow-up.
16. Request/message records respect repo scope and upstream submission policy.
17. Inbox, outbox, and mailbox records do not contradict canonical
    `.prd_plugin/state/requests.json` records.
18. Evidence and session summaries do not claim `MEM-*`, `TRK-*`, `CHG-*`,
    `OBS-*`, or `SES-*` records that are absent from canonical PRD Plugin
    state.
19. Registry counters do not skip ahead of committed canonical records, and
    timestamped state or fixtures do not contain future completion times.

Run the required downstream validator
`python scripts/state_consistency_check.py --repo-root .` as part of
traceability review for repos with PRD Plugin state.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Include stale `TRK-*`, stale `REQ-*` or `MSG-*` threads, stale request
transport, stale automation locks, and scheduler-state drift in the review.
When stale records are found, report whether they should be resolved,
refreshed with evidence, superseded, or carried as explicit `HLT-*` findings.

## Output

Lead with findings ordered by severity. Include file paths and line references
when available. If no issues are found, say that clearly and mention residual
risk.

For a compact operational snapshot, update `.prd_plugin/state/health.json` with
`HLT-*` findings rather than treating the traceability review itself as project
state.