How to Run Test Design with TEA

Use TEA’s test-design skill to plan tests, rank risks, and define NFR evidence requirements.

When to Use This

System-level (Phase 3):

After architecture is complete
Before implementation-readiness gate
To validate architecture testability
To define NFR thresholds, unknowns, and planned evidence before implementation

Epic-level (Phase 4):

At the start of each epic
Before implementing stories in the epic
To identify epic-specific testing needs
To refine NFR validation when the epic has security, performance, reliability, scalability, compliance, or maintainability requirements

Prerequisites

For system-level: Architecture document complete
For epic-level: Epic defined with stories

Steps

1. Run the Test Design Skill

Claude Code / Cursor / Windsurf: /bmad-tea-test-design
Codex: $bmad-tea-test-design
Inside a /bmad-tea chat: TD

Full invocation rules: Invoking a TEA Skill.

2. Specify the Mode

TEA will ask if you want:

System-level: For architecture testability review and NFR planning (Phase 3)
Epic-level: For epic-specific test and NFR planning (Phase 4)

3. Provide Context

For system-level:

Point to your architecture document
Reference any ADRs (Architecture Decision Records)
Include PRD NFRs, SLO/SLA targets, compliance requirements, and known monitoring needs

For epic-level:

Specify which epic you’re planning
Reference the epic file with stories
Mention any NFR-heavy scenarios or inherited system-level NFR plans

4. Review the Output

TEA generates test design document(s) based on mode.

Before it finishes, TEA edits the documents for review. Where your sources state them, it names who acts, what they do, under which condition and with which expected result; a missing detail stays marked as unknown. It removes filler and promotional wording. Risk IDs, scores, priorities, test levels, thresholds, literal test data and stated unknowns stay exactly as planned, and a planned test never reads as one that already passed. TEA validates the saved documents and the handoff after that last edit. Validate mode reports wording findings without changing your files, and Edit mode changes only the text you ask it to change.

Interrupting and Resuming a Run

Each run saves its progress to its own checkpoint under {test_artifacts}/test-design/:

Run	Checkpoint
System-level	`test-design-progress-system.md`
Epic-level	`test-design-progress-epic-{N}.md`

The skill resolves that name in its first step, from the mode and the epic you named. Interrupting a run for one epic and then running test design for another epic leaves the first epic’s checkpoint untouched, so you can come back to it.

Pick [R] Resume to continue. Name the scope you want (for example “resume epic 3”) when checkpoints exist for more than one run; without a scope TEA lists the candidates and asks. TEA refuses to resume a checkpoint that belongs to a different run.

Checkpoints written by earlier TEA versions sit at the root of {test_artifacts}, under the old fixed name test-design-progress.md or a scoped test-design-progress-{run_key}.md. Resume picks those up too while they are still in progress; a completed one stays where it is. It asks you to confirm which run a fixed-name checkpoint belongs to and migrates it to its scoped name in test-design/, and it moves a scoped checkpoint into test-design/ unchanged. It never writes over a checkpoint that test-design/ already holds for the same run.

A headless run never asks. It starts an interrupted run of the same scope over, and an epic-level run whose epic it cannot resolve halts with a message naming the candidate epics.

What You Get

Every test design document lands in {test_artifacts}/test-design/. The system-level documents and the handoff exist once per project; each epic gets its own document. See Output Layout for how every TEA skill names and places its files.

System-level outputs:

System-level mode writes three files:

test-design-architecture.md: blockers, scored risks, testability gaps, NFR thresholds, and mitigation plans for architecture and development teams.
test-design-qa.md: P0-P3 scenarios, planned NFR validation, evidence artifacts, and Sprint 0 setup for QA.
{project_name}-handoff.md: P0/P1 risks, quality gates and a risk-to-story map that BMad’s epic and story creation reads.

test-design defines the thresholds and evidence that nfr-assess audits after implementation.

Epic-level output:

test-design-epic-N.md (combined risk assessment + test plan)

Risk assessment for the epic
Test priorities (P0-P3)
Coverage plan
NFR planning when NFRs are in scope
Regression hotspots (for brownfield)
Integration risks
Mitigation strategies

Test Design for Different Tracks

Track	Phase 3 Focus	Phase 4 Focus
Greenfield	System-level testability + NFR planning	Per-epic risk assessment and test plan
Brownfield	System-level + existing test baseline	Regression hotspots, integration/NFR risks
Enterprise	Compliance-aware testability + NFR evidence plan	Security/performance/compliance focus

Examples

System-level documents cross-reference each other:

Architecture doc: “ASR-1: OAuth 2.1 required (see QA doc for 12 test scenarios)”
QA doc: “OAuth tests: 12 P0 scenarios (see Architecture doc R-001 for risk details)”
Keep risk details in the architecture document and test scenarios in the QA document

Tips

Run system-level right after architecture: Early testability review
Shift NFRs left: Define thresholds and planned evidence before implementation
Run epic-level at the start of each epic: Targeted test planning
Update if ADRs change: Keep test design aligned
Use output to guide other skills: Feeds into Automate red and expand modes
Use nfr-assess later: Audit evidence after tests, scans, metrics, or logs exist
Architecture teams review Architecture doc: Focus on blockers and mitigation plans
QA teams use QA doc as implementation guide: Follow test scenarios and Sprint 0 checklist

Next Steps

After test design:

Setup Test Framework: If not already configured
Implementation Readiness: System-level feeds into gate check
Story Implementation: Epic-level guides testing during dev
NFR Evidence Audit: Run nfr-assess after implementation evidence exists