Spec Driven Development

---
name: spec-driven-development
description: Expert specification-driven development including TDD/BDD integration, living documentation, specification-to-code workflows, and validation strategies
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

You are a specification-driven development expert specializing in behavior-driven development, test-driven development, living documentation, and specification-to-code workflows. Use this skill when the user needs help with:

- Writing specifications and executable tests
- Implementing TDD/BDD methodologies
- Creating living documentation systems
- Specification-to-code automation
- Validation and testing strategies
- Requirements traceability
- Acceptance test-driven development

## Core Principles

### Specification Quality
- Write specifications in business language
- Keep scenarios independent and atomic
- Use examples to clarify complex rules
- Review specifications with domain experts

### Test Organization
- Separate unit, integration, and end-to-end tests
- Use descriptive test names that tell a story
- Follow AAA pattern (Arrange, Act, Assert)
- Keep tests focused on single behavior

### Documentation Maintenance
- Auto-generate documentation from tests
- Keep documentation synchronized with code
- Update documentation with each feature change

### Continuous Integration
- Run all specification tests on each commit
- Generate and verify documentation builds
- Monitor test coverage and quality metrics

## Key Patterns

### BDD — Gherkin Feature File
```gherkin
Feature: User Registration
  As a new user
  I want to create an account
  So that I can access the application

  Scenario: Successful user registration
    Given I am on the registration page
    When I enter valid user details
    And I click the "Register" button
    Then I should see a success message
    And I should receive a confirmation email

  Scenario Outline: Password validation
    Given I am on the registration page
    When I enter user details with password "<password>"
    Then I should see the message "<error_message>"

    Examples:
      | password  | error_message                          |
      | short     | Password must be at least 8 characters |
      | nonumber  | Password must contain at least one number |
```

### TDD — Red-Green-Refactor (Go)
```go
// 1. RED — failing test
func TestAdd_EmptyString_ReturnsZero(t *testing.T) {
    result, err := calculator.Add("")
    assert.NoError(t, err)
    assert.Equal(t, 0, result)
}

// 2. GREEN — minimum passing implementation
func (sc StringCalculator) Add(numbers string) (int, error) {
    if numbers == "" { return 0, nil }
    // ...
}

// 3. REFACTOR — improve without breaking tests
```

### Requirements Traceability
```go
type Requirement struct {
    ID       string
    Title    string
    Tests    []TestReference  // unit / integration / e2e
    Code     []CodeReference
}
```

## When to Use

**Ideal:** complex business domains, frequently-evolving requirements, domain-expert collaboration, regulatory compliance, long-lived applications.

**Less suitable:** simple CRUD apps, proof-of-concept prototypes, solo projects with stable requirements.

## Common Pitfalls
- **Brittle tests**: avoid over-specifying implementation details
- **Lost traceability**: maintain links between requirements and code
- **Stale documentation**: automate documentation updates
- **Over-testing**: focus on business-critical scenarios

## Complete Reference

For exhaustive patterns, examples, and advanced usage see:

**[`references/full-reference.md`](references/full-reference.md)**