Specification Creation

@.claude/shared-imports/constitution.md @.claude/shared-imports/CoD_Σ.md @.claude/templates/feature-spec.md

Specification Creation

Purpose: Generate technology-agnostic feature specifications (WHAT/WHY only, no HOW) with intelligence-backed evidence and structured user stories.

Constitutional Authority: Article IV (Specification-First Development), Article I (Intelligence-First Principle), Article II (Evidence-Based Reasoning)

Phase 1: Intelligence-First Context Gathering

MANDATORY: Execute intelligence queries BEFORE any file operations.

Step 1.1: Auto-Number Next Feature

!`fd --type d --max-depth 1 '^[0-9]{3}-' specs/ 2>/dev/null | sort | tail -1`

Extract highest existing feature number, increment by 1 for next feature.

Example:

• Last feature: specs/003-auth-system
• Next number: 004

Step 1.2: Query Existing Patterns

!`project-intel.mjs --search "<user-keywords>" --type md --json > /tmp/spec_intel_patterns.json`

Search for related features, similar requirements, existing patterns.

Save evidence to /tmp/spec_intel_patterns.json for CoD^Σ tracing.

Step 1.3: Understand Project Architecture

!`project-intel.mjs --overview --json > /tmp/spec_intel_overview.json`

Get project structure, tech stack, existing components to inform requirements.

Phase 2: Extract User Requirements (WHAT/WHY Only)

Article IV Mandate: Specifications MUST be technology-agnostic.

Step 2.1: Problem Statement

Extract from user description:

• What problem are they trying to solve?
• Why is this needed?
• Who will use this?
• What value does it provide?

NO IMPLEMENTATION DETAILS: No tech stack, no architecture, no "how to build it".

Step 2.2: User Stories with Priorities

Organize requirements as user stories:

Format:

## User Story 1 - [Title] (Priority: P1)

**As a** [user type]
**I want to** [capability]
**So that** [value/benefit]

**Why P1**: [Rationale for priority]

**Independent Test**: [How to validate this story works standalone]

**Acceptance Scenarios**:
1. **Given** [state], **When** [action], **Then** [outcome]
2. **Given** [state], **When** [action], **Then** [outcome]

Priority Levels:

• P1: Must-have for MVP (core value)
• P2: Important but not blocking (enhances P1)
• P3: Nice-to-have (can be deferred)

Requirement: Each story MUST be independently testable (Article VII).

Step 2.3: Functional Requirements (Technology-Agnostic)

Document as testable requirements:

- **FR-001**: System MUST [specific capability]
- **FR-002**: Users MUST be able to [interaction]
- **FR-003**: System MUST [behavior]

Mark Unknowns:

- **FR-004**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified]

Maximum 3 [NEEDS CLARIFICATION] markers - use sparingly, clarify rest through user dialogue.

Phase 3: Generate Specification with CoD^Σ Evidence

Step 3.1: Create Feature Directory Structure

NEXT_NUM=$(printf "%03d" $(($(fd --type d --max-depth 1 '^[0-9]{3}-' specs/ 2>/dev/null | wc -l) + 1)))
FEATURE_NAME="<derived-from-user-description>"  # Lowercase, hyphenated, 2-4 words
mkdir -p specs/$NEXT_NUM-$FEATURE_NAME

Step 3.2: Create Git Branch (if git repo)

if git rev-parse --git-dir >/dev/null 2>&1; then
    git checkout -b "$NEXT_NUM-$FEATURE_NAME"
fi

Step 3.3: Write Specification

Use @.claude/templates/feature-spec.md structure with:

1. YAML Frontmatter:

   ---
   feature: <number>-<name>
   created: <YYYY-MM-DD>
   status: Draft
   priority: P1
   ---
   

2. Problem Statement: What problem are we solving and why?

3. User Stories: From Step 2.2 (prioritized, independently testable)

4. Functional Requirements: From Step 2.3 (technology-agnostic)

5. Success Criteria: Measurable outcomes (not technical metrics)

6. CoD^Σ Evidence Trace:

   Intelligence Queries:
   - project-intel.mjs --search "<keywords>" → /tmp/spec_intel_patterns.json
     Findings: [file:line references to similar features]
   - project-intel.mjs --overview → /tmp/spec_intel_overview.json
     Context: [existing architecture patterns]
   
   Assumptions:
   - [ASSUMPTION: rationale based on intelligence findings]
   
   Clarifications Needed:
   - [NEEDS CLARIFICATION: specific question]
   

7. Edge Cases: Boundary conditions, error scenarios

Step 3.4: Save Specification

Write specs/$NEXT_NUM-$FEATURE_NAME/spec.md

Phase 4: Report to User

Output Format:

✓ Feature specification created: specs/<number>-<name>/spec.md

Intelligence Evidence:
- Queries executed: project-intel.mjs --search, --overview
- Patterns found: <file:line references>
- Related features: <existing feature numbers>

User Stories:
- P1 stories: <count> (MVP scope)
- P2 stories: <count> (enhancements)
- P3 stories: <count> (future)

Clarifications Needed:
- [NEEDS CLARIFICATION markers if any, max 3]

**Automatic Next Steps**:
1. If clarifications needed: Use clarify-specification skill
2. Otherwise: **Automatically create implementation plan**

Invoking /plan command now...

[Plan creation, task generation, and audit will proceed automatically]

Phase 5: Automatic Implementation Planning

DO NOT ask user to trigger planning - this is automatic workflow progression (unless clarifications needed).

Step 5.1: Check for Clarifications

If [NEEDS CLARIFICATION] markers exist:

• Do NOT proceed to planning
• Report clarifications needed to user
• User must run clarify-specification skill or provide answers
• After clarifications, re-run specify-feature skill

If NO clarifications (or max 0-1 minor ones):

• Proceed automatically to implementation planning

Step 5.2: Invoke /plan Command

Instruct Claude:

"Specification is complete. Automatically create the implementation plan:

Run: /plan specs/$FEATURE/spec.md

This will:

1. Create implementation plan with tech stack selection
2. Generate research.md, data-model.md, contracts/, quickstart.md
3. Define ≥2 acceptance criteria per user story
4. Automatically invoke generate-tasks skill
5. Automatically invoke /audit quality gate

The entire workflow from planning → tasks → audit happens automatically. No manual intervention needed."

Step 5.3: Workflow Automation

After /plan is invoked, the automated workflow proceeds:

/plan specs/$FEATURE/spec.md
  ↓ (automatic)
create-implementation-plan skill
  ↓ (automatic)
generate-tasks skill
  ↓ (automatic)
/audit $FEATURE
  ↓
Quality Gate Result: PASS/FAIL

User sees:

• spec.md created ✓
• plan.md created ✓
• tasks.md created ✓
• audit report generated ✓
• Implementation readiness status

User only needs to:

• Review audit results
• Fix any CRITICAL issues (if audit fails)
• Or proceed with /implement plan.md (if audit passes)

Note: This completes specification creation. Next steps happen automatically unless clarifications are needed.

**Constitutional Compliance**:
- ✓ Article I: Intelligence queries executed before file operations
- ✓ Article II: CoD^Σ trace with evidence saved to /tmp/*.json
- ✓ Article IV: Specification is technology-agnostic (WHAT/WHY only)
- ✓ Article VII: User stories are independently testable

---

## Anti-Patterns to Avoid

**DO NOT**:
- Include tech stack choices in specification
- Design architecture or data models
- Specify implementation details ("use React hooks", "create API endpoint")
- Create more than 3 [NEEDS CLARIFICATION] markers (clarify through dialogue first)
- Write vague requirements ("system should be fast" → specify "p95 latency < 200ms")

**DO**:
- Focus on user value and business requirements
- Make requirements testable and measurable
- Prioritize user stories (P1, P2, P3)
- Document evidence from intelligence queries
- Limit unknowns (max 3 [NEEDS CLARIFICATION])

---

## Example Execution

**User Input**: "I want to build a user authentication system with social login options"

**Execution**:

1. **Intelligence Queries**:
   ```bash
   fd --type d --max-depth 1 '^[0-9]{3}-' specs/
   # Output: specs/001-dashboard, specs/002-api, specs/003-reporting
   # Next: 004

   project-intel.mjs --search "auth login" --type tsx --json
   # Findings: src/components/Login.tsx:12-45 (existing login form)
   #           src/utils/auth.ts:23 (auth helper functions)

2. Extract Requirements:

   Problem: Users need to securely access their accounts
   Why: Enable personalized experiences and data security
   Who: End users, administrators
   Value: Secure access, convenience
   
   User Stories:
   - P1: Basic email/password authentication
   - P2: Social login (Google, GitHub)
   - P3: Two-factor authentication
   

3. Create Feature:

   mkdir -p specs/004-user-authentication
   git checkout -b 004-user-authentication
   

4. Write Spec with CoD^Σ evidence, user stories, requirements

5. Report:

   ✓ Feature specification created: specs/004-user-authentication/spec.md
   
   Intelligence Evidence:
   - Found existing: src/components/Login.tsx:12-45, src/utils/auth.ts:23
   - Pattern: Email/password already partially implemented
   
   User Stories: 3 total (1 P1, 1 P2, 1 P3)
   
   Next: Run clarify-specification skill or create-implementation-plan skill
   

Skill Version: 1.0.0 Last Updated: 2025-10-19