Feature Specification Template

Overview

The most expensive bugs are not in code — they are in misunderstood requirements. A feature specification is a document that aligns product, design, and engineering on what to build, why it matters, and how to know it is done. It prevents the “I thought you meant…” conversations that derail sprints and create rework. A good spec is not a contract; it is a shared understanding that evolves as the team learns.

When to Use

• For alternatives, see What Works in Code Review — For Authors and Reviewers.

Use this template when:

• A feature touches multiple systems, teams, or user journeys
• Engineers and product managers have different understandings of the requirement
• The feature has non-obvious edge cases, dependencies, or rollout complexity
• You need to estimate effort before committing to a sprint
• The feature affects users, data, or billing and needs explicit sign-off

Prerequisites

Before writing a feature specification:

• The product goal is clear: what problem are we solving and for whom?
• Stakeholders (product, engineering, design, QA) are identified
• Success metrics are defined: how will we know this feature worked?
• Constraints are documented: time, budget, compliance, or technical limitations
• You have reviewed related specs to avoid duplicating or conflicting with existing work

Solution

# Feature Specification: `<Feature Name>`

> Author: ______ | Product Owner: ______ | Status: Draft / In Review / Approved
> Created: YYYY-MM-DD | Last updated: YYYY-MM-DD | Target release: ______

## 1. Summary

**Problem:** [What user pain or business opportunity does this address?]

**Proposed solution:** [One-paragraph description of the feature]

**Success criteria:** [How we measure whether this feature solved the problem]

## 2. Goals and Non-Goals

### Goals
- [Goal 1: what we will achieve]
- [Goal 2]
- [Goal 3]

### Non-Goals
- [What we are explicitly not doing in this version]
- [What is out of scope]

## 3. User Stories

| User | Need | So That | Priority |
|------|------|---------|----------|
| [Persona] | [Action] | [Outcome] | P0 / P1 / P2 |
| ______ | ______ | ______ | ______ |

## 4. Functional Requirements

### 4.1 [Requirement Area 1]
- **FR-1.1:** [Specific, testable requirement]
- **FR-1.2:** [Specific, testable requirement]

### 4.2 [Requirement Area 2]
- **FR-2.1:** [Specific, testable requirement]

## 5. Non-Functional Requirements

- **Performance:** [e.g., p99 response time < 200ms]
- **Scalability:** [e.g., support 10x current load]
- **Availability:** [e.g., 99.9% uptime during rollout]
- **Security:** [e.g., data encrypted in transit and at rest]
- **Accessibility:** [e.g., WCAG 2.1 AA compliant]
- **Compliance:** [e.g., GDPR right to deletion supported]

## 6. Design and UX

- **Figma / mockups:** [Link]
- **Copy and localization:** [Link or notes]
- **Interaction flow:** [Step-by-step or diagram]
- **Edge cases:** [Empty states, errors, loading, offline]

## 7. Technical Approach

### Architecture
[Diagram or description of how this feature fits into existing systems]

### Data Model Changes
[New tables, fields, or schema changes]

### API Changes
[New endpoints, modified payloads, backward compatibility plan]

### Dependencies
[Services, libraries, or teams this feature depends on]

### Rollout Strategy
- **Phase 1:** [Internal testing / alpha]
- **Phase 2:** [Beta with limited users]
- **Phase 3:** [General availability]
- **Rollback plan:** [How to undo if something goes wrong]

## 8. Acceptance Criteria

- [ ] [Criteria 1: specific, verifiable condition for done]
- [ ] [Criteria 2]
- [ ] [Criteria 3]

## 9. Open Questions

| Question | Owner | Due Date |
|----------|-------|----------|
| ______ | ______ | ______ |

## 10. Appendix

- **Related specs:** [Links]
- **Historical context:** [Previous attempts, related decisions]
- **Glossary:** [Terms that need definition]

Explanation

The template is organized by audience: product owns the summary and goals, design owns the UX section, engineering owns the technical approach, and QA owns acceptance criteria. Separating functional from non-functional requirements prevents the common mistake of forgetting performance, security, or accessibility until late in development. The non-goals section is particularly important: it prevents scope creep by making explicit what is out of scope.

Feature Spec Example

# Feature Spec: Real-time Order Notifications

## Summary
Add real-time order status notifications to the user dashboard
using WebSocket connections. Users will see order updates
immediately without page refresh.

## Goals
- Reduce support tickets about order status by 30%
- Improve user engagement with the dashboard
- Provide sub-second notification delivery

## Non-Goals
- Mobile push notifications (separate feature)
- Email notifications (already implemented)
- Order history search (separate feature)

## User Stories
1. As a buyer, I want to see order status updates in real-time
   so I do not need to refresh the page.
2. As a seller, I want to know when an order is placed so I can
   prepare the shipment immediately.
3. As a support agent, I want to see the same notifications so I
   can answer customer questions accurately.

## Functional Requirements
- WebSocket connection on dashboard page load
- Reconnection with exponential backoff on disconnect
- Notification payload includes: order ID, status, timestamp
- Notifications appear as toast messages and in a notification panel

## Non-Functional Requirements
- Notification delivery latency: p95 < 500ms
- WebSocket connections: support 10,000 concurrent
- Fallback to polling if WebSocket fails after 3 retries
- Accessibility: notifications announced via ARIA live region

## Technical Approach
- WebSocket gateway: AWS API Gateway WebSocket
- Message broker: Redis Pub/Sub
- Auth: JWT token passed in connection query params
- Frontend: native WebSocket API with reconnection wrapper

## API Changes
- New endpoint: GET /api/v1/notifications/stream (WebSocket upgrade)
- New endpoint: GET /api/v1/notifications (REST fallback, polling)
- No breaking changes to existing endpoints

## Rollout Strategy
- Phase 1: Internal testing with 10 users (1 week)
- Phase 2: Beta with 5% of users (2 weeks)
- Phase 3: General availability (monitor for 1 week)
- Rollback: Disable WebSocket feature flag, users fall back to polling

## Acceptance Criteria
- [ ] WebSocket connects on dashboard load
- [ ] Order status changes appear within 500ms
- [ ] Connection recovers automatically after network interruption
- [ ] Notifications are accessible via screen reader
- [ ] System handles 10,000 concurrent connections in load test

Variants

Context	Adjustments	Notes
API-only feature	Replace UX section with endpoint design, payload schemas, and versioning plan	Internal APIs still need user stories (the user is another developer)
Data / ML feature	Add data sources, model training pipeline, and evaluation metrics	ML specs need experiment tracking and reproducibility
Security feature	Expand security requirements; add threat model and compliance mapping	Security features need explicit sign-off from security team
Platform / infrastructure feature	Replace user stories with affected teams and migration requirements	Platform work has users, but they are internal teams
Experiment / A/B test	Add hypothesis, success metrics, sample size, and rollback criteria	Experimental features need clear kill criteria

What Works

1. Write the spec before coding starts — the goal is shared understanding, not documentation after the fact
2. Keep the summary on one page — busy stakeholders should grasp the feature in 60 seconds
3. Make requirements testable — vague requirements like “fast” become “p99 < 200ms”
4. Include non-goals explicitly — this is your best defense against mid-sprint scope expansion
5. Review the spec with engineering before estimating — engineers catch edge cases product misses

Common Mistakes

1. Writing the spec alone — a spec written by product without engineering input becomes fiction
2. Skipping non-functional requirements — performance, security, and accessibility are not “nice to have”; they are requirements
3. Making acceptance criteria vague — “works as expected” is not acceptance criteria; “user can complete checkout in under 3 clicks” is
4. Not updating when scope changes — specs that diverge from reality mislead QA, support, and future maintainers
5. Forgetting rollout and rollback — the feature is not done when code is merged; it is done when users are successfully using it

Troubleshooting

• Pipeline fails silently: enable verbose logging and store pipeline artifacts between stages so you can inspect the exact state that failed.
• Container crashes on startup: check that environment variables, secrets, and config files are mounted correctly. Read the first 50 lines of logs before scaling replicas.
• Deployment rolls back repeatedly: verify health checks, resource limits, and startup probes. A failing readiness probe is a common cause of rolling restarts.
• Slow CI builds: cache dependencies and docker layers. Split large test suites into parallel jobs to reduce wall-clock time.
• Drift between environments: use infrastructure-as-code and immutable artifacts.

Production Notes

• Deploy gradually using canary or blue-green to catch regressions early.
• Configure alerts for error rate, p99 latency, and failure rate before enabling in production.
• Document the rollback in the runbook; test the procedure in staging at least once per quarter.
• Review structured logs with correlation IDs to trace requests end-to-end during incidents.

Key Takeaways

• Apply feature specification template when you need a practical solution for your use case.
• Monitor performance after implementation; measure latency, errors, and resource usage before and after.
• Check the Troubleshooting section for common failures; most have documented root causes with fixes.
• Keep dependencies updated and run tests in CI to prevent production regressions.

Common Production Pitfalls

• Leaving required fields blank or using vague one-word answers.
• Filling the document once and never updating it after scope or decisions change.
• Storing the document where the team does not look during incidents or reviews.
• Not assigning an owner, due date, or review cadence.
• Copying boilerplate without removing sections that do not apply.
• Skipping version control, which makes rollback and accountability impossible.
• Failing to link the document to related decisions or follow-up actions.
• Avoiding quarterly reviews that would retire stale or unused sections.