Specification Writing

Transform a REQUIREMENTS.md artifact into a comprehensive FUNCTIONAL_SPEC.md artifact containing detailed feature specifications, user flows, business rules, edge cases, data models, and API contracts. This is the third step in the greenfield specification pipeline — it takes prioritized requirements and produces implementation-ready specifications.

When to Use This Skill

• A REQUIREMENTS.md exists and has been validated
• You need detailed feature definitions before architecture design
• Developers need precise specifications for implementation
• Business rules and edge cases need formal documentation
• API contracts need to be defined for integration planning

Pipeline Position

[Raw Idea] → [PROBLEM_BRIEF.md] → [REQUIREMENTS.md] → **SPECIFICATION WRITING** → [FUNCTIONAL_SPEC.md] → Architecture → ...

Input: artifacts/greenfield/<project_name>/REQUIREMENTS.md Output: artifacts/greenfield/<project_name>/FUNCTIONAL_SPEC.md

Process

Step 1: Read and Analyze Requirements

Load the REQUIREMENTS.md and extract:

• All functional requirements (REQ-NNNN) with priorities and acceptance criteria
• All user stories (US-NNNN) with Given/When/Then criteria
• All non-functional requirements (NFR-NNNN) with metrics
• Dependency graph between requirements
• Functional areas for grouping

Map requirements to feature specifications: typically one FS per REQ, but related REQs may be combined into a single feature spec if they share the same user flow.

Step 2: Group Requirements into Feature Specs

Create feature specifications (FS-NNNN) by grouping related requirements:

Grouping rules:

• One FS per functional requirement by default
• Combine REQs into a single FS only when they share the same primary user flow
• Never combine REQs from different functional areas into one FS
• P0 requirements get the most detailed specs
• Each FS must map to at least one REQ-NNNN

Feature spec structure:

FS-NNNN: [Feature Name]
Requirements: REQ-NNNN, REQ-NNNN
Priority: [Inherited from highest-priority mapped REQ]

Step 3: Write User Flows

For each feature spec, create at least one user flow using Mermaid diagrams:

User flow types:

• Happy path: The primary successful flow (required for every FS)
• Error path: How the system handles failures (required for P0 features)
• Edge case path: Unusual but valid scenarios (required for P0, recommended for P1)

Mermaid format:

flowchart TD
    A[User Action] --> B{Decision Point}
    B -->|Yes| C[Success State]
    B -->|No| D[Error State]
    C --> E[Next Step]
    D --> F[Recovery Action]

Rules for user flows:

• Start with user action, end with system state
• Every decision point must have at least two branches
• Error states must show recovery paths
• Flows must reference specific REQ-NNNN and US-NNNN IDs
• Keep flows to 5-12 steps maximum (split if larger)

Step 4: Define Business Rules

For each feature spec, identify and document business rules:

Business rule format:

BR-NNNN: [Business Rule Title]
Feature: FS-NNNN
Rule: [Precise, unambiguous statement of the rule]
Source: [REQ-NNNN or domain knowledge]
Validation: [How to verify the rule is enforced]
Example:
  - Valid: [Example of rule being satisfied]
  - Invalid: [Example of rule being violated]

Rules for business rules:

• Every BR must be deterministic (same input always produces same output)
• Every BR must have at least one valid and one invalid example
• BRs must not contradict each other within the same FS
• BRs must reference the FS-NNNN and REQ-NNNN they implement

Step 5: Document Edge Cases

For each feature spec, identify edge cases that require special handling:

Edge case format:

EC-NNNN: [Edge Case Title]
Feature: FS-NNNN
Scenario: [Description of the unusual but valid scenario]
Expected Behavior: [What the system should do]
Related Business Rules: BR-NNNN

Common edge case categories:

• Boundary values (min/max/zero/empty)
• Concurrent operations (race conditions, conflicts)
• Data quality (missing fields, invalid formats, encoding)
• Permission boundaries (unauthorized access, role transitions)
• State transitions (invalid state changes, interruptions)
• Resource limits (quotas, rate limits, storage)

Step 6: Define Data Models

Create data model definitions for each feature spec that involves data persistence:

Data model format:

Entity: [Entity Name]
Feature: FS-NNNN
Description: [What this entity represents]

| Field | Type | Required | Constraints | Description |
|-------|------|----------|-------------|-------------|
| id | UUID | Yes | Primary key | Unique identifier |
| name | string | Yes | Max 255 chars | Display name |
| status | enum | Yes | [active, inactive, deleted] | Current state |
| created_at | datetime | Yes | Immutable | Creation timestamp |
| updated_at | datetime | Yes | Auto-updated | Last modification |

Relationships:
- [Entity Name] has many [Related Entity]
- [Entity Name] belongs to [Parent Entity]

Indexes:
- [field_name] — [purpose, e.g., "lookup by status"]
- [field_a, field_b] — [purpose, e.g., "unique constraint on name per parent"]

Rules for data models:

• Every entity must have an id field
• Every entity must have created_at and updated_at fields
• Relationships must be explicitly stated
• Indexes must be documented with their purpose
• Enums must list all valid values
• String fields must specify maximum length

Step 7: Define API Contracts

For features that expose or consume APIs, define contracts:

API contract format:

API-NNNN: [Endpoint Name]
Feature: FS-NNNN
Method: GET | POST | PUT | PATCH | DELETE
Path: /api/v1/[resource]
Authentication: Required | Optional | None
Authorization: [Role or permission required]

Request:
  Headers:
    - Content-Type: application/json
    - Authorization: Bearer {token}
  Path Parameters:
    - id (string, required): [description]
  Query Parameters:
    - page (integer, optional, default=1): [description]
    - limit (integer, optional, default=20, max=100): [description]
  Body:
    ```json
    {
      "field_name": "type — description",
      "field_name": "type — description"
    }
    ```

Response:
  Success (200):
    ```json
    {
      "data": { ... },
      "meta": { "page": 1, "limit": 20, "total": 100 }
    }
    ```
  Error (400):
    ```json
    {
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Human-readable message",
        "details": [{ "field": "name", "issue": "required" }]
      }
    }
    ```
  Error (404):
    ```json
    {
      "error": {
        "code": "NOT_FOUND",
        "message": "Resource not found"
      }
    }
    ```

Rate Limiting: [requests per minute/hour]
Idempotency: [Yes/No — if Yes, specify idempotency key]

Rules for API contracts:

• Every endpoint must define success and at least one error response
• Request/response bodies must use JSON format
• Pagination must be specified for list endpoints
• Authentication/authorization requirements must be explicit
• Rate limiting must be documented
• Idempotency must be specified for mutating endpoints (POST, PUT, PATCH)

Output Format

Write the artifact following the template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/FUNCTIONAL_SPEC.template.md.

The artifact must follow the standard artifact template structure:

# FUNCTIONAL_SPEC: [Project Name]

## Summary
[2-3 sentence summary: number of feature specs, coverage of requirements, key design decisions]

## Inputs
- **Requirements**: `REQUIREMENTS.md` — [REQ count, priority breakdown]
- **Problem Brief**: `PROBLEM_BRIEF.md` — [referenced for constraints and non-goals]

## Outputs
- This document (FUNCTIONAL_SPEC.md)
- Feeds into: ARCHITECTURE.md (via architecture skill)
- Feeds into: TASKS.md (via task-breakdown skill)

## Assumptions
- [ASM-0001]: [Assumption text — inherited or new]
- ...

## Open Questions
- [OQ-0001]: [Question that affects feature design]
- ...

## Main Content

### Feature Specifications Overview

| ID | Feature Name | Requirements | Priority | User Flows | Business Rules | Edge Cases |
|----|-------------|-------------|----------|------------|----------------|------------|
| FS-0001 | [Name] | REQ-0001, REQ-0002 | P0 | 2 | 3 | 4 |
| FS-0002 | [Name] | REQ-0003 | P1 | 1 | 2 | 2 |
| ... | ... | ... | ... | ... | ... | ... |

---

### FS-0001: [Feature Name]

**Requirements**: REQ-0001, REQ-0002
**Priority**: P0
**Description**: [Detailed description of what this feature does and why]

#### User Flows

##### Happy Path: [Flow Name]

```mermaid
flowchart TD
    A[User starts action] --> B{Validation passes?}
    B -->|Yes| C[Process request]
    C --> D[Return success]
    B -->|No| E[Show validation errors]
    E --> A

Steps:

1. User [action] — references US-0001
2. System [validates] — references BR-0001
3. System [processes] — references REQ-0001
4. System [responds] — references US-0002

Error Path: [Flow Name]

flowchart TD
    A[User action] --> B{System available?}
    B -->|No| C[Show error message]
    C --> D[Offer retry]
    B -->|Yes| E[Continue flow]

Business Rules

BR-0001: [Business Rule Title]

• Feature: FS-0001
• Rule: [Precise statement]
• Source: REQ-0001
• Validation: [How to verify]
• Examples:
  • Valid: [Example]
  • Invalid: [Example]

BR-0002: [Business Rule Title]

• Feature: FS-0001
• Rule: [Precise statement]
• Source: REQ-0002
• Validation: [How to verify]
• Examples:
  • Valid: [Example]
  • Invalid: [Example]

Edge Cases

EC-0001: [Edge Case Title]

• Feature: FS-0001
• Scenario: [Description]
• Expected Behavior: [What should happen]
• Related Business Rules: BR-0001

EC-0002: [Edge Case Title]

• Feature: FS-0001
• Scenario: [Description]
• Expected Behavior: [What should happen]
• Related Business Rules: BR-0002

Data Model

Entity: [Entity Name]

• Feature: FS-0001
• Description: [What this entity represents]

Field	Type	Required	Constraints	Description
id	UUID	Yes	Primary key	Unique identifier
...	...	...	...	...

Relationships:

• [Entity] has many [Related Entity]

Indexes:

• [field] — [purpose]

API Contracts

API-0001: [Endpoint Name]

• Feature: FS-0001
• Method: POST
• Path: /api/v1/[resource]
• Authentication: Required
• Authorization: [Role]

Request:

{
  "field": "type — description"
}

Response (201):

{
  "data": { "id": "uuid", "field": "value" }
}

Error (400):

{
  "error": { "code": "VALIDATION_ERROR", "message": "Details" }
}

---

FS-0002: [Feature Name]

[... same structure as FS-0001 ...]

---

Cross-Cutting Concerns

Error Handling Strategy

[How errors are handled across all features — error codes, user messages, logging]

Authentication & Authorization Model

[Shared auth model referenced by all API contracts]

Data Validation Rules

[Shared validation patterns used across features]

Acceptance Criteria

• Every REQ-NNNN maps to at least one FS-NNNN
• Every FS has at least one user flow (happy path)
• P0 features have error path flows
• Every FS has at least one business rule
• Every business rule has valid and invalid examples
• Edge cases documented for all P0 and P1 features
• Data models defined for features involving persistence
• API contracts defined for features exposing/consuming APIs
• All IDs are sequential and sorted appropriately
• Mermaid diagrams render correctly
• Cross-cutting concerns documented

**Output path**: `artifacts/greenfield/<project_name>/FUNCTIONAL_SPEC.md`

## Determinism Rules

1. FS-NNNN IDs: Sort alphabetically by feature name, assign sequential 4-digit numbers starting from 0001
2. BR-NNNN IDs: Sort by parent FS-NNNN first, then alphabetically by rule title within each FS, assign sequential 4-digit numbers starting from 0001 globally
3. EC-NNNN IDs: Sort by parent FS-NNNN first, then alphabetically by edge case title within each FS, assign sequential 4-digit numbers starting from 0001 globally
4. API-NNNN IDs: Sort by parent FS-NNNN first, then by HTTP method order (GET, POST, PUT, PATCH, DELETE), then alphabetically by path, assign sequential 4-digit numbers starting from 0001 globally
5. Data model entities listed alphabetically within each FS
6. No timestamps in artifact body
7. Sections must appear in template order
8. Feature specs ordered by FS-NNNN ID

## Cross-Referencing

The FUNCTIONAL_SPEC.md artifact is referenced by:
- **ARCHITECTURE.md**: Components are designed to implement feature specs
- **TASKS.md**: Tasks map to specific FS-NNNN, BR-NNNN, EC-NNNN, or API-NNNN items
- **IMPLEMENTATION_PLAN.md**: Sprint planning references FS priorities

This artifact references:
- **REQUIREMENTS.md**: Every FS maps to REQ-NNNN IDs
- **PROBLEM_BRIEF.md**: Constraints and non-goals inform feature boundaries

## Handling Complexity

### Large Feature Specs
If a feature spec exceeds 200 lines:
- Split into sub-features (FS-0001a, FS-0001b) only if they have independent user flows
- Otherwise, use clear subsections within the single FS
- Document the complexity in the Summary section

### Missing API Details
If API contracts cannot be fully specified:
- Define the endpoint path, method, and auth requirements at minimum
- Mark request/response bodies as "[TBD — pending data model finalization]"
- Add an Open Question for the missing details

### Conflicting Business Rules
If two business rules within the same feature contradict:
- Document both with a note: "[CONFLICT — see OQ-NNNN]"
- Add an Open Question specifying the conflict
- Do not silently resolve by removing one rule

## Quality Checklist

Before completing, verify:
- [ ] Every REQ-NNNN from REQUIREMENTS.md maps to at least one FS-NNNN
- [ ] Every FS has a happy path user flow with Mermaid diagram
- [ ] P0 features have error path flows documented
- [ ] Every FS has at least one business rule with examples
- [ ] Edge cases cover boundary values, concurrency, and permission boundaries
- [ ] Data models include all required fields (id, created_at, updated_at)
- [ ] Data model relationships and indexes are documented
- [ ] API contracts include success and error responses
- [ ] API contracts specify authentication, authorization, and rate limiting
- [ ] All IDs are sequential and deterministically ordered
- [ ] Mermaid diagrams are syntactically valid
- [ ] Cross-cutting concerns (error handling, auth, validation) are documented
- [ ] No business rule contradicts a constraint from the problem brief
- [ ] Artifact follows the standard template structure

## Common Pitfalls

1. **User flows without decision points**: A linear flow with no branches is not a flow, it is a procedure. Real flows have error handling and decision logic.
2. **Business rules that are vague**: "Users should have appropriate access" is vague. "Only users with the 'admin' role can delete other users' accounts" is precise.
3. **Missing error responses in API contracts**: Every endpoint must handle at least 400 (bad request) and 404 (not found) errors. Auth-protected endpoints need 401 and 403.
4. **Data models without indexes**: If a field is used in queries (WHERE, ORDER BY, JOIN), it needs an index. Document the purpose of each index.
5. **Edge cases that are actually business rules**: "Email must be unique" is a business rule, not an edge case. "What happens when two users try to register with the same email simultaneously" is an edge case.
6. **Specifying implementation in the spec**: "Use Redis for caching" is an implementation decision. "Frequently accessed data should be cached with a TTL of 5 minutes" is a specification.
7. **Ignoring cross-cutting concerns**: Error handling, logging, and auth patterns should be consistent across all features, not defined per-feature.