---
name: quality-test-plan
description: "Use when implementation needs a comprehensive testing strategy — triggered by phrases like 'make a test plan', 'design the test matrix', 'coverage plan', 'what tests do we need', 'plan the integration tests', 'test strategy for this feature', 'lay out the full test pass'. Produces a structured plan covering unit, integration, E2E, smoke, load, and contract tests with explicit traceability to architecture artifacts and risk classification. Skip when the user wants to write OR run tests directly — this skill produces the plan, not the tests themselves (use build-tdd for writing, quality-test-execution for running)."
---

# Test Plan

## Overview

Generate a comprehensive test plan covering every test type needed for the feature. Each test maps to a requirement for full traceability.

**Core principle:** Every acceptance criterion needs a test that traces back to it.

**Announce at start:** "I'm using the quality-test-plan skill to generate the test strategy."

## When to Use

- After implementation is complete (all TDD cycles done)
- Before running the full test execution phase
- During `/feature` and `/greenfield` commands at the test planning phase

**Not for:**
- Writing tests during implementation (that is build-tdd)
- Executing tests (that is quality-test-execution)

## When to load references

- **`references/test-type-guide.md`** — purpose, structure, examples, and key rules for each of the six test types (unit, integration, E2E, smoke, load, contract). Load when generating any test-type section.

## Prerequisites

Before generating a test plan, the following must exist:

1. **Requirements** -- `.forge/work/{type}/{name}/requirements.md` (for acceptance criteria mapping)
2. **Architecture artifacts** -- `.forge/work/{type}/{name}/architecture/` (for API contracts, DB schema)
3. **Implementation code** -- The actual code to test (from build-tdd phase)
4. **Existing TDD tests** -- Unit tests written during build-tdd already exist

If any are missing, stop and request them. Do not generate a test plan against imagined requirements.

## The Test Plan Process

### Step 1: Read Input Artifacts

Read and understand:

```
1. requirements.md
   - All requirements and their acceptance criteria
   - Priority levels (must/should/could/won't)
   - User stories and their scenarios

2. architecture/api-contract.md
   - Every endpoint: method, path, request/response shapes
   - Error codes and error response format
   - Authentication requirements per endpoint

3. architecture/db-schema.md
   - Tables, columns, types, constraints
   - Indexes, unique constraints, foreign keys
   - Cascade behavior

4. Implementation code
   - All new/modified source files
   - All existing TDD tests
   - Entry points, routes, handlers, services

5. Decision log
   - Architecture decisions that affect test strategy
   - Known limitations or accepted risks
```

### Step 1.5: Codex Mode Check

Now that input artifacts are read, run the Codex consent flow from `protocols/codex.md`. The selected mode applies for the rest of this skill's invocation.

- **Takeover:** Dispatch Codex with the artifacts to generate the full test plan. Claude reviews coverage and gap analysis.
- **Verify** or **Skip / Codex unavailable:** Proceed with the steps below. Step 4.5 will dispatch Codex to review Claude's test plan (Verify only).

### Step 2: Map Requirements to Tests

Create a traceability matrix:

```markdown
| Requirement | Acceptance Criteria | Test Type | Test ID |
|-------------|-------------------|-----------|---------|
| REQ-001: User registration | AC-001.1: Email must be valid | Unit | UT-001 |
| REQ-001: User registration | AC-001.2: Password min 8 chars | Unit | UT-002 |
| REQ-001: User registration | AC-001.3: Duplicate email rejected | Integration | IT-001 |
| REQ-001: User registration | AC-001.4: Success creates user | Integration | IT-002 |
| REQ-001: User registration | Full flow | E2E | E2E-001 |
| REQ-002: User login | AC-002.1: Valid credentials succeed | Integration | IT-003 |
| REQ-002: User login | AC-002.2: Invalid credentials fail | Integration | IT-004 |
| REQ-002: User login | Full flow | E2E | E2E-002 |
```

**Rule:** Every acceptance criterion MUST have at least one test. If a criterion has no test, the plan is incomplete.

### Step 2.3: Map Oracles to Tests

If `aiwiki/oracles/` contains oracle pages for slices in this work item, every in-scope oracle MUST appear in the traceability matrix with at least one mapped test. Oracles are the prototype-derived behavioral contract from Phase 5 (harden); production code is not "tested" if oracles are unverified. This is the load-bearing closure of the mock-pass / real-break wiring gap — the failure mode where unit tests pass against mocks but real integration breaks at the wiring boundary.

For each `aiwiki/oracles/{slug}.md` whose `prototype_path` is within this work item's scope (typically `pocs/{name}-prototype/`):

```markdown
| Oracle | Type | Setup → Trigger → Assertions cite | Mapped tests |
|---|---|---|---|
| `auth-login-success` | interaction | `pocs/myapp-prototype/src/auth/Login.tsx:42` | IT-003, E2E-001 |
| `dashboard-renders-empty-state` | render | `pocs/myapp-prototype/src/Dashboard.tsx:18` | IT-005 |
| `checkout-applies-discount-code` | golden-trace | `pocs/myapp-prototype/src/checkout/apply.ts:67` | IT-012, CONTRACT-004 |
```

**Rule:** Every in-scope oracle MUST have at least one test that exercises its `Setup → Trigger → Assertions`. Unmapped oracles fail this step — either add tests to cover them, or surface to the user that harden's oracle capture missed a slice.

The mapped test SHOULD be an integration or E2E test (oracles describe boundary behavior; unit tests with mocks at the boundary don't satisfy them). A pure-unit test mapping is acceptable only when the oracle is itself a unit-level invariant (rare).

**Skip condition:** If `phase_plan.codify: skipped` for this work item or `aiwiki/oracles/` is empty for the work scope, record "No oracles in scope" in the plan and proceed. The check is non-blocking when oracle capture wasn't part of the lifecycle (e.g. trivial bugfix routed past harden).

### Step 2.5: Map User Journeys to E2E Scenarios

If the requirements document includes a User Journeys section, create a business flow traceability table. Every journey MUST map to an E2E test scenario. Gaps are flagged before test execution.

```markdown
## Business Flow Traceability

| Journey | Priority | E2E Scenario | Steps | Requirements Covered | Status |
|---|---|---|---|---|---|
| {journey name} | Must | E2E-001 | {N} steps | {FR-xxx, FR-yyy} | COVERED |
| {journey name} | Must | E2E-002 | {N} steps | {FR-xxx, FR-yyy} | COVERED |
| {journey name} | Should | — | {N} steps | {FR-xxx} | GAP |
```

**Rule:** Every "Must" priority journey MUST have a corresponding E2E scenario. "Should" journeys without E2E scenarios are flagged as gaps but do not block.

### Step 3: Generate Test Sections

Before generating output, check this skill's `templates/` directory and use the provided templates as the output format for each test type.

Generate a plan section for each test type below. For each, load **`references/test-type-guide.md`** to see the purpose, structure, illustrative examples, and key rules:

| Test type | Purpose | Output template |
|---|---|---|
| **Unit** | Individual functions/methods in isolation | `templates/unit-test-plan.md` |
| **Integration** | Component interactions, API endpoints, DB ops | `templates/integration-test-plan.md` |
| **E2E** | Full user flows through the UI (Playwright) | `templates/e2e-test-plan.md` |
| **Smoke** | Critical-path sanity check post-deploy | `templates/smoke-test-plan.md` |
| **Load/Stress** | Performance under realistic and peak load | `templates/load-test-plan.md` |
| **API Contract** | Frontend/backend agree on API shapes | (no separate output template — follow the example in `references/test-type-guide.md`) |

Coverage targets, key rules, traceability requirements, and per-type examples all live in `references/test-type-guide.md`.

### Step 4: Coverage Gap Analysis

After generating all test sections, verify completeness:

```markdown
### Coverage Gap Analysis

| Requirement | Unit | Integration | E2E | Smoke | Contract | Status |
|-------------|------|-------------|-----|-------|----------|--------|
| REQ-001 | 3 tests | 2 tests | 1 flow | - | 1 test | COVERED |
| REQ-002 | 2 tests | 2 tests | 1 flow | 1 test | 1 test | COVERED |
| REQ-003 | 1 test | 0 tests | 0 flows | - | - | GAP |

GAPS FOUND: 1
- REQ-003 has no integration or E2E tests. Must add before plan is complete.
```

**Rule:** No gaps allowed. Every requirement must have coverage at the appropriate test levels. If a gap exists, add the missing tests to the plan.

### Step 4.5: Codex Verify

After gap analysis, check the mode recorded at Step 1.5. If **Verify** was selected, dispatch Codex to review the test plan for missing scenarios, edge cases, mock-vs-real blind spots, and coverage gaps. Add missing scenarios if user approves. If **Takeover** was selected, skip this step (Codex already generated the plan). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.

### Step 5: Write the Test Plan Document

Output to `.forge/work/{type}/{name}/test-plan.md` with this structure:

```markdown
# Test Plan: {Feature Name}

## Metadata
- **Feature:** {name}
- **Date:** {date}
- **Requirements:** {link to requirements.md}
- **Architecture:** {link to architecture/}

## Traceability Matrix
[Full requirement-to-test mapping table]

## Unit Tests
[All unit test specifications]

## Integration Tests
[All integration test specifications]

## E2E Tests
[All E2E test specifications]

## Smoke Tests
[All smoke test specifications]

## Load/Stress Tests
[All load test specifications, if applicable]

## API Contract Tests
[All contract test specifications]

## Coverage Gap Analysis
[Completeness verification]

## Test Environment Requirements
- Database: {test database config}
- Services: {external services needed}
- Tools: {Playwright, k6, etc.}
- Data: {seed data requirements}
```

### Step 5.5: Critic Review of Test Plan

After writing the test plan, dispatch the **critic** subagent (Opus) to review the plan for completeness against requirements and API contracts. Provide the critic with the test plan, requirements document, and architecture artifacts.

If the critic identifies coverage gaps or missing scenarios, address them before presenting the plan to the user.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Skipping E2E for "simple" features | No feature is too simple. E2E catches integration issues. |
| Only testing happy paths | Every error code, every validation failure, every edge case. |
| No traceability | Every test must link to a requirement. No orphan tests. |
| Vague test descriptions | Specify exact inputs, exact expected outputs. |
| Missing error scenarios | For every success scenario, there is at least one error scenario. |
| No load test thresholds | "Should be fast" is not a threshold. Specify numbers. |
| Ignoring existing TDD tests | TDD tests are part of the plan. Include them in the traceability matrix. |
| Tests that depend on each other | Each test must be independent. No ordering requirements. |

## Red Flags

**Never:**
- Generate a test plan without reading requirements first
- Skip any test type without explicit project profile justification
- Leave gaps in the traceability matrix
- Use vague descriptions ("test that it works")
- Assume existing TDD tests cover everything
- Generate load tests for projects that do not need them (check project profile)

**Always:**
- Read requirements, architecture, and implementation before planning
- Map every acceptance criterion to at least one test
- Include both happy and error paths for every scenario
- Specify exact inputs and expected outputs
- Verify completeness with gap analysis
- Output to `.forge/work/{type}/{name}/test-plan.md`

## I/O Contract

| Field | Value |
|---|---|
| **Requires** | Implementation code (from `build-tdd`), architecture artifacts (`.forge/work/{type}/{name}/architecture/`), requirements (`.forge/work/{type}/{name}/requirements.md`), oracle pages (`aiwiki/oracles/*.md` from harden Step 2.5) when codify ran |
| **Produces** | `.forge/work/{type}/{name}/test-plan.md` |
| **Feeds into** | `quality-test-execution` (test plan drives execution) |
| **Updates manifest** | `artifacts.test-plan: test-plan.md` |

## Graphify Context

**Protocol:** `protocols/graphify.md` | **Guard:** Run the status check from the protocol before Step 1.

Graph data directly informs test prioritization — god nodes need the most integration tests, and community boundaries reveal integration gaps.

**How graph data maps to this skill:**
- **God nodes (highest-degree)** → components with most connections need the most integration tests
- **Community boundaries** → cross-community edges are integration test priorities
- **INFERRED edges** → relationships worth validating with contract tests

**CLI queries** (if graph exists and CLI available):
- `graphify query "what are the most connected components" --budget 1000 --graph graphify-out/graph.json` — identify integration test priorities

**Codex bridge:** Pass graph-informed test priorities to the Codex verify step below.

---

## Codex Integration
**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`

- **Verify:** Claude generates the test plan, Codex reviews for gaps.
- **Takeover:** Codex generates the test plan, Claude reviews coverage.

**When:** After Claude generates the test plan, before user approval.

**Context to pass:**
- Path to `test-plan.md`
- Path to `architecture/api-contract.md`
- Path to `requirements.md`

**What Codex reviews:**
- Missing test scenarios (edge cases, error paths, boundary conditions)
- Mock-vs-real blind spots (tests that mock away the thing they should test)
- Coverage gaps against requirements (must-haves without corresponding tests)

**Prompt focus:** "Review this test plan against the requirements and architecture. For each test scenario, assess: does this test the real behavior or just a mock? What edge cases are missing? What requirements have no corresponding test?"

**Presentation:** Codex findings merged into the test plan review. Missing scenarios added to the plan if user approves.

---

## Integration

**Called by:**
- `/feature` command (after implementation loop)
- `/greenfield` command (after implementation loop)

**Pairs with:**
- `build-tdd` (existing unit tests become part of the plan)
- `quality-test-execution` (executes every test in this plan)
- `plan-architecture` (API contracts and DB schema inform integration/contract tests)
- `discover-requirements` (acceptance criteria drive the traceability matrix)