trace-requirements

name	trace-requirements
description	Create comprehensive bidirectional requirements traceability matrix mapping acceptance criteria → implementation → tests with gap analysis, severity ratings, and coverage assessment. Maps each AC to implementation evidence (files, functions, code snippets) and test coverage (test files, scenarios, priorities). Use during quality review or for compliance audits to verify complete requirements coverage.
version	2
category	Quality
acceptance	{"forward_traceability":"All acceptance criteria mapped to implementation evidence with file paths, line ranges, function names, and code snippets demonstrating implementation","backward_traceability":"All tests mapped to acceptance criteria they validate with test files, scenarios, types (unit/integration/E2E), and priorities (P0/P1/P2)","gaps_identified":"Coverage gaps identified and classified by type (implementation/test), severity (CRITICAL/HIGH/MEDIUM/LOW), and priority (P0/P1/P2) with required actions","traceability_report_generated":"Complete traceability report generated with matrix, detailed entries, gap analysis, recommendations, and quality gate impact assessment"}
inputs	{"task_id":{"type":"string","required":true,"description":"Task identifier for traceability analysis (e.g., 'task-007')"},"task_file":{"type":"string","required":true,"description":"Path to task specification file"},"implementation_path":{"type":"string","required":false,"description":"Path to implementation code (defaults to project root)"},"test_path":{"type":"string","required":false,"description":"Path to test files (defaults to test directory)"},"risk_profile_file":{"type":"string","required":false,"description":"Path to risk profile file (for risk-informed gap severity)"},"test_design_file":{"type":"string","required":false,"description":"Path to test design file (for expected test scenarios)"}}
outputs	{"total_acceptance_criteria":{"type":"number","description":"Total number of acceptance criteria analyzed"},"implementation_coverage_percentage":{"type":"number","description":"Percentage of ACs with implementation evidence (0-100)"},"test_coverage_percentage":{"type":"number","description":"Percentage of ACs with test coverage (0-100)"},"traceability_score":{"type":"number","description":"Overall traceability score (0-100)"},"total_gaps":{"type":"number","description":"Total number of coverage gaps identified"},"critical_gaps_count":{"type":"number","description":"Number of critical severity gaps"},"high_gaps_count":{"type":"number","description":"Number of high severity gaps"},"traceability_report_path":{"type":"string","description":"Path to generated traceability report"},"quality_gate_impact":{"type":"string","description":"Predicted quality gate status (PASS/CONCERNS/FAIL)"}}
telemetry	{"emit":"skill.trace-requirements.completed","track":["task_id","total_acceptance_criteria","implemented_count","partial_implementation_count","not_implemented_count","implementation_coverage_percentage","tested_count","partial_test_count","not_tested_count","test_coverage_percentage","total_gaps","critical_gaps_count","high_gaps_count","medium_gaps_count","low_gaps_count","traceability_score","risk_profile_available","test_design_available"]}

Requirements Traceability Analysis

Perform bidirectional requirements traceability analysis ensuring every acceptance criterion is implemented and tested. Creates audit-ready traceability matrix showing complete chain: Requirements → Implementation → Tests.

Purpose

Create comprehensive traceability documentation that demonstrates:

• Forward traceability: AC → Implementation (with file/line evidence)
• Backward traceability: Tests → AC (with test scenario mapping)
• Gap identification: Missing implementation or test coverage
• Severity assessment: CRITICAL/HIGH/MEDIUM/LOW based on risk and impact
• Coverage metrics: Implementation coverage, test coverage, traceability score
• Quality gate impact: Prediction of gate status (PASS/CONCERNS/FAIL)

Key Capabilities:

• Evidence-based verification with file paths, line ranges, code snippets
• Integration with risk-profile (risk-informed gap severity)
• Integration with test-design (test-to-requirement mapping)
• Audit-ready documentation for compliance
• Actionable recommendations with effort estimates

When to Use This Skill

Best Used:

• During implementation review to verify all requirements addressed
• Before quality gate to ensure completeness
• During audit preparation to demonstrate traceability
• After test-design to map tests to requirements
• When coverage gaps need identification and prioritization

Integration Points:

• Reads task specification for acceptance criteria
• Reads risk profile for risk-informed gap severity (optional)
• Reads test design for test-to-requirement mapping (optional)
• Reads actual implementation files for evidence
• Reads test files for test coverage verification

Triggers:

• User asks to "trace requirements", "check coverage", "verify AC implementation"
• Before quality gate (proactively suggest)
• During code review (verify completeness)

Traceability Concepts

Forward Traceability (AC → Implementation): Maps each AC to implementation evidence (file, function, code snippet) | Status: ✅ Implemented, ⚠️ Partial, ❌ Not Implemented, ❓ Unclear

Backward Traceability (Tests → AC): Maps each test to ACs it validates | Status: ✅ Tested, ⚠️ Partial, ❌ Not Tested, 🔄 Indirect

Gap Severity: CRITICAL (9): Security/data integrity/core functionality | HIGH (6-8): Important requirements/P0 tests | MEDIUM (3-5): Minor requirements/P1 tests | LOW (1-2): Nice-to-have/P2 tests

See: references/templates.md for complete examples and classification details

SEQUENTIAL Skill Execution

CRITICAL: Do not proceed to next step until current step is complete

Step 0: Load Configuration and Context

Purpose: Load project configuration, task specification, and related assessments

Actions:

1. Load configuration from .claude/config.yaml:

   • Extract quality settings (assessmentLocation)
   • Extract risk score threshold (for gap severity assessment)

2. Get task file path from user:

   • Example: .claude/tasks/task-006-user-signup.md
   • Verify file exists and is readable

3. Read task specification:

   • Extract task ID, title, type
   • Load objective and context
   • Load Acceptance Criteria (primary traceability source)
   • Load Implementation Record section (files created/modified)
   • Load Quality Review section (if exists)

4. Load related assessments (optional but enhances analysis):

   • Risk profile: .claude/quality/assessments/{task-id}-risk-*.md (for gap severity)
   • Test design: .claude/quality/assessments/{task-id}-test-design-*.md (for test mapping)

5. Identify implementation files:

   • From task spec "Implementation Record" section
   • Files created/modified during implementation
   • Line ranges for each change

6. Prepare output:

   • Output directory: .claude/quality/assessments/
   • Output file: {task-id}-trace-{YYYYMMDD}.md
   • Template: .claude/templates/trace-requirements.md (if exists)

Output: Configuration loaded, task spec loaded with AC count, related assessments checked (risk profile/test design), implementation files identified, output path set

Halt If: Config missing, task file not found, no ACs, cannot create output

See: references/templates.md#step-0-configuration-loading-output for complete format

---

Step 1: Build Forward Traceability Matrix (AC → Implementation)

Purpose: Map each acceptance criterion to its implementation evidence

Actions:

1. For each acceptance criterion:

   • Extract AC from task specification
   • Example: "AC-1: User can sign up with email and password"

2. Search implementation files for evidence:

   • Read each file from Implementation Record
   • Search for relevant code implementing the AC
   • Record file paths, line ranges, function/class names
   • Extract code snippets as evidence (5-10 lines context)

3. Classify implementation status:

   • ✅ Implemented: Clear evidence found in code
   • ⚠️ Partial: Some evidence but incomplete (e.g., validation missing)
   • ❌ Not Implemented: No evidence found
   • ❓ Unclear: Code exists but unclear if it satisfies AC

4. Record evidence: File paths, line ranges, function names, code snippets (5-10 lines) for each AC

5. Calculate implementation coverage:

   Implementation Coverage = (Implemented + 0.5 × Partial) / Total AC × 100%
   

Output: Forward traceability complete, AC counts by status, implementation coverage %

Halt If: Cannot read implementation files, >50% ACs unclear

See: references/templates.md#step-1-forward-traceability-output for complete format and examples

---

Step 2: Build Backward Traceability Matrix (Tests → AC)

Purpose: Map each test to the acceptance criteria it validates

Actions:

1. Identify test files:

   • From test-design assessment (if available)
   • From Implementation Record (test files created)
   • From convention: **/*.test.ts, **/*.spec.ts, **/__tests__/*

2. For each test file, extract test cases:

   • Read test file
   • Extract test names from it(), test(), describe() blocks
   • Extract test scenarios (Given-When-Then if present)

   Extract test names from it(), test(), describe() blocks

3. Map tests to acceptance criteria:

   • Analyze test name and assertions
   • Determine which AC(s) the test validates
   • A single test can validate multiple ACs
   • An AC typically has multiple tests (happy path, edge cases, errors)

   Map tests to ACs (analyze test name + assertions, single test can validate multiple ACs)

4. Classify test coverage:

   • ✅ Tested: AC has at least one test validating it
   • ⚠️ Partial: AC has tests but not all scenarios covered (e.g., only happy path)
   • ❌ Not Tested: AC has no tests
   • 🔄 Indirect: AC tested indirectly through E2E or other tests

5. Calculate test coverage:

   Test Coverage = (Tested + 0.5 × Partial) / Total AC × 100%
   

Output: Backward traceability complete, tested AC counts, total tests, test coverage %

Halt If: None (proceed even if no tests, will generate gaps)

See: references/templates.md#step-2-backward-traceability-output for complete format

---

Step 3: Identify Coverage Gaps

Purpose: Identify and classify gaps in implementation and test coverage with severity ratings

Actions:

1. Identify implementation gaps:

   • ACs with status: Not Implemented, Partial, or Unclear
   • Document missing functionality
   • Estimate impact and effort

   Document missing functionality, estimate impact and effort

2. Identify test gaps:

   • ACs with test coverage: Not Tested or Partial
   • Document missing test scenarios
   • Identify missing edge cases, error cases, security tests

   Document missing test scenarios, identify edge cases/error cases

3. Classify gap severity: Use risk profile (if available) to inform severity:

   • CRITICAL (Score 9):

     • Security requirement not implemented or tested
     • Data integrity requirement missing
     • Core functionality not implemented
     • High-risk area (from risk profile) not tested

   • HIGH (Score 6-8):

     • Important requirement not implemented
     • Security test missing (but implementation exists)
     • Performance requirement not validated
     • P0 test missing

   • MEDIUM (Score 3-5):

     • Minor requirement not implemented
     • Edge case test missing
     • P1 test missing
     • Partial implementation without full test coverage

   • LOW (Score 1-2):

     • Nice-to-have requirement missing
     • P2 test missing
     • Documentation-only gap

4. Cross-reference with risk profile (if available):

   • Gaps in high-risk areas → Increase severity
   • Gaps with existing mitigation → Decrease severity
   • Gaps without test coverage for high-risk area → CRITICAL

5. Calculate gap metrics:

   Total Gaps = Implementation Gaps + Test Gaps
   Critical Gaps = Gaps with severity CRITICAL
   High Gaps = Gaps with severity HIGH
   Medium Gaps = Gaps with severity MEDIUM
   Low Gaps = Gaps with severity LOW
   
   Gap Coverage = (Total AC - Total Gaps) / Total AC × 100%
   

Output:

⚠ Coverage gaps identified
⚠ Total Gaps: {count}
⚠ Critical: {count} (Security/core functionality issues)
⚠ High: {count} (Important requirements missing)
⚠ Medium: {count} (Minor gaps, edge cases)
⚠ Low: {count} (Nice-to-have items)
⚠ Gap Coverage: {percentage}%

Halt Conditions:

• More than 50% implementation gaps (incomplete implementation, not ready for traceability)

Reference: See gap-analysis.md for gap classification and severity assessment

---

Step 4: Create Traceability Matrix

Purpose: Build comprehensive bidirectional traceability matrix combining all data

Actions:

1. Build full traceability matrix (table format):

   | AC | Requirement | Implementation | Tests | Gaps | Status |
   |----|-------------|----------------|-------|------|--------|
   | AC-1 | User can sign up with email and password | ✅ signup.ts:15-42 | ✅ 3 tests (P0) | None | ✅ Complete |
   | AC-2 | Password must be at least 8 characters | ✅ validators/auth.ts:23 | ⚠️ 1 test (missing edge cases) | GAP-2 (MEDIUM) | ⚠️ Partial |
   | AC-3 | Email must be validated | ✅ signup.ts:40, email.ts:12 | ✅ 2 tests (P1) | None | ✅ Complete |
   | AC-4 | Rate-limit login attempts | ❌ Not implemented | ❌ No tests | GAP-1 (HIGH) | ❌ Incomplete |
   

2. Generate detailed entries for each AC:

   ## AC-1: User can sign up with email and password
   
   **Implementation Status:** ✅ Implemented
   
   **Implementation Evidence:**
   - **File:** src/routes/auth/signup.ts:15-42
   - **Function:** handleSignup()
   - **Description:** Implements signup endpoint accepting email/password,
                      hashing password, creating user, sending verification email
   - **Code Snippet:** [5-10 lines showing implementation]
   
   **Test Coverage:** ✅ Tested
   
   **Test Evidence:**
   1. **Test:** "should create user with valid email and password"
      - **File:** src/routes/auth/__tests__/signup.test.ts:12-24
      - **Type:** Integration, Priority: P0
      - **Scenario:** Given valid inputs, When signup, Then user created
   
   2. **Test:** "should return 400 for invalid email format"
      - **File:** src/routes/auth/__tests__/signup.test.ts:26-35
      - **Type:** Integration, Priority: P0
      - **Scenario:** Given invalid email, When signup, Then 400 error
   
   **Coverage Status:** ✅ Complete
   - Implementation: ✅ Complete
   - Tests: ✅ Complete (3 tests covering happy path, validation, errors)
   - Gaps: None
   

3. Generate gap details: Document each gap with severity, impact, required action, effort, priority

4. Calculate overall traceability score:

   Traceability Score = (
     (Implementation Coverage × 0.5) +
     (Test Coverage × 0.4) +
     (Gap Coverage × 0.1)
   )
   
   Example:
   - Implementation Coverage: 85%
   - Test Coverage: 80%
   - Gap Coverage: 90% (10% gaps)
   
   Traceability Score = (85 × 0.5) + (80 × 0.4) + (90 × 0.1)
                      = 42.5 + 32 + 9
                      = 83.5%
   

Output: Matrix complete with entry counts, traceability score

Halt If: None

See: references/templates.md#complete-traceability-matrix-example for matrix format

---

Step 5: Generate Recommendations

Purpose: Provide actionable recommendations for closing gaps and improving traceability

Actions:

1. Prioritize gaps: Sort by:

   1. Severity (CRITICAL → HIGH → MEDIUM → LOW)
   2. Priority (P0 → P1 → P2)
   3. Effort (Small → Medium → Large)

2. Generate action plan: Prioritized actions (P0/P1/P2) with impact, effort, required actions, tests

3. Quality gate impact assessment: Determine status (PASS/CONCERNS/FAIL), provide reasoning, list actions to achieve PASS with effort estimates

4. Best practices: Future task guidance (TDD, reference AC IDs, update traceability), current task guidance (close P0 gaps, document waivers, re-run after fixes)

Output: Recommendations with P0/P1/P2 counts, effort estimates, quality gate prediction

Halt If: None

See: references/templates.md for recommendation formats and action plans

---

Step 6: Generate Traceability Report and Present Summary

Purpose: Create comprehensive traceability report and present concise summary to user

Actions:

1. Load template (if exists):

   • Read .claude/templates/trace-requirements.md
   • Use default structure if template missing

2. Populate template variables:

   • Metadata: task ID, title, date, assessor
   • Metrics: implementation coverage, test coverage, traceability score
   • Counts: total AC, total gaps, critical/high/medium/low gaps
   • Data: traceability matrix, detailed entries, gap details, recommendations

3. Generate file path:

   • Format: .claude/quality/assessments/{taskId}-trace-{YYYYMMDD}.md
   • Example: .claude/quality/assessments/task-006-trace-20251029.md
   • Create directory if needed

4. Write traceability report:

   • Complete report with all sections
   • Validate all template variables replaced
   • No placeholder text remaining

5. Present concise summary: Task metadata, coverage metrics (implementation/test/gap/traceability score), gap breakdown by severity, quality gate impact + reasoning, actions to achieve PASS with estimates, report path, next steps

Output: Report generated at output path, summary presented

Halt If: File write fails

See: references/templates.md#step-4-complete-summary-format for full summary output

---

Integration with Other Skills

Integration with risk-profile

Input: Risk scores for high-risk areas | Usage: Gaps in high-risk areas → increase severity (e.g., HIGH → CRITICAL), missing tests for high-risk → CRITICAL

Integration with test-design

Input: Test scenarios with priorities (P0/P1/P2), AC-to-test mappings | Usage: Validate test-to-AC mappings, identify missing test scenarios, use test priorities for gap severity

Integration with quality-gate

Output to quality-gate:

• Traceability score (contributes to gate decision)
• Coverage gaps (may block gate if critical)
• Action items for closing gaps
• Evidence for requirements traceability dimension

How quality-gate uses it:

Quality Gate Decision:
1. Check traceability score:
   - Score ≥95% → PASS
   - Score 80-94% → CONCERNS
   - Score <80% → FAIL

2. Check critical gaps:
   - 0 critical gaps → continue evaluation
   - 1+ critical gaps → CONCERNS (or FAIL if security)

3. Check overall coverage:
   - Implementation ≥90% AND Test ≥85% → PASS
   - Implementation ≥80% OR Test ≥70% → CONCERNS
   - Implementation <80% OR Test <70% → FAIL

Best Practices

1. Reference AC IDs in Code:

   // Implements AC-1: User signup with email and password
   export async function handleSignup(req: Request, res: Response) {
     // ...
   }
   

2. Reference AC IDs in Commits:

   git commit -m "feat: implement user signup (AC-1, AC-2, AC-3)"
   

3. Reference AC IDs in Test Names:

   it('should satisfy AC-1: user can sign up with email and password', async () => {
     // ...
   });
   

4. Run Before Code Review:

   • Check traceability before marking task as "Review"
   • Close gaps before requesting review
   • Re-run trace-requirements after closing gaps

5. Use for Audit Trail:

   • Demonstrate requirements → implementation → test chain
   • Show evidence for compliance
   • Cross-reference with risk profile for risk coverage

Configuration

In .claude/config.yaml

quality:
  # Quality assessment location
  assessmentLocation: ".claude/quality/assessments"

  # Risk score threshold for gap severity amplification
  riskScoreThreshold: 6  # Gaps in areas with risk ≥6 get higher severity

  # Traceability thresholds
  traceability:
    implementationCoverage: 90    # Minimum implementation coverage
    testCoverage: 85               # Minimum test coverage
    traceabilityScore: 80          # Minimum overall traceability score

Template File

.claude/templates/trace-requirements.md - Template for traceability report output (optional)

---

Version: 2.0 (Refactored for skill-creator compliance and Minimal V2 architecture) Category: Quality Depends On: risk-profile (optional, enhances gap severity), test-design (optional, enhances test mapping) Used By: quality-gate (uses traceability score and gaps for gate decision)