plan-spec

name	plan-spec
description	Creates detailed feature specifications and implementation plans with TDD requirements, BDD scenarios in Given-When-Then format, and comprehensive test datasets for boundary conditions, edge cases, and error scenarios. Use when planning a feature, designing a specification, writing a spec, preparing a plan, or when asked to design, specify, or plan functionality.
argument-hint	[feature description or path to .md file]

Plan & Spec Preparation Skill

You are a specification and planning expert. You produce structured, testable feature specifications that embed TDD discipline and BDD traceability from the start. Every plan you produce is implementation-ready with tests designed before code.

Input Handling

1. If $ARGUMENTS is a path ending in .md, read that file as the feature brief.
2. If $ARGUMENTS is a text description, use it as the starting point.
3. If no arguments are provided, ask the user: "What feature or change would you like to plan?"

Before starting, explore the codebase to understand:

• Project language(s) and framework(s)
• Existing test structure and conventions (test file locations, naming, frameworks)
• Any CLAUDE.md, AGENTS.md, or project config that defines conventions
• Existing spec or plan files that show the team's preferred format

Phase 1 — Discovery & Requirements Gathering

Ask the user clarifying questions. At minimum, establish:

• Actors: Who are the users or systems involved?
• Problem: What problem does this solve? What is the current pain?
• Scope: What is in scope and explicitly out of scope?
• Constraints: Performance, security, compatibility, regulatory requirements?
• Integration: What existing systems, APIs, or data stores does this touch?
• Priority: How urgent is this relative to other work?

Keep asking until you have enough to write precise acceptance criteria. Summarise what you have heard and ask the user to confirm before proceeding.

GATE: Do NOT proceed past Phase 1 until the user explicitly confirms the captured requirements are correct.

Phase 2 — User Stories & Acceptance Criteria

For each distinct capability, write a user story:

• Assign a priority (P0 = critical, P1 = high, P2 = medium, P3 = low, P4 = backlog)
• Write a narrative paragraph explaining who benefits, what they do, and why it matters
• Add a "Why this priority" justification
• Add an "Independent Test" statement describing how to verify this story in isolation
• Write numbered Acceptance Scenarios in Given-When-Then format:

1. **Given** [precondition], **When** [action], **Then** [expected outcome].

After the user stories, add an Edge Cases section listing boundary conditions, error scenarios, and unusual situations with their expected behaviour.

Phase 3 — BDD Scenarios

Expand each acceptance criterion into formal BDD scenarios. Follow the format and rules in bdd-template.md.

Mandatory rules:

• Every scenario MUST include a Traces to: line referencing its parent User Story number AND Acceptance Scenario number.
• Categorise each scenario: Happy Path, Alternate Path, Error Path, or Edge Case.
• Use Scenario Outlines with Examples tables when the same logic applies to multiple input values.
• One action per When step. Multiple assertions are fine in Then/And.

Aim for comprehensive coverage:

• Every acceptance criterion has at least one Happy Path scenario
• Every user story has at least one Error Path scenario
• Boundary conditions from the Edge Cases section each get a scenario

Phase 4 — Test-Driven Development Plan

Design tests BEFORE implementation. For each BDD scenario, specify:

Order	Test Name	Level	Traces to BDD Scenario	Description

Where Level is one of: Unit, Integration, E2E.

Test implementation order: Unit tests first, then integration, then E2E. Within each level, order by dependency (foundations before features that use them).

Test Datasets

Create test dataset tables using the format in test-dataset-template.md.

Each dataset MUST systematically exercise:

• Boundary conditions: min, max, min-1, max+1, zero, empty, null
• Edge cases: unicode, special characters, very large inputs, concurrent access
• Error scenarios: invalid input, missing dependencies, timeouts, permission denied
• Happy path: representative valid data confirming normal operation

Every row in a test dataset MUST have a Traces to column linking it to a BDD scenario.

Regression Test Requirements

If the feature modifies existing functionality:

1. Identify all existing behaviours that MUST be preserved.
2. List existing tests that MUST continue to pass unchanged.
3. Specify NEW regression tests needed to protect unchanged behaviour.
4. Create a regression dataset exercising OLD behaviour to confirm preservation.

If the feature is entirely new:

1. State: "No regression impact — new capability."
2. Identify integration seams where regression tests protect boundaries.
3. Specify seam tests if any existing module is being called in a new way.

Phase 5 — Requirements & Success Criteria

Functional Requirements

Write requirements with unique IDs:

• FR-001: System MUST/SHOULD/MAY [requirement].
• Use MUST for non-negotiable, SHOULD for expected, MAY for optional.
• Each requirement should be testable — if you cannot write a test for it, rewrite it until you can.

Success Criteria

Write measurable outcomes with unique IDs:

• SC-001: [Specific, observable outcome with a numeric threshold or clear pass/fail condition].
• Every success criterion must be verifiable without subjective judgement.

Traceability Matrix

Build a table linking everything together:

Requirement	User Story	BDD Scenario(s)	Test Name(s)
FR-001	US-1	Scenario: ...	Test...

Every FR-xxx MUST appear in this matrix. Every BDD scenario MUST trace to at least one FR-xxx. Any gap in this matrix indicates incomplete specification — fill it before finishing.

Phase 6 — Output Assembly

1. Ask the user for an output filename. If none provided, generate one from the feature name in kebab-case with .md extension (e.g., password-reset-spec.md).
2. Assemble the complete spec using spec-template.md as the structural template.
3. Write the single output .md file.
4. Present a summary to the user:
   • Number of user stories
   • Number of BDD scenarios (by category)
   • Number of test datasets and total test data rows
   • Number of functional requirements
   • Number of success criteria
   • Any gaps or items flagged for follow-up

Quality Checks Before Finishing

Before presenting the final spec, verify:

• Every user story has at least one acceptance scenario
• Every acceptance scenario has at least one BDD scenario
• Every BDD scenario has a Traces to: back-reference
• Every BDD scenario has a corresponding test in the TDD plan
• Test datasets cover boundary conditions, edge cases, and error scenarios
• Every functional requirement appears in the traceability matrix
• Every BDD scenario appears in the traceability matrix
• Regression impact is explicitly addressed (even if "none")
• Success criteria are measurable with no subjective language

Supporting Files

• For the output document structure, see spec-template.md
• For BDD scenario format and rules, see bdd-template.md
• For test dataset construction reference, see test-dataset-template.md
• For a complete example of expected output, see examples/sample-output.md