Skip to content

spec-template.md

Latest commit

 

History

History
161 lines (119 loc) · 7.2 KB

spec-template.md

File metadata and controls

161 lines (119 loc) · 7.2 KB

Feature Specification: [FEATURE NAME]

User Scenarios & Testing (mandatory)

Primary User Story

[Describe the main user journey in plain language]

Acceptance Scenarios

  1. Given [initial state], When [action], Then [expected outcome]
  2. Given [initial state], When [action], Then [expected outcome]

Edge Cases

  • What happens when [boundary condition]?
  • How does system handle [error scenario]?

Requirements (mandatory)

Functional Requirements

ID Requirement
FR-001 System MUST [specific capability, e.g., "allow users to create accounts"]
FR-002 System MUST [specific capability, e.g., "validate email addresses"]
FR-003 Users MUST be able to [key interaction, e.g., "reset their password"]
FR-004 System MUST [data requirement, e.g., "persist user preferences"]
FR-005 System MUST [behavior, e.g., "log all security events"]
FR-006 System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
FR-007 System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

Non-Functional Requirements

ID Requirement
NFR-001 System MUST respond within [specific time, e.g., "500ms for 95th percentile"]
NFR-002 System MUST handle [specific load, e.g., "1000 concurrent users"]
NFR-003 System MUST maintain [availability target, e.g., "99.9% uptime"]
NFR-004 System MUST scale to [capacity limit, e.g., "10,000 transactions per second"]
NFR-005 System MUST recover within [time period, e.g., "5 minutes after failure"]
NFR-006 System MUST encrypt data [NEEDS CLARIFICATION: encryption scope not specified - at rest, in transit, both?]
NFR-007 System MUST maintain audit logs for [NEEDS CLARIFICATION: retention period not specified]

Quality Attributes Addressed

Attribute Target Metric
Performance [e.g., "Response time < 200ms", "Throughput > 5000 TPS"]
Scalability [e.g., "Support 100,000 concurrent users", "Linear scaling to 10 nodes"]
Availability [e.g., "99.95% uptime", "Max 4 hours downtime per year"]
Reliability [e.g., "MTBF > 720 hours", "Error rate < 0.01%"]
Security [e.g., "OWASP Top 10 compliant", "SOC 2 Type II certified"]
Maintainability [e.g., "Code coverage > 80%", "Cyclomatic complexity < 10"]
Usability [e.g., "Task completion time < 2 minutes", "User satisfaction > 4.5/5"]

Constraints (include if applicable)

Constraint Description
[Constraint 1] [Limitation or restriction, e.g., "Must run on Windows Server 2019+"]
[Constraint 2] [Compliance requirement, e.g., "Must comply with GDPR"]

Key Entities (include if feature involves data)

Entity Description
[Entity 1] [What it represents, key attributes without implementation]
[Entity 2] [What it represents, relationships to other entities]

Feature Branch: [###-feature-name] Created: [DATE] Status: Draft Input: User description: "$ARGUMENTS"

Execution Flow (main)

  1. Parse user description from Input → If empty: ERROR "No feature description provided"
  2. Extract key concepts from description → Identify: actors, actions, data, constraints
  3. For each unclear aspect: → Mark with [NEEDS CLARIFICATION: specific question]
  4. Fill User Scenarios & Testing section → If no clear user flow: ERROR "Cannot determine user scenarios"
  5. Generate Functional Requirements → Each requirement must be testable → Mark ambiguous requirements
  6. Identify Key Entities (if data is involved)
  7. Run Review Checklist → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties" → If implementation details found: ERROR "Remove tech details"
  8. Return: SUCCESS (spec ready for planning)

⚡ Quick Guidelines

  • ✅ Focus on WHAT users need and WHY
  • ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
  • 👥 Written for business stakeholders, not developers

Section Requirements

  • Mandatory sections: Must be completed for every feature
  • Optional sections: Include only when relevant to the feature
  • When a section doesn't apply, remove it entirely (don't leave as "N/A")

For AI Generation

When creating this spec from a user prompt:

  1. Mark all ambiguities: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
  2. Don't guess: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
  3. Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
  4. Common underspecified areas:
    • User types and permissions
    • Data retention/deletion policies
    • Performance targets and scale
    • Error handling behaviors
    • Integration requirements
    • Security/compliance needs

Review & Acceptance Checklist

GATE: Automated checks run during main() execution

Content Quality

  • No implementation details (languages, frameworks, APIs)
  • Focused on user value and business needs
  • Written for non-technical stakeholders
  • All mandatory sections completed

Requirement Completeness

  • No [NEEDS CLARIFICATION] markers remain
  • Requirements are testable and unambiguous
  • Success criteria are measurable
  • Scope is clearly bounded
  • Dependencies and assumptions identified

Execution Status

Updated by main() during processing

  • User description parsed
  • Key concepts extracted
  • Ambiguities marked
  • User scenarios defined
  • Requirements generated
  • Entities identified
  • Review checklist passed