---
name: project-traceability-sync
description: Use when creating, updating, or repairing traceability maps between brainstorm, PRD, architecture, implementation, decision, evidence, memory, request/issue/bug/compatibility intake, tracking, changelog, health, agent/session, and document-branch IDs. Maintains docs/traceability maps, `.prd_plugin/state` JSON, and `.prd_plugin/ids/registry.json` consistency.
---

# Project Traceability Sync

Use `traceability_sync_auto.py` when the installed helper is available to
reconcile deterministic graph/index mechanics, then use `prd_link` for guarded
record relationships. Never invent a missing record merely to satisfy a graph
edge.

Use this skill to keep project IDs connected across artifacts.

## Sync Steps

1. Read `.prd_plugin/ID-SCHEME.md` and query exact records with
   `prd_find`/`prd_get` when present.
2. Scan changed brainstorm, PRD, architecture, implementation, decision,
   evidence, memory, requests, tracking, changelog, health, and session files.
3. Use `prd_link` for supported record relationships; record creation tools own
   registry allocation.
4. Update traceability maps so source IDs map forward:
   - `BR-* -> PRD-* -> ARCH-* -> IMP-* -> EV-*`
   - `DEC-* -> affected PRD/ARCH/IMP/EV IDs`
   - `DBR-* -> DBR-DELTA-* -> EV-* -> DBR-MERGE-*`
   - `AGENT-* -> SES-* -> OBS-* -> MEM-* -> TRK-* / CHG-* / EV-*`
   - `REQ-* -> TRK-* / DBR-* / PRD-* / ARCH-* / IMP-* / CHG-* / EV-*`
   - `HLT-* -> affected IDs -> resolving EV-* or source changes`
5. Remove or mark stale links only when the artifact no longer exists or the link is explicitly superseded.
6. Validate JSON and JSONL after edits.

## Staleness Coverage

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


When syncing maps, preserve stale links until the source artifact is gone,
superseded, or refreshed by evidence. Also surface stale `TRK-*`, `REQ-*`,
`DBR-*`, `MEM-*`, and `HLT-*` records that no longer match current artifact
links so health checks can act on them.

## Rules

- Prefer sparse but accurate maps over broad guessed maps.
- Do not invent completed evidence. Use empty evidence lists when no `EV-*` exists yet.
- Open questions should remain visible as `BR-Q-*` or matching question IDs.
- If a requirement has no architecture or plan mapping yet, record the gap instead of hiding it.

## Output

Lead with traceability gaps fixed or remaining. Include changed files and IDs.