atdd-assistant

name	atdd-assistant
scope	partial
description	Guide teams through Acceptance Test-Driven Development workflow. Use when: defining acceptance criteria, running specification workshops, writing user stories with acceptance tests, PO sign-off. Keywords: ATDD, acceptance test, acceptance criteria, user story, product owner, specification workshop, 驗收測試驅動開發.

ATDD Assistant

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2026-01-19 Applicability: Claude Code Skills

---

Purpose

This skill guides teams through the Acceptance Test-Driven Development workflow, helping them:

• Conduct effective Specification Workshops
• Write testable acceptance criteria in Given-When-Then format
• Convert criteria to executable acceptance tests
• Ensure proper collaboration between PO, Dev, and QA
• Integrate ATDD with BDD and TDD for complete workflow

---

Quick Reference

ATDD Workflow Checklist

┌─────────────────────────────────────────────────────────────────┐
│  🤝 SPECIFICATION WORKSHOP Phase                                 │
│  □ Product Owner presents user story                            │
│  □ Team asks clarifying questions                               │
│  □ Acceptance criteria defined together                         │
│  □ Concrete examples written for each AC                        │
│  □ Edge cases and error scenarios discussed                     │
│  □ Out of scope explicitly documented                           │
├─────────────────────────────────────────────────────────────────┤
│  🧪 DISTILLATION Phase                                           │
│  □ Examples converted to executable tests                       │
│  □ Ambiguity removed from tests                                 │
│  □ Tests in executable format (Gherkin, FitNesse, etc.)         │
│  □ Product Owner signs off on tests                             │
├─────────────────────────────────────────────────────────────────┤
│  💻 DEVELOPMENT Phase                                            │
│  □ Acceptance tests initially fail (RED)                        │
│  □ BDD used for feature tests, TDD for unit tests               │
│  □ Incremental progress toward passing ATs                      │
│  □ All acceptance tests pass (GREEN)                            │
│  □ Code refactored and clean                                    │
├─────────────────────────────────────────────────────────────────┤
│  🎬 DEMO Phase                                                   │
│  □ All acceptance tests passing                                 │
│  □ Demo environment prepared                                    │
│  □ Key stakeholders present                                     │
│  □ Product Owner validates functionality                        │
│  □ Story accepted or criteria refined                           │
└─────────────────────────────────────────────────────────────────┘

Acceptance Criteria Quick Reference

Element	Format	Example
User Story	As a / I want / So that	As a customer, I want to reset my password, so that I can regain access
AC Format	Given / When / Then	Given I'm on the login page, When I click "Forgot Password", Then I should see a reset form
Out of Scope	Bullet list	- SMS reset, - Admin reset capability
Technical Notes	Bullet list	- Token expires in 24 hours

INVEST Criteria

Principle	Description	Check
Independent	Can be developed independently	No blocking dependencies
Negotiable	Details can be discussed	Not a contract
Valuable	Delivers business value	PO can explain the "why"
Estimable	Can be estimated	Team understands scope
Small	Fits in one sprint	< 1 week of work
Testable	Can be verified	Clear acceptance criteria

---

Workflow Assistance

Specification Workshop Guidance

When conducting a specification workshop:

1. Story Presentation (5 min)

   User Story: [Title]
   
   As a [role]
   I want [feature]
   So that [benefit]
   
   Business Value: [Why this matters]
   

2. Clarifying Questions (10 min)

   • Business: "What's the value?", "Who are the users?"
   • Development: "What's the impact?", "Dependencies?"
   • Testing: "What could go wrong?", "Edge cases?"

3. AC Definition (20 min)

   ### AC-1: [Criterion name]
   **Given** [precondition]
   **When** [action]
   **Then** [expected result]
   

4. Out of Scope (10 min)

   • Explicitly list what is NOT included
   • Prevents scope creep during development

5. Technical Notes (5 min)

   • Implementation hints
   • Known constraints
   • Dependencies

Distillation Guidance

When converting AC to executable tests:

1. Review Each AC

   • Is it unambiguous?
   • Can it be automated?
   • Does it verify business value?

2. Choose Test Format

   Format	Best For
   Gherkin	Behavior-focused, business-readable
   FitNesse	Data-driven, wiki tables
   Robot Framework	Complex workflows
   Code (xUnit)	Technical teams

3. Write Executable Tests

   # For AC-1: Password reset request
   Scenario: Request password reset
     Given I am on the login page
     And I have a registered account
     When I click "Forgot Password"
     And I enter my email address
     Then I should see "Reset link sent"
     And I should receive an email within 5 minutes
   

4. Get PO Sign-off

   • PO confirms tests represent requirements
   • Sign-off before development starts

Demo Guidance

When preparing for demo:

1. Pre-Demo Checklist

   □ All acceptance tests passing
   □ Demo environment ready
   □ Test data prepared
   □ Stakeholders notified
   

2. Demo Structure (15-30 min)

   • Context (1 min): Remind story and AC
   • Tests (2 min): Run acceptance tests live
   • Feature (5-10 min): Walk through each AC
   • Feedback (5 min): Gather feedback, Q&A

3. Possible Outcomes

   • ✅ Accepted: Story complete
   • 🔄 Refinement: Return to workshop
   • ❌ Rejected: Identify gaps

---

User Story Template

## User Story: [Title]

**As a** [role]
**I want** [feature]
**So that** [benefit]

## Acceptance Criteria

### AC-1: [Happy path]
**Given** [precondition]
**When** [action]
**Then** [expected result]

### AC-2: [Error scenario]
**Given** [precondition]
**When** [invalid action]
**Then** [error handling]

### AC-3: [Edge case]
**Given** [edge condition]
**When** [action]
**Then** [appropriate result]

## Out of Scope
- [Feature 1 not included]
- [Feature 2 deferred to future]

## Technical Notes
- [Implementation constraint]
- [Dependency information]
- [Performance requirement]

## Questions / Assumptions
- [Open question 1]
- [Assumption 1]

---

Integration with Other Workflows

ATDD → BDD → TDD Flow

ATDD Level (Business Acceptance)
  │
  │  User Story + Acceptance Criteria
  │  PO Sign-off
  │
  ▼
BDD Level (Behavior Specification)
  │
  │  Feature Files (Gherkin)
  │  Three Amigos collaboration
  │
  ▼
TDD Level (Implementation)
  │
  │  Unit Tests
  │  Red → Green → Refactor
  │
  ▼
Verification (Demo)
  │
  └──▶ PO Acceptance

ATDD + SDD Integration

# Link ATDD to SDD Spec

## User Story: US-123

**Spec Reference**: SPEC-001

### AC-1: Implements SPEC-001 Section 3.1
**Given** [from spec requirements]
**When** [action per spec]
**Then** [expected per spec]

---

Configuration Detection

This skill supports project-specific configuration.

Detection Order

1. Check CONTRIBUTING.md for "Disabled Skills" section
2. Check CONTRIBUTING.md for "ATDD Standards" section
3. Check for existing acceptance test patterns
4. If not found, default to standard ATDD practices

First-Time Setup

If no configuration found:

1. Ask: "This project hasn't configured ATDD preferences. Which acceptance test format do you prefer?"

   • Gherkin (Cucumber, SpecFlow)
   • FitNesse tables
   • Code-based (xUnit)

2. After selection, suggest documenting in CONTRIBUTING.md:

## ATDD Standards

### Acceptance Test Format
- Gherkin (Cucumber.js)

### User Story Template
- INVEST criteria required
- Given-When-Then format for AC

### Workflow
- Specification workshop required for all stories
- PO sign-off before development
- Demo for each completed story

---

Detailed Guidelines

For complete standards, see:

• ATDD Core Standard
• ATDD Workflow Guide
• Acceptance Criteria Guide

For related standards:

• BDD Standards
• TDD Standards
• Testing Standards

---

Anti-Patterns Quick Detection

Symptom	Likely Problem	Quick Fix
Features marked done but PO rejects	AC not validated with PO	Mandatory PO sign-off
Long dev with no progress	AC too large or vague	Break into smaller criteria
Acceptance tests always pass first time	Tests written after implementation	Tests before dev
Endless scope discussions	No "out of scope" definition	Explicit out-of-scope
AC can't be automated	QA/Dev not involved in AC definition	Technical perspective in workshop

---

RACI Matrix

Activity	Product Owner	Developer	QA/Tester
Define user story	R/A	C	C
Specification workshop	R	C	C
Define acceptance criteria	A	R	R
Write executable tests	C	R	R/A
Implement feature	C	R/A	C
Execute acceptance tests	I	R	R/A
Accept/reject feature	R/A	I	I

Legend: R = Responsible, A = Accountable, C = Consulted, I = Informed

---

Related Standards

• Acceptance Test-Driven Development - Core ATDD standard
• Behavior-Driven Development - BDD standard
• Test-Driven Development - TDD standard
• Spec-Driven Development - SDD workflow
• Testing Standards - Testing framework
• BDD Assistant - BDD skill
• TDD Assistant - TDD skill

---

Version History

Version	Date	Changes
1.0.0	2026-01-19	Initial release

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards