test-plan

name	test-plan
description	Use when creating test plans from implementation and design documents. Provides test plan structure, test case tracking, and coverage guidelines.
allowed-tools	Read, Write, Glob, Grep

Test Plan Skill

This skill provides guidelines for creating and managing test plans from implementation and design documents.

When to Apply

Apply this skill when:

• Creating test plans from existing implementations
• Planning test coverage for features
• Breaking down test cases into parallelizable units
• Tracking test progress across sessions

Purpose

Test plans bridge the gap between implementation (what was built) and verification (does it work correctly). They provide:

• Clear test scenarios with expected behaviors
• Test case dependencies and execution order
• Coverage targets and completion criteria
• Progress tracking across test execution sessions

Divide & Conquer Strategy

CRITICAL: Due to context limitations, test plans MUST use a divide-and-conquer approach.

Analysis Phases

1. Discovery Phase: Identify modules to test (file listing, not content)
2. Module Analysis Phase: Analyze one module at a time
3. Test Design Phase: Design tests for analyzed module
4. Aggregation Phase: Combine into test plan

DO NOT

• Load all source files at once
• Analyze entire codebase in single pass
• Generate tests for multiple modules simultaneously

DO

• Focus on one module/area per agent invocation
• Use file patterns to identify scope first
• Analyze implementation only when designing specific tests

Plan Granularity

IMPORTANT: Test plans and impl-plans do NOT need 1:1 mapping.

Mapping	When to Use
1:N (one impl -> multiple test plans)	Large implementations need focused test plans
N:1 (multiple impls -> one test plan)	Related modules can share integration tests
1:1 (one impl -> one test plan)	Well-bounded features with clear test scope

Recommended granularity:

• Each test plan should be completable in 1-3 sessions
• Each test plan should have 3-15 test cases
• Maximize parallelizable test cases

File Size Limits

CRITICAL: Large test plan files cause Claude Code OOM errors.

Hard Limits

Metric	Limit	Reason
Line count	MAX 400 lines	Prevents memory issues
Test cases per plan	MAX 15	Keeps plans focused
Modules per plan	MAX 5	Enables focused testing

When to Split Plans

Split a test plan into multiple files when:

1. Line count exceeds 400 lines
2. More than 15 test cases
3. Multiple test types (unit, integration, e2e)
4. Multiple feature areas

Split Strategy

BEFORE: session-groups-tests.md (too large)

AFTER:
- session-groups-unit-tests.md (~200 lines)
- session-groups-integration-tests.md (~200 lines)
- session-groups-e2e-tests.md (~150 lines)

Output Location

IMPORTANT: All test plans MUST be stored under test-plans/.

test-plans/
├── README.md              # Index of all test plans
├── PROGRESS.json          # Test status tracking (single source of truth)
├── <feature>-unit.md      # Unit test plans
├── <feature>-integration.md # Integration test plans
└── <feature>-e2e.md       # End-to-end test plans

Test Plan Structure

Each test plan file MUST include:

1. Header Section

# <Feature Name> Test Plan

**Status**: Planning | Ready | In Progress | Completed
**Implementation Reference**: impl-plans/<file>.md
**Source Files**: src/<path>/*.ts
**Test Type**: Unit | Integration | E2E
**Created**: YYYY-MM-DD
**Last Updated**: YYYY-MM-DD

2. Implementation Reference

• Link to implementation plan or source files
• Summary of what is being tested
• Scope boundaries (what is NOT tested in this plan)

3. Test Environment

## Test Environment

**Runtime**: Bun test
**Mocks Required**: List of mock implementations needed
**Fixtures**: List of test fixtures needed
**Setup/Teardown**: Special requirements

4. Test Cases

Each test case MUST have:

### TEST-001: <Test Case Name>

**Status**: Not Started | In Progress | Passing | Failing | Skipped
**Priority**: Critical | High | Medium | Low
**Parallelizable**: Yes | No
**Dependencies**: None | TEST-XXX | other-plan:TEST-XXX

**Target**: `src/path/file.ts:functionName`

**Description**:
Brief description of what this test verifies.

**Scenarios**:
1. Happy path: <expected behavior>
2. Edge case: <expected behavior>
3. Error case: <expected behavior>

**Assertions**:
- [ ] Assertion 1
- [ ] Assertion 2

**Test Code Location**: `src/path/file.test.ts`

5. Test Status Table

## Test Status

| Test ID | Name | Status | Priority | Dependencies |
|---------|------|--------|----------|--------------|
| TEST-001 | Basic parsing | Not Started | High | None |
| TEST-002 | Error handling | Not Started | High | TEST-001 |
| TEST-003 | Edge cases | Not Started | Medium | TEST-001 |

6. Coverage Targets

## Coverage Targets

| Module | Current | Target | Status |
|--------|---------|--------|--------|
| src/sdk/queue/types.ts | 0% | 90% | Not Started |
| src/sdk/queue/manager.ts | 0% | 85% | Not Started |

7. Completion Criteria

## Completion Criteria

- [ ] All test cases implemented
- [ ] All tests passing
- [ ] Coverage targets met
- [ ] No flaky tests
- [ ] Documentation updated

8. Progress Log

## Progress Log

### Session: YYYY-MM-DD HH:MM
**Tests Completed**: TEST-001, TEST-002
**Tests In Progress**: TEST-003
**Blockers**: None
**Notes**: Discovered edge case requiring additional test

Test Case Definition Guidelines

Test ID Format

• Format: TEST-XXX where XXX is zero-padded (001, 002, etc.)
• IDs are unique within a plan
• Cross-plan references: <plan-name>:TEST-XXX

Dependency Specification

Same-plan dependency:

**Dependencies**: TEST-001
**Dependencies**: TEST-001, TEST-002

Cross-plan dependency:

**Dependencies**: session-groups-unit:TEST-001

No dependencies:

**Dependencies**: None

Parallelization Rules

Tests can be parallelized when:

1. No shared mutable state
2. No file system side effects
3. No network dependencies between tests
4. No order-dependent setup

Parallelizable: Yes - Test can run independently Parallelizable: No - Test depends on other tests or shared state

PROGRESS.json Integration

CRITICAL: After creating a test plan, update test-plans/PROGRESS.json.

PROGRESS.json Structure

{
  "lastUpdated": "2026-01-09T16:00:00Z",
  "summary": {
    "totalPlans": 10,
    "totalTests": 150,
    "passing": 0,
    "failing": 0,
    "notStarted": 150
  },
  "plans": {
    "feature-unit": {
      "status": "Ready",
      "testType": "Unit",
      "implRef": "impl-plans/feature.md",
      "tests": {
        "TEST-001": { "status": "Not Started", "priority": "High", "parallelizable": true, "deps": [] },
        "TEST-002": { "status": "Not Started", "priority": "High", "parallelizable": false, "deps": ["TEST-001"] }
      }
    }
  }
}

Status Values

Status	Meaning
Not Started	Test not yet implemented
In Progress	Test being written
Passing	Test implemented and passing
Failing	Test implemented but failing
Skipped	Test intentionally skipped

Priority Values

Priority	Meaning
Critical	Must pass for release
High	Should pass for release
Medium	Important but not blocking
Low	Nice to have

Test Type Guidelines

Unit Tests

• Test single functions/methods in isolation
• Mock all dependencies
• Fast execution (< 100ms per test)
• File naming: *.test.ts adjacent to source

Integration Tests

• Test multiple components together
• May use real dependencies
• Moderate execution time
• Test API contracts between modules

End-to-End Tests

• Test complete user flows
• Minimal mocking
• May require setup/teardown
• Test from external interface

Workflow Integration

Creating a Test Plan

1. Read the implementation or design document
2. Identify test boundaries and types
3. List test scenarios (happy path, edge cases, errors)
4. Define test cases with IDs and dependencies
5. Set coverage targets
6. Create plan file in test-plans/<feature>-<type>.md
7. Update PROGRESS.json with new plan and tests
8. Update test-plans/README.md with new plan entry

During Test Execution

1. Update test status in PROGRESS.json as tests are written
2. Add progress log entries per session
3. Note blockers and issues
4. Check off completion criteria

Completing a Test Plan

1. Verify all tests passing
2. Verify coverage targets met
3. Update plan status to "Completed"
4. Add final progress log entry

Quick Reference

Section	Required	Format
Header	Yes	Markdown metadata
Implementation Reference	Yes	Link + summary
Test Environment	Yes	Requirements list
Test Cases	Yes	Structured format with scenarios
Status Table	Yes	Simple table
Coverage Targets	Yes	Target percentages
Completion Criteria	Yes	Checklist
Progress Log	Yes	Session entries