| name | kiss-traceability-matrix |
| description | Builds and maintains a Requirements Traceability Matrix (RTM) that links every requirement (FR-NNN / NFR-NNN from the SRS) to its design section, implementation task, test case, and bug report. Supports forward traceability (requirements → delivery) and backward traceability (artefacts → requirements). Use when a Waterfall project needs to demonstrate that every requirement is designed, implemented, and tested; when a customer or auditor asks for full traceability evidence; or when performing a coverage gap analysis before a phase gate. |
| compatibility | Requires kiss project structure with .kiss/ directory |
| metadata | {"author":"github-kiss","source":"agent-skills/kiss-traceability-matrix/kiss-traceability-matrix.md"} |
User Input
$ARGUMENTS
Consider the user input before proceeding (if not empty).
Audience and tone (interactive mode)
When KISS_AGENT_MODE=interactive (the default), assume the user
has limited technical background and limited domain knowledge.
Run this skill as a guided questionnaire:
- One question at a time. No walls of questions.
- Yes / no first. Phrase so
yes, no, not sure, or skip
is a valid answer.
- Translate jargon, don't strip it. Explain RTM, traceability,
coverage gap on first use.
- Choices, not blank fields. Offer lettered options (A/B/C/D)
with one-line descriptions. Always include "Not sure — sensible
default".
- Always recommend. State which option you would pick and why.
- Show, don't ask. Pre-fill from upstream artefacts; ask for
yes / no confirmation.
not sure / skip triggers a sensible default, marked
"(default applied)" and a RTMDEBT entry.
When KISS_AGENT_MODE=auto, skip the questionnaire and log
decisions to the parent agent's decision log.
Inputs
.kiss/context.yml{context.paths.docs}/analysis/srs.md — FR-NNN / NFR-NNN
identifiers (required; if absent, prompt user to run
/kiss.srs first){context.paths.docs}/analysis/srs.extract — ID counters{context.paths.docs}/design/**/*.md — design sections{context.paths.tasks}/**/tasks.md — task IDs (TASK-NNN){context.paths.docs}/testing/**/test-cases.md — test case IDs
(TC-NNN){context.paths.docs}/bugs/*.md — bug report IDs (BUG-NNN)
Outputs
{context.paths.docs}/analysis/traceability-matrix.md — the RTM
(primary artefact){context.paths.docs}/analysis/traceability-matrix.extract —
companion KEY=VALUE ledger
(RTM_REVISION, COVERAGE_PCT, UNCOVERED_REQS, LAST_UPDATED){context.paths.docs}/analysis/rtm-debts.md — traceability gaps
and open items (RTMDEBT-NN: …)
Context Update
Does not mutate .kiss/context.yml.
Handoffs
kiss-phase-gate reads traceability-matrix.extract to verify
that COVERAGE_PCT meets the gate threshold before sign-off.kiss-test-execution appends pass/fail status per TC-NNN, which
updates the RTM's test-result column.kiss-baseline can snapshot traceability-matrix.md as part of
the verification baseline.
AI authoring scope
Does:
- Parse FR-NNN / NFR-NNN IDs from
srs.md.
- Scan design docs, tasks, test cases, and bug reports to detect
links.
- Populate the RTM table and calculate coverage percentages.
- Flag requirements with no design, task, test, or bug link as
RTMDEBT entries.
- Support incremental update: re-running the skill refreshes
existing rows rather than overwriting manual edits.
Does not:
- Invent or remove design sections, tasks, or test cases.
- Accept the gap as "acceptable" on the user's behalf.
- Modify any source artefact (spec, design, tasks, test cases).
Outline
-
Load SRS — parse srs.md for every FR-NNN / NFR-NNN entry.
If not found, stop and instruct the user to run /kiss.srs first.
-
Discover linked artefacts:
- Design: scan
{docs}/design/**/*.md for headings referencing
FR-NNN / NFR-NNN.
- Tasks: scan
tasks.md files for requirement references.
- Test cases: scan test-case files for "Covers: FR-NNN" tags.
- Bugs: scan bug report files for requirement references.
-
Interactive gap check (interactive mode only) — if uncovered
requirements are found, ask:
a. Do you want to mark them as "Out of Scope" or "Deferred"?
b. Should a RTMDEBT entry be raised for each gap?
-
Build / update the RTM table — one row per requirement ID,
columns: ID | Title | Priority | Design Ref | Task ID(s) |
Test Case ID(s) | Test Status | Bug ID(s) | Coverage Status.
-
Compute coverage metrics:
- Coverage % = requirements with ≥1 test case / total requirements.
- Design coverage % = requirements with ≥1 design ref / total.
- Task coverage % = requirements with ≥1 task / total.
-
Write outputs — write traceability-matrix.md,
traceability-matrix.extract, and rtm-debts.md.
-
Summary — print:
- Total requirements, coverage %, open gaps.
- Suggested next action if coverage < 100%.
Usage
<SKILL_DIR> = the integration's skills root.
RTM_COVERAGE_THRESHOLD=80 \
bash <SKILL_DIR>/kiss-traceability-matrix/scripts/bash/build-rtm.sh --auto
Answer keys
| Key | Meaning | Default |
|---|
RTM_COVERAGE_THRESHOLD | Minimum coverage % to pass a gate | 80 |
RTM_INCLUDE_NFRS | true / false — include NFRs in RTM | true |
