bmad-testarch-trace

Generate requirements-to-tests traceability matrices and quality gate decisions for release readiness.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill bmad-testarch-trace-watchthelight
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-testarch-trace
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/bmad-testarch-trace
Command: npx skills add https://github.com/watchthelight/shatterfish --skill bmad-testarch-trace-watchthelight

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often cannot tell which requirements are actually covered by tests or whether a build is safe to release. This Skill maps requirements to tests, classifies coverage gaps by priority, and produces a deterministic PASS/CONCERNS/FAIL/WAIVED gate decision backed by evidence. ## Core Features & Use Cases - Traceability Matrix Generation: Maps acceptance criteria, OpenAPI endpoints, or inferred user journeys to discovered tests across E2E, API, component, unit, and live-verification levels, with FULL/PARTIAL/NONE coverage classification. - Gap Analysis & Quality Audit: Detects uncovered P0-P3 criteria, endpoint and auth negative-path gaps, duplicate coverage, and test quality issues such as hard waits or missing assertions. - Quality Gate Decision: Applies deterministic thresholds to test results, coverage, NFR evidence, and flakiness data, emitting traceability-matrix.md, e2e-trace-summary.json, and gate-decision.json for CI/CD enforcement. - Use Case: Before merging a story, run the workflow to discover that a P0 password-reset criterion has no E2E test, receive a FAIL gate decision, and get concrete recommended test IDs to add. ## Quick Start Ask the agent to create a traceability matrix and quality gate decision for the current story or release.

Frequently Asked Questions about bmad-testarch-trace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a requirements traceability matrix for my tests?

Run the workflow in Create mode and it resolves a coverage oracle from acceptance criteria, specs, or source code, discovers tests by ID and level, then writes traceability-matrix.md mapping every criterion to its covering tests with coverage status.

What is a quality gate decision in CI/CD testing?

A quality gate decision is a PASS, CONCERNS, FAIL, or WAIVED verdict computed from deterministic rules over test pass rates, P0-P3 coverage, security issues, and flakiness. The workflow emits gate-decision.json so pipelines can block or allow deployments automatically.

Can traceability work without formal requirements documents?

Yes. When no formal oracle exists, the workflow can resolve OpenAPI or GraphQL contracts, follow external pointers to trackers like Jira, or infer synthetic user journeys from routes, forms, and auth flows in the source tree, recording confidence for each mode.

Does the traceability workflow generate missing tests?

No. It only identifies coverage gaps and recommends specific test IDs, levels, and Given-When-Then scenarios for each gap. Test creation is delegated to companion workflows such as bmad-testarch-atdd or bmad-testarch-automate.

How are live verification results counted as coverage?

A live result counts only when it has a unique ID, a recognized requirement_id, status pass, and a source_sha matching the commit under trace. Stale, failed, blocked, or unverifiable records are reported as blockers and never counted as coverage.