1# Feature Specification: [FEATURE NAME]
2
3**Feature Branch**: `[###-feature-name]`  
4**Created**: [DATE]  
5**Status**: Draft  
6**Input**: User description: "$ARGUMENTS"
7
8## Execution Flow (main)
9```
101. Parse user description from Input
11   → If empty: ERROR "No feature description provided"
122. Extract key concepts from description
13   → Identify: actors, actions, data, constraints
143. For each unclear aspect:
15   → Mark with [NEEDS CLARIFICATION: specific question]
164. Fill User Scenarios & Testing section
17   → If no clear user flow: ERROR "Cannot determine user scenarios"
185. Generate Functional Requirements
19   → Each requirement must be testable
20   → Mark ambiguous requirements
216. Identify Key Entities (if data involved)
227. Run Review Checklist
23   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
24   → If implementation details found: ERROR "Remove tech details"
258. Return: SUCCESS (spec ready for planning)
26```
27
28---
29
30## ⚡ Quick Guidelines
31- ✅ Focus on WHAT users need and WHY
32- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
33- 👥 Written for business stakeholders, not developers
34
35### Section Requirements
36- **Mandatory sections**: Must be completed for every feature
37- **Optional sections**: Include only when relevant to the feature
38- When a section doesn't apply, remove it entirely (don't leave as "N/A")
39
40### For AI Generation
41When creating this spec from a user prompt:
421. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
432. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
443. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
454. **Common underspecified areas**:
46   - User types and permissions
47   - Data retention/deletion policies  
48   - Performance targets and scale
49   - Error handling behaviors
50   - Integration requirements
51   - Security/compliance needs
52
53---
54
55## User Scenarios & Testing *(mandatory)*
56
57### Primary User Story
58[Describe the main user journey in plain language]
59
60### Acceptance Scenarios
611. **Given** [initial state], **When** [action], **Then** [expected outcome]
622. **Given** [initial state], **When** [action], **Then** [expected outcome]
63
64### Edge Cases
65- What happens when [boundary condition]?
66- How does system handle [error scenario]?
67
68## Requirements *(mandatory)*
69
70### Functional Requirements
71- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
72- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
73- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
74- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
75- **FR-005**: System MUST [behavior, e.g., "log all security events"]
76
77*Example of marking unclear requirements:*
78- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
79- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
80
81### Key Entities *(include if feature involves data)*
82- **[Entity 1]**: [What it represents, key attributes without implementation]
83- **[Entity 2]**: [What it represents, relationships to other entities]
84
85---
86
87## Review & Acceptance Checklist
88*GATE: Automated checks run during main() execution*
89
90### Content Quality
91- [ ] No implementation details (languages, frameworks, APIs)
92- [ ] Focused on user value and business needs
93- [ ] Written for non-technical stakeholders
94- [ ] All mandatory sections completed
95
96### Requirement Completeness
97- [ ] No [NEEDS CLARIFICATION] markers remain
98- [ ] Requirements are testable and unambiguous  
99- [ ] Success criteria are measurable
100- [ ] Scope is clearly bounded
101- [ ] Dependencies and assumptions identified
102
103---
104
105## Execution Status
106*Updated by main() during processing*
107
108- [ ] User description parsed
109- [ ] Key concepts extracted
110- [ ] Ambiguities marked
111- [ ] User scenarios defined
112- [ ] Requirements generated
113- [ ] Entities identified
114- [ ] Review checklist passed
115
116---