feature-spec-templates

name	feature-spec-templates
description	Feature specification structure, API contract patterns, and state definition templates. Use when writing implementation-ready feature specs that development agents can execute without ambiguity.

Feature Spec Templates

A feature spec translates a PRD from "what to build" into "exactly how it should behave." Its primary reader is the Development agent — so if a spec leaves room for interpretation, the interpretation will happen during implementation, not during planning. This skill covers the structure and patterns for writing unambiguous feature specs.

When to Use This Skill

• Writing a feature spec from a PRD and journey maps
• Specifying API contracts for backend features
• Documenting all UI states for a new or changed screen
• Reviewing a spec for gaps that would require clarification during development
• Creating a spec that will be handed off to a design team

Core Concepts

1. Spec the States, Not Just the Flow

The most common spec gap is specifying the happy path flow but not the states. Every screen element has states:

• Default / initial state — what does a first-time user see?
• Loading state — what appears while data is fetching?
• Empty state — what appears when there's no data?
• Populated state — what appears with data?
• Error state — what appears when something fails?
• Disabled state — what appears when the action isn't available?

2. Spec the Boundaries

For every input field, list:

• Minimum and maximum length
• Allowed characters / format
• What happens at the boundary (trim? truncate? reject?)
• What happens when empty and the user tries to proceed

3. Explicit Out-of-Scope Section

Every spec must say what it does NOT cover. This prevents scope creep and sets Development's expectations.

Full Feature Spec Template

# Feature Spec: [Feature Name]

**PRD reference:** [Link or section]
**Author:** [Name]
**Status:** Draft / In Review / Approved
**Last updated:** [Date]

---

## Overview

[1-3 sentences describing what this feature does and why.]

## Out of Scope

The following are explicitly NOT part of this spec:
- [Item 1]
- [Item 2]

---

## UI Specification

### Screen: [Screen Name]

**Entry:** [How does the user get here?]

#### States

**Default / Initial State**
[Describe what the user sees when they first land on this screen]

**Loading State**
[What appears while content is loading? Skeleton screens? Spinners? Disabled inputs?]

**Populated State**
[What appears when content is loaded successfully?]

**Empty State**
[What appears when there's no content to show?]
- Headline: "[Copy]"
- Body: "[Copy]"
- CTA (if any): "[Label]" → [Action]

**Error State**
[What appears when loading fails?]
- Error message: "[User-facing copy]"
- Recovery action: [What can the user do?]

#### Components

**[Component Name]**
- Type: [Button / Input / List / Card / etc.]
- Label: "[Copy]"
- Behavior: [What happens when interacted with]
- Disabled condition: [When is this disabled, if ever]
- Validation: [Input rules if applicable]

---

## Backend Specification

### API Endpoints

#### [Method] /api/[path]

**Purpose:** [What this endpoint does]

**Authentication:** Required / Optional / None

**Request:**
```json
{
  "field_name": "type — description",
  "field_name": "type — required — constraints"
}

Validation rules:

• field_name: [min/max length, format, required/optional]

Response — Success (200):

{
  "field_name": "type — description"
}

Response — Errors:

Status Code	Condition	Response Body
400	[Invalid input condition]	{"error": "...", "field": "..."}
401	[Unauthenticated]	{"error": "Authentication required"}
404	[Resource not found]	{"error": "Resource not found"}
422	[Validation failure]	{"error": "...", "details": [...]}
500	[Server error]	{"error": "Internal server error"}

Performance requirements:

• P50 response time: < [Xms]
• P95 response time: < [Xms]
• Rate limit: [X requests per minute per user]

---

Business Logic Rules

Rule: [Rule Name]

Condition: [When this rule applies]
Action: [What the system does]
Example: [Concrete example]

Rule: [Rule Name]

[Same structure]

---

Data Model Changes

[Table / Collection Name]

New fields:

Field	Type	Nullable	Default	Description
[field]	[type]	[Y/N]	[value]	[description]

---

Integration Points

External System	Interaction	Failure Behavior
[Service name]	[What we call it for]	[What we do if it's down or slow]

---

Definition of Done

• [Specific AC 1]
• [Specific AC 2]
• [Performance criterion]
• [Accessibility criterion]

## API Contract Patterns

### REST Endpoint Naming

Collections

GET /api/orders # List orders POST /api/orders # Create order GET /api/orders/{id} # Get specific order PATCH /api/orders/{id} # Partial update DELETE /api/orders/{id} # Delete

Nested resources

GET /api/orders/{id}/items # List items in order POST /api/orders/{id}/items # Add item to order

Actions (when CRUD doesn't fit)

POST /api/orders/{id}/cancel # Cancel order POST /api/orders/{id}/refund # Issue refund

### Pagination Pattern

```json
{
  "data": [...],
  "pagination": {
    "total": 1250,
    "page": 1,
    "per_page": 20,
    "next_cursor": "eyJpZCI6IDEyM30="
  }
}

Use cursor-based pagination for real-time data; offset-based for static datasets.

Error Response Standard

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

State Definition Checklist

For every UI component, verify the spec covers:

• Default/initial state
• Loading state (if data is fetched)
• Empty state (if content can be absent)
• Populated state
• Error state
• Disabled state (if the action can be unavailable)
• Focused state (for form inputs)
• Validation error state (for form inputs)
• Success state (after form submission or action)

Best Practices

1. Write for a developer who has never seen the product — don't assume context
2. Use concrete examples — abstract descriptions invite misinterpretation
3. Never write "as needed" or "if appropriate" — define the condition explicitly
4. Spec the copy — placeholder text, error messages, and labels must be in the spec
5. Distinguish UI behavior from backend logic — a spec that mixes them is hard to review and hard to implement
6. Out-of-scope section is not optional — what you don't specify, someone will assume