# 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:

```markdown
# [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