spec-create

name	spec-create
description	Create functional specification for complex features: detailed requirements, user scenarios, constraints, acceptance criteria. Bridges strategic intent and implementation with MoSCoW prioritization and Given/When/Then scenarios.
version	1.0.0
type	specification
category	documentation

Spec Create: Specification-Driven Development

Create comprehensive functional specifications for complex features before implementation. Specifications translate requirements into concrete implementation guidance while remaining independent of specific acceptance tests or architectural decisions.

Instructions

Initialize as Scribe Sally or Analyst Annie to create a specification.

1. Identify scope:

   • Feature name and purpose
   • Target personas (see docs/audience/)
   • Related ADRs or design documents

2. Gather requirements:

   • Functional requirements (MUST/SHOULD/COULD/WON'T)
   • Non-functional requirements (performance, security, usability)
   • Business rules and constraints
   • Edge cases and error scenarios

3. Write specification using template:

# Specification: [Feature Name]

**Status:** Draft
**Created:** YYYY-MM-DD
**Author:** [Agent Name]
**Stakeholders:** [Who needs to review/approve]
**Target Personas:** [List from docs/audience/]

---

## User Story

**As a** [persona]
**I want** [capability]
**So that** [benefit]

**Alternative: Acceptance Criterion Format**
**Given** [context]
**When** [action]
**Then** [outcome]
**Unless** [exception]

---

## Overview

Brief description of the feature (2-3 paragraphs):
- What problem does this solve?
- Why is it needed now?
- What constraints exist?

**Related Documentation:**
- Related ADRs: [links]
- Related Specifications: [links]
- Background: [context documents]

---

## Functional Requirements (MoSCoW)

### MUST Have (Critical - Feature unusable without these)

**FR-M1:** System MUST [requirement]
- **Rationale:** [Why this is critical]
- **Personas Affected:** [Primary users]
- **Success Criteria:** [How to verify]

**FR-M2:** System MUST [requirement]
...

### SHOULD Have (Important - Feature degraded without these)

**FR-S1:** System SHOULD [requirement]
- **Rationale:** [Why important]
- **Workaround if omitted:** [Alternative approach]

### COULD Have (Nice to have - Enhances experience)

**FR-C1:** System COULD [requirement]
  [Why beneficial]
  [Impact on users]



 [Feature/capability]
  [Why excluded]
  [When to revisit]

---





 [When this applies]

 [Initial state]
 [Additional context]
 [User action]
 [Additional actions]
 [Expected outcome]
 [Additional outcomes]

 [Who this applies to]
 MUST | SHOULD | COULD

---



 [When this applies]

 [Initial state with error condition]
 [User action]
 [Error handling outcome]
 [System state after error]

 [Who encounters this]
 MUST | SHOULD

---





 [Rule statement]
  [Which scenarios]
  [How validated]

 [Rule statement]
...



 [Constraint description]
  [How to verify]
  [Why this constraint exists]



 [Requirement]
  [Concrete example]
  [Metrics]
  [Testing approach]

---





 [ ]  [Question about requirements]
  [Who will answer]
  [When needed]
  [What can't proceed without answer]



 [ ]  [Decision point]
  (A) ..., (B) ..., (C) ...
  [Who decides]
  [Why decision needed]



 [ ]  [What needs clarification]
  [Stakeholder]
  [Impact on implementation]

---





 
  [Why excluded]
  [When/if to consider]

---





 [ ] All MUST requirements (FR-M) implemented OR documented workarounds exist
 [ ] All MUST scenarios pass acceptance tests
 [ ] All business rules (BR) met and verified
 [ ] Open questions resolved or documented for future iterations
 [ ] Acceptance tests derived from scenarios are passing
 [ ] Documentation updated
 [ ] Target personas have validated feature meets their needs

---




  [High-level objective]
  [Problem being solved]
  [Architecture decisions]


  [Test files/scenarios]
  [Task IDs or files]
  [API specs or contracts]


  [Specs that must be complete first]
  [Specs that depend on this one]
  [Related features]

---





| Role | Name | Date | Status | Comments |
|------|------|------|--------|----------|
| Implementer | [Agent] | - | ⏳ Pending | - |
| Architect | Alphonso | - | ⏳ Pending | - |
| Target Persona | [Name] | - | ⏳ Pending | - |
| Stakeholder | [Name] | - | ⏳ Pending | - |




  [When approved]
  [Authority]
  Draft | Approved | Implemented

---



   


 Template: 
 Persona: [Links to persona documents]
 ADR: [Links to relevant ADRs]
 Tests: [Links to test files]


 Previous Spec: [Link]
 Next Spec: [Link]
 Parent Spec: [Link if hierarchical]

4. Location:

   • Save in specifications/[domain]/[feature-name].md
   • Create domain directory if needed

5. Review cycle:

   • Draft: Initial creation
   • Review: Stakeholder feedback
   • Approved: Ready for implementation
   • Implemented: Feature complete, spec frozen

When to Create Specifications

Create Spec For ✅

• Complex features spanning multiple components
• Features requiring cross-team coordination
• API contracts needing stakeholder agreement
• Features with security or performance constraints
• Workflows requiring step-by-step definition
• Features with multiple personas

Skip Spec For ❌

• Simple CRUD operations (use acceptance tests directly)
• Bug fixes (use directive 028: test-first bug fixing)
• Architectural decisions (use ADRs instead)
• Internal utilities (document in code)

Spec vs. ADR vs. Acceptance Test

Document Type	Purpose	When	Lifecycle
Specification	Detailed functional requirements	Complex features	Living (evolves during dev)
ADR (Directive 018)	Architectural decision rationale	Significant tech choices	Immutable once accepted
Acceptance Test (Directive 016)	Executable behavioral contract	All user-facing features	Frozen once passing

Use all three together:

1. Spec defines WHAT to build (requirements, scenarios)
2. ADR explains HOW technical choices were made (architecture)
3. Acceptance Tests verify DONE (executable scenarios)

Example Usage

User: We need to implement a real-time execution dashboard for the LLM service

Agent (Scribe Sally): Creating specification...

1. Identified scope:
   - Feature: Real-Time Execution Dashboard
   - Personas: Software Engineer (primary), Cost-Conscious Developer
   - Related ADRs: ADR-032 (dashboard architecture)

2. Gathered requirements:
   - MUST: Real-time task updates via WebSocket (<100ms latency)
   - MUST: Cost tracking (today/month/total)
   - MUST: File-based task tracking (preserve Git audit trail)
   - SHOULD: Metrics visualization (charts)
   - COULD: Task filtering by agent

3. Created specification:
   - Location: specifications/llm-dashboard/real-time-execution-dashboard.md
   - Format: MoSCoW requirements (8 MUST, 5 SHOULD, 4 COULD, 4 WON'T)
   - Scenarios: 6 scenarios (4 happy path, 2 error cases)
   - Constraints: WebSocket latency <100ms, localhost-only
   - Traceability: Links to ADR-032, telemetry API, task files

4. Status: DRAFT → awaiting stakeholder review

Next steps:
- Review with Human-in-Charge (stakeholder)
- Architect review (ADR alignment check)
- Approve and mark ready for implementation
- Derive acceptance tests from scenarios

Integration with Workflow

Before Implementation:

1. /spec-create    ← Create specification
2. Review with stakeholders
3. Architect review (ADR alignment)
4. Approve specification
5. /iterate        ← Implement using spec as guide

During Implementation:

- Refer to spec for requirements
- Update spec if understanding evolves
- Derive acceptance tests from scenarios
- Link implementation tasks to spec sections

After Implementation:

- Mark spec status: Implemented
- Freeze spec (becomes reference doc)
- Archive in specifications/ directory

Related Skills

• /iterate - Implement features defined in specifications
• /review - Architect reviews spec for ADR alignment
• architect-adr - Create ADR for architectural decisions
• target-audience-fit - Validate spec addresses target personas

References

• Directive 034: .github/agents/directives/034_spec_driven_development.md
• Approach: .github/agents/approaches/spec-driven-development.md
• Template: docs/templates/specifications/feature-spec-template.md
• Directive 016: .github/agents/directives/016_acceptance_test_driven_development.md (ATDD)
• Directive 018: .github/agents/directives/018_traceable_decisions.md (ADRs)
• Directive 022: .github/agents/directives/022_audience_oriented_writing.md (Target personas)