Test plan

Skill: test-plan

When to Use

Use this skill before merging a feature branch, after completing implementation, or when you need a QA checklist. Invoke with /test-plan to generate from the current branch, /test-plan main...HEAD for a specific git range, or /test-plan execute to run an existing plan.

Use $ARGUMENTS to determine the mode:

• Empty or git range (default): Generate mode -create a test plan from code changes
• "execute" or a file path: Execute mode -run an existing test plan via Playwright

Generate Mode

Procedure

1. Identify changes. Detect the default branch (git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@', falling back to main if that fails). Run git diff <default-branch>...HEAD --stat to list changed files. If $ARGUMENTS contains a git range, use that instead.
2. Understand each change. Read each changed file to understand what was modified and why.
3. Create test scenarios. For each user-visible change, generate a test scenario:
   • Scenario name: What the user does (e.g., "Submit the contact form with valid data")
   • Steps: Numbered, specific enough for someone unfamiliar with the app
   • Expected result: What should happen after completing the steps
   • Edge cases: What could go wrong (empty fields, duplicate submissions, slow network, etc.)
4. Group by feature area. Organise scenarios under feature headings.
5. Write the plan. Save to docs/test-plans/YYYY-MM-DD-<branch-name>.md.

Output Format

## Test Plan: <branch name>
Generated: <date>

### <Feature Area>

#### Scenario: <name>
- [ ] Step 1: ...
- [ ] Step 2: ...
- [ ] Step 3: ...
- Expected: ...
- Edge cases: ...

Execute Mode

Procedure

1. Find the plan. If $ARGUMENTS is a file path, use it. If $ARGUMENTS is "execute", find the most recent test plan in docs/test-plans/. If none exists, tell the user to generate one first.
2. Read the plan. Parse each scenario and its steps.
3. Run each scenario. For each scenario, use Playwright MCP to:
   • Navigate to the relevant page
   • Follow the steps exactly as written
   • Use browser_snapshot to verify page state after each action
   • Verify the expected result
4. Record results. For each scenario, record one of:
   • PASS -all steps completed and expected result verified
   • FAIL -a step didn't produce the expected result (include browser_take_screenshot as evidence)
   • BLOCKED -couldn't reach the step (prerequisite failed, page unreachable, login required)
5. Update the plan. Append results to the test plan file:

### Execution Results - <date>

| Scenario | Result | Notes |
|---|---|---|
| <name> | PASS/FAIL/BLOCKED | <details> |

Rules

• Test scenarios describe what a user does, not what the code does. Write "Click the submit button and verify the success message appears" not "POST /api/form returns 200."
• Steps must be reproducible by someone who has never seen the codebase. No references to file names, function names, or implementation details.
• One scenario per user action. Don't combine "create an account" and "update profile" into one scenario.
• Include the unhappy path. For every form, test with empty fields, invalid data, and duplicate submissions. For every action, test what happens when it fails.
• In execute mode, follow steps literally. Do not improvise or skip steps. If a step is ambiguous, record it as BLOCKED with a note about what was unclear.
• Use browser_snapshot first to understand page structure before interacting. Use browser_take_screenshot to capture evidence of failures.
• Limit file reads to 15 files. If the diff touches more than 15 files, group by feature area and generate scenarios from the diff summary and the 15 most relevant files. Tell the user which files were skipped.