--- description: "Transform a rough feature idea into a structured engineering spec: Requirements → Design → Tasks. Produces a SPEC.md ready for team handoff." alwaysApply: true --- # 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 ``` **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 ## Playground

Input: Feature request

Feature: Users should be able to
export their skill collection as
a ZIP file containing all their
SKILL.md files, one per folder.

Output: Feature spec

## Feature: Skill Collection Export

User story
As a skill author, I want to download
all my skills as a ZIP so I can back
them up or use them offline.

Acceptance criteria
- [ ] GET /api/users/me/export returns
      a ZIP with Content-Disposition
- [ ] ZIP contains one folder per skill
      named by skill slug
- [ ] Each folder contains SKILL.md
- [ ] Max 500 skills per export

Out of scope
- Importing from ZIP (separate ticket)
- Including demo media files