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

Specification Creation Skill

Overview

This skill creates technology-agnostic feature specifications following Article IV: Specification-First Development. It captures WHAT and WHY (user needs, requirements, success criteria) WITHOUT HOW (technical implementation, architecture, tech stack).

Core Workflow: Quality Gate → Intelligence Gathering → User Requirements → Specification → Automatic Planning

Automatic Workflow Progression: After creating spec.md, this skill automatically invokes /plan which chains through create-implementation-plan → generate-tasks → /audit → ready for /implement.

Announce at start: "I'm using the specify-feature skill to create a technology-agnostic specification."

Quick Reference

Workflow Files

• •@.claude/skills/specify-feature/workflows/quality-assessment.md - Phase 0: Quality gate with 5 dimensions
• •@.claude/skills/specify-feature/workflows/intelligence-gathering.md - Phase 1: Intel-first context
• •@.claude/skills/specify-feature/workflows/user-requirements.md - Phase 2: WHAT/WHY extraction
• •@.claude/skills/specify-feature/workflows/spec-generation.md - Phase 3: Create spec.md
• •@.claude/skills/specify-feature/workflows/automation.md - Phase 4-5: Reporting + automatic /plan

Example & References

• •@.claude/skills/specify-feature/examples/feature-creation-example.md - Complete walkthrough
• •@.claude/skills/specify-feature/references/specification-rules.md - Best practices and anti-patterns

Phase 0: Pre-Specification Quality Gate

See: @.claude/skills/specify-feature/workflows/quality-assessment.md

Summary:

Validate user input quality BEFORE creating specification using 5 quality dimensions (0-10 scale):

1. •Problem Clarity - Clear problem statement, pain points, measurable impact
2. •Value Proposition - Business/user value, quantified benefits, success metrics
3. •Requirements Completeness - Key capabilities, scenarios, constraints
4. •Technology-Agnostic - Zero technical details, pure WHAT/WHY focus
5. •User-Centric - User needs central, personas, user value clear

Thresholds:

• •≥ 7.0: PROCEED to Phase 1
• •5.0-6.9: CLARIFY - Request specific improvements
• •< 5.0: BLOCK - User description too vague

Why This Matters: Prevents wasting effort on vague or technically prescriptive inputs. Quality gate catches issues before specification creation.

Phase 1: Intelligence-First Context Gathering

See: @.claude/skills/specify-feature/workflows/intelligence-gathering.md

Summary:

Query project intelligence BEFORE creating specification to discover existing patterns:

Step 1.1: Auto-Number Next Feature

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

Step 1.2: Query Existing Patterns

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

Step 1.3: Understand Project Architecture

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

Token Efficiency: 85% savings vs reading full spec files

Why This Matters: Intelligence evidence ensures specifications build on existing patterns rather than duplicating or conflicting with previous work.

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

See: @.claude/skills/specify-feature/workflows/user-requirements.md

Summary:

Extract technology-agnostic requirements focusing on WHAT and WHY, not HOW.

Step 2.1: Problem Statement

• •What problem are we solving and why?
• •Who experiences this problem?
• •Current situation and pain points

Step 2.2: User Stories with Priorities

## User Story <N> - [Title] (Priority: P1/P2/P3)

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

**Why P1/P2/P3**: [Rationale for priority]
**Independent Test**: [How to validate this story works standalone]

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

Priority Levels:

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

Step 2.3: Functional Requirements

• •Core capabilities (WHAT, not HOW)
• •Data visibility and user interactions
• •Constraints and boundaries

Step 2.4: Success Criteria

• •User-centric metrics (measurable outcomes)
• •Business metrics
• •Adoption metrics

Why This Matters: Technology-agnostic requirements survive implementation changes and enable better tech stack decisions in planning phase.

Phase 3: Generate Specification with CoD^Σ Evidence

See: @.claude/skills/specify-feature/workflows/spec-generation.md

Summary:

Create specification document with intelligence evidence.

Step 3.1: Create Feature Directory

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>"
mkdir -p specs/$NEXT_NUM-$FEATURE_NAME

Step 3.2: Create Git Branch

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

Step 3.3: Generate Specification Content

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

• •YAML frontmatter (feature, created, status, priority)
• •Problem statement, user stories, functional requirements, success criteria
• •CoD^Σ Evidence Trace (intelligence queries, findings, assumptions, clarifications)
• •Edge cases

Step 3.4: Save Specification

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

Why This Matters: Evidence trace ensures all specifications have intelligence backing, not just assumptions.

Phase 4-5: Reporting and Automatic Workflow Progression

See: @.claude/skills/specify-feature/workflows/automation.md

Summary:

Report specification completion and automatically trigger implementation planning workflow.

Phase 4: Report to User

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

Intelligence Evidence: [queries + findings]
User Stories: [P1/P2/P3 counts]
Clarifications Needed: [0-3 markers]

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

Invoking /plan command now...

Phase 5: Automatic Implementation Planning

If [NEEDS CLARIFICATION] markers exist:

• •User must run clarify-specification skill
• •After clarifications, re-run specify-feature skill

If NO clarifications:

• •Automatically invoke /plan command via SlashCommand tool
• •Workflow progresses: /plan → create-implementation-plan → generate-tasks → /audit
• •User sees: spec.md → plan.md → research.md → data-model.md → tasks.md → audit report

Why This Matters: Fully automated workflow from specification to implementation-ready state. User only needs to run /feature and /implement.

Anti-Patterns to Avoid

See: @.claude/skills/specify-feature/references/specification-rules.md

Summary:

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
• •Write vague requirements ("system should be fast")

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

See: @.claude/skills/specify-feature/examples/feature-creation-example.md

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

Result:

• •Quality assessment passed (7.2/10)
• •Intelligence queries executed
• •Specification created: specs/004-auth-social-login/spec.md
• •Automatic planning triggered
• •Files created: spec.md, plan.md, research.md, data-model.md, tasks.md
• •Audit passed
• •Ready for /implement

Prerequisites

Before using this skill:

• •✅ Git repository initialized
• •✅ project-intel.mjs exists and is executable
• •✅ PROJECT_INDEX.json exists (auto-generated)
• •⚠️ Optional: product.md exists (for product-aligned features)

Dependencies

Depends On:

• •None (this skill is the entry point to SDD workflow)

Integrates With:

• •clarify-specification skill: Use after this skill if ambiguities exist
• •create-implementation-plan skill: Use after this skill (auto-invoked via /plan)

Tool Dependencies:

• •fd (file discovery for feature numbering)
• •git (branch creation, feature isolation)
• •project-intel.mjs (pattern discovery)

Next Steps

After specification completes, automatic workflow progression:

Automatic Chain (no manual intervention needed):

specify-feature (creates spec.md)
    ↓ (auto-invokes /plan)
create-implementation-plan (creates plan.md, research.md, data-model.md)
    ↓ (auto-invokes generate-tasks)
generate-tasks (creates tasks.md)
    ↓ (auto-invokes /audit)
/audit (validates consistency)
    ↓ (if PASS)
Ready for /implement

User Action Required:

• •If audit PASS: Run /implement plan.md to begin implementation
• •If audit FAIL: Fix CRITICAL issues, then re-run (audit re-validates automatically)
• •If ambiguities found: clarify-specification skill may be invoked during workflow

Commands:

• •/plan spec.md - Automatically invoked after spec creation
• •/implement plan.md - User runs after audit passes

Agent Integration

This skill orchestrates agent delegation through the automatic workflow chain.

Implementation Planning Agent

When: Automatically after spec.md is created (via /plan invocation)

Agent: implementation-planner

Delegation Method: The /plan slash command invokes the create-implementation-plan skill, which the implementation-planner agent executes.

What the Planner Receives:

• •spec.md (technology-agnostic specification)
• •Constitution requirements (Article IV compliance)
• •Project intelligence context (existing patterns via project-intel.mjs)

What the Planner Returns:

• •plan.md (implementation plan with tasks and ACs)
• •research.md (technical research and decisions)
• •data-model.md (database/state schema)

Task Tool Usage (Indirect)

This skill does NOT directly use the Task tool. Instead:

specify-feature skill
    ↓ invokes
/plan command (SlashCommand tool)
    ↓ expands to
create-implementation-plan skill
    ↓ executed by
implementation-planner agent (isolated context)

Why This Design:

• •Slash commands provide consistent user interface
• •Skills provide reusable workflows
• •Agents provide isolated context execution
• •Separation of concerns: specify-feature focuses on WHAT/WHY, planner handles HOW

Expected Workflow

1. •This skill completes: spec.md created with all requirements
2. •Automatic /plan invocation: SlashCommand tool runs /plan spec.md
3. •Planner agent engaged: Receives spec, constitution, intelligence context
4. •Planning artifacts created: plan.md, research.md, data-model.md generated
5. •Automatic task generation: generate-tasks skill creates tasks.md
6. •Automatic audit: /audit validates consistency
7. •Ready for implementation: User runs /implement plan.md if audit passes

Failure Modes

Common Failures & Solutions

1. Feature auto-numbering fails

• •Symptom: Cannot determine next feature number
• •Solution: Create specs/ directory: mkdir -p specs/
• •Workaround: Manually specify feature number (e.g., 001-feature-name)

2. Intelligence queries return no results

• •Symptom: No existing patterns found
• •Solution: This is normal for first features; continue without pattern evidence
• •Note: Intelligence is opportunistic, not required

3. Specification too technical

• •Symptom: Spec includes implementation details (React, PostgreSQL, etc.)
• •Solution: Re-run skill with explicit "WHAT/WHY only, no HOW" instruction
• •Prevention: Review @constitution.md Article IV (Specification-First)

4. Requirements unclear or incomplete

• •Symptom: [NEEDS CLARIFICATION] markers in spec
• •Solution: clarify-specification skill will be invoked automatically
• •Action: Answer max 5 structured questions to resolve ambiguities

5. Git branch creation fails

• •Symptom: Cannot create feature branch
• •Solution: Commit current changes or stash them first
• •Command: git stash && git checkout -b <feature-branch>

6. Duplicate feature numbers

• •Symptom: Feature directory already exists
• •Solution: Intelligence detected wrong next number; manually increment
• •Prevention: Ensure consistent ###-name branch naming

Related Skills & Commands

Direct Integration:

• •clarify-specification skill - Invoked when ambiguities detected
• •create-implementation-plan skill - Automatically invoked via /plan after spec
• •/feature command - User-facing command that invokes this skill

Workflow Context:

• •Position: Entry point to SDD workflow (Phase 1)
• •Triggers: User describes feature idea, mentions "I want to build", "implement", "create"
• •Output: spec.md in specs/###-feature-name/ directory
• •Next: Automatic progression to /plan → /tasks → /audit → ready for /implement

Skill Version: 1.2.0 Last Updated: 2025-10-23 Change Log:

• •v1.2.0 (2025-10-23): Refactored to progressive disclosure pattern (<500 lines)
• •v1.1.0 (2025-10-23): Added Phase 0 Pre-Specification Quality Gate
• •v1.0.0 (2025-10-22): Initial version with cross-skill references