Spec-Driven Planning Skill

Purpose

Guide feature planning through three structured phases: Feature Creation → Requirements (EARS) → Technical Design. This systematic approach ensures clear requirements and thoughtful design before implementation begins.

Activation Triggers

Activate this skill when:

• User says "create a new feature"

• User mentions "requirements", "specifications", or "specs"

• User uses /dev-workflow:spec command with planning options

• User asks to plan or design a feature

• User says "I need to build [feature]"

• User mentions "architecture" or "technical design"

Three-Phase Planning Workflow

Phase 1: Feature Creation

Goal: Establish feature structure and placeholder files

Process:

• Parse feature name from user input

• Check existing features using Bash tool: ls docx/features/

• Determine next number (NN) for feature directory

• Create directory using Bash tool: mkdir -p docx/features/[NN-feature-name]

• Copy templates from plugin to feature directory:

• Use Read tool: dev-workflow/templates/requirements.md

• Use Write tool: docx/features/[NN-feature-name]/requirements.md (replace [Feature Name] with actual name)

• Use Read tool: dev-workflow/templates/design.md

• Use Write tool: docx/features/[NN-feature-name]/design.md (replace [Feature Name] with actual name)

• Use Read tool: dev-workflow/templates/tasks.md

• Use Write tool: docx/features/[NN-feature-name]/tasks.md (replace [Feature Name] with actual name)

Output:

Created feature: docx/features/[NN-feature-name]/

• requirements.md (from template)
• design.md (from template)
• tasks.md (from template)

Next step: Define requirements using EARS format

User Confirmation:

"Feature structure created. Ready to define requirements?"

Phase 2: Requirements Definition (EARS Format)

Goal: Capture clear, testable requirements using EARS methodology

Brainstorming Integration (Optional):

• If user has rough idea but unclear requirements, use Skill tool to invoke: dev-workflow:brainstorming

• Helps clarify what to build vs. what's out of scope

• Explores different feature scopes through collaborative questioning

• Determines must-haves vs. nice-to-haves

How to activate:

Use Skill tool: Skill(skill: "dev-workflow:brainstorming")

EARS Format Explained:

EARS (Easy Approach to Requirements Syntax) provides five templates for unambiguous requirements:

Ubiquitous Requirements - Always true

• Template: "The system SHALL [requirement]"

• Example: "The system SHALL validate all user inputs before processing"

Event-Driven Requirements - Triggered by events

• Template: "WHEN [trigger] THEN the system SHALL [response]"

• Example: "WHEN user clicks submit THEN the system SHALL validate form data"

State-Driven Requirements - Active during specific states

• Template: "WHILE [state] the system SHALL [requirement]"

• Example: "WHILE processing payment the system SHALL display loading indicator"

Conditional Requirements - Based on conditions

• Template: "IF [condition] THEN the system SHALL [requirement]"

• Example: "IF user role is admin THEN the system SHALL show management panel"

Optional Requirements - Feature toggles

• Template: "WHERE [feature included] the system SHALL [requirement]"

• Example: "WHERE premium subscription is active the system SHALL enable advanced analytics"

Research Protocol (Before Eliciting Requirements):

Before diving into requirement questions, gather context through research:

Prior Art Research

• Use WebSearch to find similar features/products

• Query: "[feature type] best practices 2025"

• Query: "[feature type] common requirements"

Technical Documentation

• Use WebFetch on relevant technical docs, APIs, or standards

• Fetch competitor/similar product documentation

API Research (if applicable)

• Use Bash with curl to explore API endpoints

• Fetch API documentation and schemas

Document Findings

• Summarize key insights in requirements.md under "## Research Summary"

• Note patterns, anti-patterns, and industry standards discovered

🗣 Say: "Let me research similar implementations before we define requirements."

Systematic Questioning Approach:

Ask the user these questions to elicit requirements:

Core Functionality

• "What is the primary purpose of this feature?"

• "What problem does it solve?"

Event-Driven Requirements

• "What user actions trigger this feature?"

• "What system events are involved?"

State-Driven Requirements

• "Are there different states or modes?"

• "What should happen during each state?"

Conditional Requirements

• "Are there different behaviors for different users/roles?"

• "What conditions affect functionality?"

Performance Requirements

• "Are there response time requirements?"

• "What's the expected load/scale?"

Security Requirements

• "What data needs protection?"

• "Who should have access?"

Error Handling

• "What can go wrong?"

• "How should errors be handled?"

Edge Cases

• "What are the boundary conditions?"

• "What happens at extremes?"

Best Practices:

• Use "SHALL" for mandatory requirements

• Be specific and measurable (avoid "quickly", use "within 2 seconds")

• One requirement per statement

• Avoid ambiguous terms ("appropriate", "reasonable", "user-friendly")

• Use active voice

Requirement IDs & Traceability:

• Assign unique IDs to every requirement using a consistent prefix (e.g., REQ-001 ).

• Keep numbering sequential across all requirement types (functional + non-functional).

• Record the IDs directly in each requirement line so later tasks can reference them.

• Add a short traceability note indicating how tasks/design will map back to these IDs.

Output Format: Update docx/features/[NN-feature-name]/requirements.md with:

• Overview section

• Functional requirements (organized by EARS type)

• Non-functional requirements (performance, security, usability)

• Constraints

• Acceptance criteria (checkboxes)

• Out of scope items

User Confirmation:

"Requirements complete. Ready for design phase?"

Phase 3: Technical Design

Goal: Create comprehensive technical design with architectural decisions

Research Protocol (Before Design):

Before proposing architectural approaches, research solutions:

Architecture Research

• Use WebSearch: "[technology] architecture patterns 2025"

• Use WebSearch: "[problem domain] implementation approaches"

Library/Framework Research

• Use WebFetch on documentation for potential libraries

• Compare approaches used by similar projects

API Research (if applicable)

• Use WebFetch on external API documentation

• Use Bash with curl to test API endpoints

• Understand integration requirements and constraints

Document Findings

• Add "## Technical Research" section to design.md

• Include links to sources and key insights

🗣 Say: "Let me research technical approaches before proposing architecture options."

Process:

Brainstorming Integration

• Use Skill tool to invoke: dev-workflow:brainstorming for collaborative design exploration

• Explore 2-3 different architectural approaches

• Discuss trade-offs for each approach

How to activate:

Use Skill tool: Skill(skill: "dev-workflow:brainstorming")

UltraThink for Complex Designs: Before proposing technical approaches, activate deep thinking when:

• Architecture involves multiple services or complex data flows

• Trade-offs between approaches aren't obvious

• Design impacts security, performance, or scalability

• Requirements seem contradictory or incomplete

🗣 Say: "This design requires deep thinking. Let me ultrathink the architectural fundamentals before proposing approaches."

During UltraThink, question:

• Are we solving the right problem?

• What are we assuming that might be wrong?

• What could break at scale?

• What's the simplest architecture that works?

• What are the hidden costs of each approach?

• What would we do differently if starting from scratch?

After UltraThink: Present approaches with explicit reasoning about architectural trade-offs and scalability considerations.

Approach Comparison Present options with trade-offs:

Option A: [Approach Name]

• Pros: [Advantages]

• Cons: [Disadvantages]

• Complexity: Low/Medium/High

• Timeline: [Estimate]

Option B: [Approach Name]

• Pros: [Advantages]

• Cons: [Disadvantages]

• Complexity: Low/Medium/High

• Timeline: [Estimate]

Recommendation

• State recommended approach

• Provide clear reasoning

• Explain why it best fits requirements

Design Document Structure Create comprehensive design.md covering:

Architecture Overview

• How feature fits into system

• High-level component diagram (ASCII art)

Component Structure

• List components with responsibilities

• Define dependencies between components

• Specify public interfaces

Data Flow

• Step-by-step data movement

• Diagram showing flow

API Contracts

• Input/output schemas

• Error responses

• Example requests/responses

Error Handling

• Error scenarios and handling strategy

• Fallback behaviors

Security Considerations

• Authentication/authorization

• Input validation

• Data protection

Performance Considerations

• Optimization strategies

• Caching approach

• Database indexing needs

Testing Strategy

• Unit test areas

• Integration test scenarios

• E2E test workflows

Approval Gate:

"Design complete. Ready for task breakdown?"

Wait for explicit user approval before proceeding.

Next Steps

After design approval, use /dev-workflow:spec tasks or /dev-workflow:spec execute to activate the spec-driven-implementation skill, which will:

• Break down your design into TDD tasks with Red-Green-Refactor cycles

• Guide systematic execution with quality gates

• Track progress with checkbox updates

• Integrate with review and git-workflow skills

Examples

Example 1: Creating User Authentication Feature

User: "I need to add user authentication"

Assistant:

Activating spec-driven-planning skill for feature planning.

Let me create the feature structure:

Created feature: docx/features/01-user-authentication/

• requirements.md
• design.md
• tasks.md

Phase 1 Complete. Ready to define requirements?

User: "Yes"

Assistant:

Phase 2: Requirements Definition (EARS Format)

Let me ask some questions to capture clear requirements:

1. Core Functionality:

   • What authentication methods should be supported? (email/password, OAuth, etc.)
   • Should there be session management?

2. Events:

   • What happens when user tries to log in?
   • What happens when session expires?

[...continues with systematic questioning...]

Example 2: Resuming at Design Phase

User: "/dev-workflow:spec design"

Assistant:

Activating spec-driven-planning skill at Phase 3: Design

Found latest feature: docx/features/01-user-authentication/

Requirements already defined. Let me propose architectural approaches:

Option A: JWT-Based Authentication Pros: Stateless, scalable, works across services Cons: Token invalidation complexity, larger payload Complexity: Medium

Option B: Session-Based Authentication Pros: Simple invalidation, smaller cookies, familiar pattern Cons: Requires session storage, scaling challenges Complexity: Low

Recommendation: Option A (JWT-Based) Reasoning: Better for microservices, future-proof, industry standard

Proceed with JWT-based design?

Notes

• Always request explicit approval between phases

• Use EARS format strictly for requirements

• Focus on "what" and "how", not "doing"

• Create clear, complete documentation before implementation

• Explore multiple architectural options before recommending one

• Wait for user approval before activating implementation skill