writing-verification-plans

Writing Verification Plans

Overview

Help Claude write verification plans that validate a project works in real-world scenarios before completing tasks.

Core principle: Verification is not integration testing. It uses real systems, never mocks or fakes. A test environment is acceptable only if it's a fully running copy of the system being integrated with.

Announce at start: "I'm using the writing-verification-plans skill to create acceptance testing procedures."

When to Use This Skill

Use this skill when:

• Setting up a new project (called from setting-up-a-project skill)
• A project lacks a VERIFICATION_PLAN.md
• The developer asks for a verification plan
• Adding new features that require real-world validation

When NOT to use: Not for writing automated test suites — this skill produces manual/agent-executed acceptance procedures, not unit or integration tests.

Writing the Verification Plan

Ask the user about the real-world scenarios that need to be validated. For each scenario, gather:

1. What is being tested? The feature or capability to verify
2. What does success look like? Concrete, observable outcomes
3. What environment is needed? Real systems, test accounts, sample data
4. What could go wrong? Edge cases and failure modes to check

VERIFICATION_PLAN.md Format

# Verification Plan

**Verification runs automatically after completing any task. Do not wait for the developer to request it.**

## Prerequisites

[List everything needed before verification can run]
- Test environment setup instructions
- Required accounts or credentials
- Sample data or test fixtures
- External systems that must be running

## Scenarios

### Scenario 1: [Name]

**Context**: [What state the system should be in before starting]

**Steps**:
1. [Specific action Claude should take]
2. [Next action]
3. [Continue until complete]

**Success Criteria**:
- [ ] [Observable outcome that must be true]
- [ ] [Another required outcome]

**If Blocked**: [When to stop and ask developer for help]

[Add a section like Scenario 1 for each additional scenario]

## Verification Rules

- Never use mocks or fakes
- Test environments must be fully running copies of real systems
- If any success criterion fails, verification fails
- Ask developer for help if blocked, don't guess