Workflow Traceability

Requirements Traceability — lean, tiered, 100% — without the spreadsheet

The goal is the leanest system that is 100% traceable, not "gapless everywhere." Aerospace-grade traceability on a marketing site is a defect, not diligence. The trick (Gojko Adzic's Specification by Example): the artifacts you already write ARE the trace links — you never keep a separate matrix. The only "extra" you maintain is an ID and a link; the RTM is generated, never hand-kept.

This skill is the single home for the model. workflow-flow-review applies it to flows; meta-adr-authoring owns the ADR half; meta-lifecycle-stage supplies the tier.

Trigger

• "Is this traceable?" / "Are all the user flows covered?" / "Why is this the right set of flows?"
• Speccing or planning a non-trivial feature (the IDs + footer come from here).
• A demo or handoff gate (run the audit with --gate; emit the RTM as a deliverable).
• "Where does this decision live?" / "The client changed their mind — how do I record it?"

Two homes, four sources (every line resolves to exactly one)

A line that resolves to none of these is an orphan — the thing the audit detects. This is the rule that forbids "I improvised": a design decision tracing to neither a skill you read nor a SOW/REQ line has no home but an ADR (write one — see meta-adr-authoring).

The ID namespace (project-scoped to avoid cross-repo collision)

• REQ-<PROJ>-<AREA>-<NNN> — requirement (EARS). e.g. REQ-PIC-AUTH-001.
• ADR-<NNNN> — decision record (immutable, numbered).
• PERSONA-<slug> — a persona in the registry.
• FLOW-<NN> — a user flow.
• SCREEN-<slug> — = the mockup filename (mockups/login.html → SCREEN-login). This is the free join between flows and views.
• Q-<NNN> — a client question (only-the-client-can-answer, costly/irreversible).

The spine (orphan-free in both directions)

SOW§ / ADR / constitution
   └─→ REQ-id (EARS)  ──story──  PERSONA + FLOW
         └─→ SCREEN (mockup file)
               └─→ plan task (cites REQ + SCREEN)
                     └─→ test (tagged REQ)  →  commit (cites REQ/ADR)
                           └─→ usability task (FLOW + persona goal)

Forward: every REQ has a source; every SOW capability has a covering REQ. Backward: every spec element earns its place. Down: every flow step names a SCREEN. The **Implements:** line in workflow-plan is the REQ→task link; a test tagged with a REQ is the verify link.

The tiering matrix — lean where it can be, rigorous where it must be

Rigor is keyed to two markers: .claude/project-type sets the ceiling; .claude/project-stage sets how far up you climb. Persimmon's two project types are internal-tool and marketing-site; hybrid is handled per-surface — an operated surface (admin, payments, dashboards, anything touching money/auth/PII regardless of where it sits in the nav) takes the internal-tool row; public marketing pages take the marketing-site row.

Two rules baked into every cell: (a) verified = a tagged automated test (vitest/Playwright) OR a dated manual user-workflow checklist item (never force E2E on a site that doesn't warrant it); (b) the audit never blocks mid-build — it gates only at demo/handoff, and skip workflow: always exists. The audit detects; the human chooses not to bypass. Don't tell yourself a script "forces" anything.

The payout is at handoff. Under Persimmon's "client keeps the code and the keys, no subscription lock-in" model the RTM is a deliverable feature. Emit the full RTM at handoff; don't tax prototype code that may be cut.

The audit (scripts/traceability-audit.mjs) — detection, not enforcement

node <persimmon-skills>/scripts/traceability-audit.mjs <project-docs-root> [--gate] [--json]

Dependency-free Node, docs-only (no DB, no creds, no schema coupling). It is a link-checker: it reads requirements.md / personas.md / flows.md + the mockups/ and decisions/ dirs, reports orphans (REQ w/o source, FLOW w/o persona/source, FLOW→missing persona/screen/ADR, uncovered screens), and generates the RTM as a view. Default exits 0 (a report); --gate exits 1 on orphans — use only at the demo/handoff transition (see meta-lifecycle-stage). See ADR-0006.

What it cannot do, by construction: find a flow nobody authored. A missing user journey (a forgotten password-reset, an unspecified empty/error state) is caught by the human four-source method in workflow-flow-review, not here. A green audit is NOT a completeness proof (ADR-0008). Keep the two claims separate: the audit proves links among authored nodes; the signed four-source method argues the node set is complete.

Doc conventions the audit parses (one ### <ID> block each) are documented in the script header — keep requirements.md, personas.md, flows.md in that shape.

The docs/ homes

docs/
  README.md            ← the map (the thin index .claude/project-rules.md points at)
  requirements/  personas.md · requirements.md (EARS+IDs) · flows.md (registry+RTM)
  decisions/     NNNN-{slug}.md (immutable ADRs) · README.md (index) — see meta-adr-authoring
  specs/         YYYY-MM-DD-{topic}.md (+ optional .html) · mockups/{screen}.html
  plans/         YYYY-MM-DD-{topic}.md
  context/       decisions.md · open-questions.md · changelog.md · meetings/YYYY-MM-DD-{topic}.md

Persimmon client repos already use docs/specs/, docs/plans/, docs/decisions/; this adds docs/requirements/ and docs/context/ (ADR-0007). install-in-project.sh scaffolds them idempotently. The design spec is not split — its EARS criteria carry REQ- IDs that live in requirements.md; IDs do the linking.

Point-in-time vs living; supersede, never delete

• Immutable, filename-identified: ADRs (docs/decisions/0007-{slug}.md), dated specs. Never edited after acceptance — superseding writes a new record and adds a Superseded by: header to the old. See meta-adr-authoring.
• Living, in-file status: requirements.md, personas.md, flows.md evolve in place; each REQ carries status: active|changed|removed + a changed: <date> — <meeting> trailer.
• Client contradicts a prior decision: capture the meeting (context/meetings/), record it (context/decisions.md), supersede the ADR or flip the REQ status, and log one line in context/changelog.md — what / why / who decided / which meeting / which REQ-ADR. A ledger without an author is half a record.

Relationship to other skills