spec-create

# 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:** ```markdown # 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] - **Rationale:** [Why beneficial] - **If omitted:** [Impact on users] ### WON'T Have (Explicitly out of scope) **FR-W1:** [Feature/capability] - **Rationale:** [Why excluded] - **Future Consideration:** [When to revisit] --- ## Scenarios and Behavior ### Scenario 1: [Happy Path Name] **Context:** [When this applies] **Given:** [Initial state] **And:** [Additional context] **When:** [User action] **And:** [Additional actions] **Then:** [Expected outcome] **And:** [Additional outcomes] **Personas:** [Who this applies to] **Priority:** MUST | SHOULD | COULD --- ### Scenario 2: [Error Case Name] **Context:** [When this applies] **Given:** [Initial state with error condition] **When:** [User action] **Then:** [Error handling outcome] **And:** [System state after error] **Personas:** [Who encounters this] **Priority:** MUST | SHOULD --- ## Constraints and Business Rules ### Business Rules **BR1:** [Rule statement] - **Applies to:** [Which scenarios] - **Enforcement:** [How validated] **BR2:** [Rule statement] ... ### Technical Constraints **TC1:** [Constraint description] - **Measurement:** [How to verify] - **Rationale:** [Why this constraint exists] ### Non-Functional Requirements (MoSCoW) **NFR-M1 (MUST):** [Requirement] - **Example:** [Concrete example] - **Measurement:** [Metrics] - **Verification:** [Testing approach] --- ## Open Questions ### Unresolved Requirements - [ ] **Q1:** [Question about requirements] - **Assigned to:** [Who will answer] - **Target Date:** [When needed] - **Blocking:** [What can't proceed without answer] ### Design Decisions Needed - [ ] **D1:** [Decision point] - **Options:** (A) ..., (B) ..., (C) ... - **Decision Maker:** [Who decides] - **Context:** [Why decision needed] ### Clarifications Required - [ ] **C1:** [What needs clarification] - **Who to ask:** [Stakeholder] - **Why it matters:** [Impact on implementation] --- ## Out of Scope **Explicitly NOT included in this specification:** 1. **[Feature/capability]** - **Reason:** [Why excluded] - **Future:** [When/if to consider] --- ## Acceptance Criteria Summary **This feature is DONE when:** - [ ] All MUST requirements (FR-M*) implemented and verified - [ ] All SHOULD requirements (FR-S*) implemented OR documented workarounds exist - [ ] All MUST scenarios pass acceptance tests - [ ] All business rules (BR*) enforced in code - [ ] All technical constraints (TC*) 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 --- ## Traceability ### Derives From (Strategic) - **Strategic Goal:** [High-level objective] - **User Need:** [Problem being solved] - **Related ADRs:** [Architecture decisions] ### Feeds Into (Tactical) - **Acceptance Tests:** [Test files/scenarios] - **Implementation Tasks:** [Task IDs or files] - **API Documentation:** [API specs or contracts] ### Related Specifications - **Dependencies:** [Specs that must be complete first] - **Dependents:** [Specs that depend on this one] - **Cross-References:** [Related features] --- ## Approval ### Reviewers | Role | Name | Date | Status | Comments | |------|------|------|--------|----------| | Implementer | [Agent] | - | ⏳ Pending | - | | Architect | Alphonso | - | ⏳ Pending | - | | Target Persona | [Name] | - | ⏳ Pending | - | | Stakeholder | [Name] | - | ⏳ Pending | - | ### Sign-Off **Final Approval:** - **Date:** [When approved] - **Approved By:** [Authority] - **Status:** Draft | Approved | Implemented --- ## Metadata **Tags:** `#feature-spec` `#[domain]` `#[milestone]` **Related Files:** - Template: `docs/templates/specifications/feature-spec-template.md` - Persona: [Links to persona documents] - ADR: [Links to relevant ADRs] - Tests: [Links to test files] **Navigation:** - 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)