Home / admin / requirements-traceability-matrix

requirements-traceability-matrix

Use this skill when building or maintaining a Requirements Traceability Matrix (RTM) on a Salesforce project: one row per requirement, columns for source, user-story id(s), test-case id(s), defect id(s), sprint, release, and status.

• v1.1.5
• Salesforce Spring '25+
• Updated 2026-09-12
• Operational Excellence
• Reliability

• requirements-traceability
• rtm
• audit
• delivery-governance
• business-analysis

Open the skill folder on GitHub

Requirements Traceability Matrix (RTM) for Salesforce

This skill activates when a Business Analyst, delivery lead, or admin needs to build or maintain the artifact that ties every approved requirement to its user story, code, test, defect, and release on a Salesforce project. It is the single document every audit and every Steerco demands: forward traceability proves that scope was delivered, backward traceability proves that no surprise scope was added.

Before Starting

Gather this context before opening the RTM:

• Are requirement IDs already assigned? If the elicitation phase did not produce stable REQ-XXX IDs — or, on a fit-gap-led project, stable FG-XXX IDs (see § REQ-XXX ⇄ FG-XXX) — stop and assign them first. RTM rows are keyed on requirement ID — using titles or descriptions as the key creates duplicates and breaks every downstream join.
• What is the agile tool of record? Jira, Azure DevOps, Salesforce DevOps Center, or GUS each store user-story IDs in their own format. The RTM mirrors the source system; it does not invent its own story IDs.
• What is the regulatory or audit posture? A regulated project (HIPAA, SOX, GxP, FedRAMP) needs a source column that distinguishes regulatory requirements from elicited ones, plus a per-row evidence link. A non-regulated greenfield project can ship a lighter RTM.
• Who owns RTM updates? RTM rot is the most common failure mode — assign a single owner (usually the lead BA) and a cadence (end of every sprint and at every release gate).

Questions to Ask Before Configuring

Ask these before the first row is written. A matrix built without them looks complete and joins to nothing.

What a proper configuration adds over just keeping a list of requirements: the matrix answers "which deployed component satisfies this requirement, who built it, which decision produced it, and which test proved it" as a lookup rather than an investigation — and its two derived views turn the question "are we done?" into a gate a machine can fail.

Core Concepts

Canonical Column Set

The minimum viable RTM has these columns. Every row is one requirement. Multi-valued cells (e.g., several user stories implementing one requirement) are pipe-delimited so the file stays diff-friendly in Git.

Optional columns for regulated projects: compliance_control_id (e.g., HIPAA-164.312(a)(1)), evidence_link (URL to test result, signed approval, or audit log).

The Build-Layer RTM: traceability.md

standards/build-orchestration.md § 2 gives every build a .sfskills/builds/<build-id>/traceability.md that maps REQ / clarification id → step → artefact path → test result, written by agents/build-doc-keeper/AGENT.md after each step is tested. That file is this skill's format — the build layer does not define a second one. The audit RTM above and traceability.md are the same matrix at two altitudes: the audit RTM is keyed on the requirement and rolls up to a release; the build-layer RTM adds the columns a build needs (step_id, artefact, agent, decision_ref, test_type) and drops the ones only a multi-release programme has.

step_id, decision_ref and test_type are what make the row executable: a gate can re-run the test, re-read the decision, and re-run the step. story_ids, defect_ids, sprint and release stay in the audit RTM — a build has one release by definition. Worked end to end in references/worked-examples.md.

Two views are derived from the matrix and are the only things a gate reads: coverage gaps (requirements with no artefact or no test) and orphans (artefacts with no requirement).

REQ-XXX ⇄ FG-XXX: Which Prefix Is the Key

Two id families reach the same column. admin/requirements-gathering-for-sf mints REQ-XXX at elicitation. admin/fit-gap-analysis-against-org mints FG-XXX per gap row, and admin/configuration-workbook-authoring → references/examples.md shows FG-014 sitting in the workbook's source_req_id column — so on a fit-gap-led project the workbook's key is FG-, not REQ-. Both are legal RTM keys. The mapping rule:

Two rows for one need is the failure this rule prevents: coverage counts double, and the gate cannot tell which of the two is authoritative. scripts/check_rtm.py accepts either prefix and errors on a key that matches neither.

Forward vs Backward Traceability

• Forward traceability (req → story → code → test → release) proves that every approved requirement was actually delivered. Used at release gate review.
• Backward traceability (test → req) proves that every test case maps to an approved requirement — i.e., no scope crept in without an approval trail. Used at audit time.

A complete RTM supports both directions. The most common gap is backward — tests get written against stories that drifted from the original requirement, and nobody updates the matrix.

ID Conventions

• REQ-XXX — requirement ID, assigned during elicitation, immutable.
• US-XXX — user story ID, mirrored from the agile tool.
• TC-XXX — test case ID, mirrored from the test management tool.
• DEF-XXX or BUG-XXX — defect ID, mirrored from the defect tracker.
• Use a project-prefix (e.g., ACME-REQ-001) when running multiple programs in the same agile tool to prevent collision.

One-to-Many Cardinality

The relationships are not 1:1:

• 1 requirement : N stories — a requirement like "agents can triage cases" splits into multiple stories (queue setup, assignment rule, escalation, SLA timer). The RTM lists all story IDs in the story_ids cell.
• 1 story : N test cases — UAT typically has happy path, validation, and exception cases per story.
• N stories : 1 requirement is the rule — never split a requirement across rows. Keep the requirement on one row and pipe-delimit its stories.
• 1 test case : 1+ requirements — a regression test can validate multiple requirements. Mirror the test ID into each requirement row it covers.

The Audit Pass

At every release gate and at audit time, run a pass over the RTM:

1. Coverage check — every requirement with status Released must have at least one story_ids and one test_case_ids value. Empty cells are coverage gaps.
2. Status check — every requirement with status In UAT must have at least one test_case_ids value. In Build must have at least one story_ids.
3. Drop check — every requirement with status Deferred or Dropped has a documented decision (owner + date + rationale) in the requirements doc or a decision log.
4. Backward check — sample 10% of test_case_ids and confirm each one appears in some req_id row (no orphan tests).
5. Source check — count rows by source. Regulatory requirements with status Dropped are an audit red flag and need an explicit waiver document.

Common Patterns

Pattern: RTM as Single Source of Truth (CSV-in-Git)

When to use: Any Salesforce project where the BA team owns delivery governance and wants version control over the matrix.

How it works:

1. Store the RTM as a CSV in the project repo at a known path (e.g., governance/rtm.csv).
2. The CSV columns match the canonical column set above.
3. Every requirement update is a Git commit with a message linking the change request or decision.
4. A nightly or per-PR CI job runs scripts/check_rtm.py against the CSV and flags orphans, duplicates, and invalid statuses.
5. A markdown rendering of the CSV is generated for Steerco distribution — never hand-maintain the markdown.

Why not a spreadsheet: Spreadsheet RTMs decay because nobody can audit who changed what. CSV-in-Git gives blame, history, and review.

Pattern: Two-Phase Population

When to use: Greenfield Salesforce projects with a discrete planning and build phase.

How it works:

1. Planning pass (forward traces): As stories are written, populate req_id, source, description, priority, story_ids, sprint, and set status to Draft or In Build.
2. Build/UAT pass (test traces): As UAT cases are authored, populate test_case_ids. Move status to In UAT.
3. Hypercare pass (defect traces): As defects are raised against released requirements, populate defect_ids. Defects raised against a non-released requirement are escalated to scope, not silently absorbed.
4. Release pass: When a release deploys, populate release for every requirement that landed and move status to Released.

Decision Guidance

Recommended Workflow

1. Fix the schema and the key first. Choose the audit schema (templates/rtm.md § CSV Schema)

   or the build-layer schema (§ The Build-Layer RTM above, worked in references/worked-examples.md). Apply the REQ-XXX ⇄ FG-XXX rule and write the mapping table if both prefixes are in play. Locking this before row 1 is the whole job — every later fix is a migration.

2. Seed one row per requirement from the clarifications, not the backlog. In a build, the row

   set comes from plan.json.clarifications[] and requirement.md; source carries the Q<n> id. Seeding from the backlog inverts the direction and guarantees the orphan view is empty by construction, which is the failure gotcha 2 describes.

3. Fill step_id, artefact, agent and decision_ref as the plan is written. The artefact is

   the Metadata API name (CustomField:Account.Region__c), never the UI label — see gotcha 10. Mark the rows whose components the Metadata API cannot carry as setup-only now, not after the first false alarm (gotcha 14).

4. Fill test_id and test_type as the tester runs, one of the five runners from

   standards/build-orchestration.md § 5 (checker / xml / manifest / command / manual). A row that reaches In UAT with an empty test_id is a coverage gap, not a formatting problem.

5. Run the checker at every gate, not at the end:

   python3 scripts/check_rtm.py --manifest-dir .sfskills/builds/<build-id> --repo-root <repo>. It fails the gate (exit 1) on a duplicate or malformed id, a row with no artefact or no test, an agent id that does not resolve to agents/<id>/AGENT.md, and — under --strict — an artefact API name it cannot find in the manifest. Add --self-check to prove the rules still fire.

6. Publish the two derived views the gate reads — the coverage-gap report and the orphan report

   (references/worked-examples.md §§ 5–6). Every coverage gap is either closed or waived with an owner and a date; every orphan is either given a requirement or listed as a destructive change.

7. Re-run steps 3–6 after every milestone gate and diff the matrix against the previous

   milestone. A row whose artefact changed without its decision_ref changing is drift — the thing gotcha 1 is about — and it is only visible in the diff.

Review Checklist

Run through these before handing the RTM to Steerco or audit:

• [ ] Every row has a unique req_id; no duplicates
• [ ] Every requirement with status Released has at least one story_ids and one test_case_ids value
• [ ] Every requirement with status In UAT has at least one test_case_ids value
• [ ] Every requirement with status Deferred or Dropped has a documented decision (owner + date + rationale)
• [ ] Every status value is in the enum: Draft / In Build / In UAT / Released / Deferred / Dropped
• [ ] Every source value is in the enum: interview / sow / regulatory / change-request / defect-driven
• [ ] No requirement IDs reused across the project lifetime (e.g., REQ-042 means the same thing in R1.0 and R2.0)
• [ ] A 10% sample of test cases trace back to a requirement (backward traceability sample)
• [ ] Multi-valued cells use the pipe | delimiter — no commas, no semicolons
• [ ] Markdown rendering is generated, not hand-edited
• [ ] Regulated rows (if applicable) have populated compliance_control_id and evidence_link

Salesforce-Specific Gotchas

Non-obvious delivery realities that cause real audit findings:

1. Bidirectional drift — A requirement is updated mid-flight (often via a verbal change in a workshop), but the linked story is not updated. The RTM still says story US-101 implements requirement REQ-007, but the story now delivers a different behavior. Always update both sides of the link in the same change.
2. RTM in a spreadsheet that nobody maintains — The most common failure mode. The RTM lives in a SharePoint or Google Sheet, gets populated at project start, and is never updated. By release, it is fiction. CSV-in-Git with a per-PR check is the only durable fix.
3. IDs reused across phases — Phase 1 ships REQ-001 through REQ-050. Phase 2 starts a new RTM and reuses REQ-001. Now defects raised in Phase 2 reference an ambiguous requirement. Always continue the numbering or use a phase prefix.
4. Missing the deferred/dropped column — Teams delete dropped requirements to keep the matrix clean. Auditors then ask "you scoped 200 requirements, you delivered 150 — where are the other 50?" and there is no answer. Dropped requirements are first-class rows.
5. Backlog churn outpaces RTM — In aggressive sprint teams, stories are split, merged, and renamed weekly. If the BA only updates the RTM at release gates, the matrix is months stale. Update at end of every sprint or use a CI job that diffs the agile tool against the RTM.
6. Salesforce-specific platform constraints not surfaced as requirements — A requirement like "agents can update 1M cases" implicitly demands Bulk API or Batch Apex. If that platform constraint is not captured as a sub-requirement, the RTM looks complete while the system is unsupportable. Surface platform constraints as their own REQ rows linked to the parent.

Output Artifacts

Reference Files

Related Skills

• admin/requirements-gathering-for-sf — use first to elicit and mint the REQ-XXX ids the matrix is keyed on
• admin/fit-gap-analysis-against-org — mints the FG-XXX ids; read it before applying the REQ ⇄ FG mapping rule
• admin/user-story-writing-for-salesforce — authors the stories whose ids populate story_ids in the audit schema
• admin/uat-test-case-design — the per-case field schema behind the test_id column
• admin/uat-and-acceptance-criteria — runs the programme that produces the manual test results this matrix records
• admin/acceptance-criteria-given-when-then — the AC form a manual test id resolves to
• admin/configuration-workbook-authoring — consumes req_id as source_req_id; its RTM linkage block is the workbook-side half of this matrix
• admin/moscow-prioritization-for-sf-backlog — populates priority in the audit schema
• admin/case-management-setup — supplies the build worked in references/worked-examples.md
• devops/metadata-api-retrieve-deploy — the retrieve/deploy mechanics behind the artefact column and the destructive-change path for a dropped row
• standards/build-orchestration.md — defines traceability.md, the step ids, and the five test types this matrix uses
• agents/build-doc-keeper/AGENT.md — writes traceability.md after every tested step
• agents/milestone-verifier/AGENT.md — reads the two derived views at the milestone gate
• agents/deployment-risk-scorer/AGENT.md — consumes the matrix at release gate; share the same release tag
• agents/audit-router/AGENT.md — consumes the matrix at audit time; needs the per-row evidence chain

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• references/worked-examples.md
• templates/requirements-traceability-matrix-template.md
• templates/rtm.md
• scripts/check_requirements_traceability_matrix.py
• scripts/check_rtm.py