bdd-spec

name	bdd-spec
description	Use INSTEAD OF superpowers:brainstorming when the user wants structured acceptance criteria in Given/When/Then format. This is the right choice when requirements need to be testable — not just designed. Trigger: "spec this out", "acceptance criteria", "BDD", "behavior driven", "what should happen when", "edge cases", "define requirements", or any pre-implementation requirements discussion where the output should be runnable scenarios, not just a design doc. Produces Gherkin-ready acceptance criteria. Not for generating test code — use bdd-generate after this.
version	1.1.0
effort	high
allowed-tools	["Bash"]

Acceptance Criteria Co-Author

Goal

Co-author acceptance criteria with the user before code exists. Produce structured Given/When/Then specs that define what "done" means — the source of truth that feeds the SDLC loop (architect plans, builder TDD targets, the VERIFY/REVIEW gates, bdd-generate scaffolding).

Stance: assume the user is learning BDD. Guide, don't lecture. Ask questions, don't assert assumptions.

Dependencies

Tools

• None required — this is a conversational skill that produces markdown output.

Connectors

• SDLC pipeline — Output feeds into: architect (plan documents), builder (TDD targets), validator (PASS/FAIL rows), and bdd-generate (Gherkin scaffolding). The handoff to bdd-generate is optional.

Context

Output Format

## Acceptance Criteria: {Feature Name}

### AC-1: {Descriptive title}
**Given** {precondition — state before the action}
**When** {single action the user or system takes}
**Then** {verifiable, measurable outcome}
  and {additional outcome on indented line}

**Edge cases:**
- {What should happen when...?}

**Notes:** {Open questions, V2 considerations, or scope decisions}

Design rules:

• AC-N numbering — provides traceability from spec → plan → implementation → verification
• Bold Given/When/Then — human-readable markdown, not Gherkin. Conversion happens in bdd-generate
• One action per When — if "When" contains "and", split into separate criteria
• Verifiable Then — every outcome must be observable and testable. "The system works correctly" is not verifiable. "The system returns HTTP 200 with user_id" is.
• Scenario Outline tables — consolidate when 3+ edge cases follow the same pattern:

### AC-N: Input validation (parameterized)
**Given** a user on the registration form
**When** the user submits with `<input>`
**Then** the system displays `<error_message>`

| input | error_message |
|-------|---------------|
| empty email | "Email is required" |
| "not-an-email" | "Invalid email format" |

Anti-Patterns

Anti-Pattern	Example	Fix
Implementation-as-criteria	"Then the system stores a bcrypt hash"	"Then the password is stored securely"
God criterion	AC covers login + session + redirect + audit	Split into AC-1, AC-2, AC-3, AC-4
Missing the Given	"When the user clicks delete Then removed"	"Given a user viewing their own item When..."
Non-verifiable Then	"Then handles the error gracefully"	"Then displays 'Unable to process' and logs correlation ID"

Positive Patterns

• Negative Path — spec what should not happen: "Then does not reveal whether the email exists"
• State Transition — "Given order in 'pending' When payment confirmed Then transitions to 'confirmed'"
• Permission Matrix — Scenario Outline for role-based access (role × action × result table)

Edge Case Probing

For structured probing questions organized by domain (input validation, auth, state integrity, concurrency, boundaries, errors, external deps, UX states), consult:

→ references/edge-case-checklist.md

For BDD terminology definitions, consult:

→ references/bdd-glossary.md

Process

Step 0: Load Stored Feedback

python ${CLAUDE_PLUGIN_ROOT}/scripts/feedback_manager.py autonomous-sdlc show-feedback

Apply relevant feedback: spec_writing, bdd_workflow, general.

Step 1: Understand Feature Intent

Redirect implementation language to behavior language. "I need JWT authentication" → "Users need to log in and stay authenticated across requests."

Ask:

• Who is the actor? (End user, admin, system, external service?)
• What is the core behavior?
• Why does this matter?
• What does success look like from the actor's perspective?

Red flag: if the user describes how instead of what, gently redirect.

Step 2: Write the Happy Path

Coach the Given/When/Then for the primary success scenario:

• Given — What must be true before the action?
• When — What single action triggers the behavior?
• Then — What is the observable result?

Write it. Read it back. Ask: "Does this capture what you mean?"

Step 3: Probe for Error Scenarios

Think hard about how this behavior can fail before asking — the failure modes you miss here become the bugs that ship. Reason through the categories in the checklist rather than picking the obvious ones.

Consult references/edge-case-checklist.md for structured probing questions.

Present edge cases as questions, not assertions. Let the user decide what matters for V1:

• "What should happen when the user submits an empty form?"
• "What if the database is unreachable?"
• "What about concurrent updates?"

For each confirmed edge case, write a full AC block or add to an existing AC's edge case list.

Step 4: Look for Scenario Outlines

When 3+ edge cases follow the same behavioral pattern, consolidate into a parameterized table. Signs: "It should reject empty, too-long, and malformed input" or "Different roles have different permissions."

Checkpoint: Review and Refine

Read back all acceptance criteria, then:

1. Scope check — "Are we trying to do too much for V1? What can wait?"
2. Completeness check — "Is there a scenario we haven't considered?"
3. Verifiability check — "Can each Then be tested automatically?"
4. One more thing — "Anything else before we lock these down?"

Mark deferred items with "V2:" prefix in a Notes section.

Interactive mode (a human asked for a spec in conversation): wait for user confirmation before considering the spec complete.

Autonomous mode (an SDLC loop is active — .sdlc/state.json exists): there is no one to confirm with. Answer the four checks yourself conservatively (smallest defensible V1 scope), log each non-obvious call with python3 ${CLAUDE_PLUGIN_ROOT}/scripts/sdlc_state.py decide --decision "..." --why "...", and proceed. Escalate only a genuine contradiction between requirements — never mere vagueness.

Output

Structured acceptance criteria in markdown, ready to:

• Slot into the ## Acceptance Criteria section of an architect plan document
• Feed into bdd-generate for Gherkin scaffolding
• Serve as standalone specification artifacts

AC-N numbers provide traceability across the entire SDLC pipeline.