Feature Spec Writer

Purpose: Transform a rough feature idea into a structured implementation spec using the Kiro-style Requirements → Design → Tasks breakdown. Produces a SPEC.md document ready for engineering handoff — no more half-baked tickets.

Invocation

/spec <feature-idea>

Example: /spec Add OAuth login with GitHub and Google

Process

Phase 1: Requirements Analysis

Formalize requirements from the raw feature description.

Functional Requirements (what it MUST do)

• Extract concrete behaviors the feature must support
• Write in user story format: "As a [user], I can [action] so that [outcome]"
• Assign IDs: FR-1, FR-2, ...

Non-Functional Requirements

• Performance targets (latency, throughput, data volume)
• Security constraints (auth model, data handling, compliance)
• Accessibility (WCAG 2.1 AA minimum)
• Browser / platform / device targets

Out of Scope

• Explicitly list what this spec does NOT cover — prevents scope creep

Phase 2: Technical Design

Architecture Overview

• Which layers are touched: frontend, API, database, third-party services
• New components vs modified existing components
• Data flow (text-based ASCII diagram if helpful)

Data Model Changes

• New tables, columns, or indexes
• Migration strategy and rollback plan

API Changes

• New or modified endpoints with request/response shapes
• Auth requirement per endpoint (public / authenticated / admin)

UI/UX Changes

• Pages and components affected
• New routes if applicable
• State management implications

Phase 3: Task Breakdown

Produce a numbered task checklist in implementation order:

TASKS
[ ] 1. Database: Create migration for [table/column]
[ ] 2. API: Add POST /[resource] with [auth requirement]
[ ] 3. Frontend: Build [Component] in [location]
[ ] 4. Tests: Unit tests for [function/route]
[ ] 5. Tests: E2E test for [user flow]
[ ] 6. Docs: Update [doc] with new behavior
[ ] 7. Deploy: Feature flag rollout or straight deploy

Each task must be completable in ≤ 4 hours. Break down anything larger.

Output Format

Produce a SPEC.md file with this structure:

# [Feature Name] — Engineering Spec

**Status:** Draft
**Author:** @[username]
**Date:** [today]
**Estimated effort:** [X days / Y tasks]

---

## Requirements

### Functional
[FR-1 through FR-N as user stories]

### Non-Functional
[Performance, security, accessibility]

### Out of Scope
[Explicit exclusions]

---

## Design

### Architecture
[Overview + data flow]

### Data Model
[Schema changes + migration plan]

### API
[Endpoints + auth]

### UI/UX
[Component changes + routes]

---

## Tasks

[Numbered, ordered checklist]

---

## Open Questions

[Unresolved decisions — list even if none to show they were considered]

---

## Security Checklist

- [ ] Auth required on all mutation endpoints
- [ ] Input validation on all user-supplied fields
- [ ] No PII in logs or error messages
- [ ] Rate limiting on high-frequency endpoints

Rules

• Requirements must be testable — if you cannot write a test for it, rewrite it
• Every API change must state its auth requirement explicitly
• Tasks must be ordered by dependency (no task references a later task)
• Flag all unresolved decisions as Open Questions — never silently assume
• If the feature touches auth, payments, or data deletion: add an explicit Security Checklist section
• Estimate effort in tasks, not hours — estimates in hours are always wrong