gh-xbklairith-kisune-dev-workflow/skills/spec-driven-planning/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
spec-driven-planning	Use when planning new features or need structured requirements - creates feature structure, elicits EARS requirements through systematic questioning, proposes architectural approaches with trade-offs. Activates when user mentions "new feature", "requirements", "specs", "design", "architecture", or uses /dev-workflow:spec commands (create, requirements, design).	Read, Write, Glob, Grep

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:

1. Parse feature name from user input
2. Check existing features using Bash tool: ls docx/features/
3. Determine next number (NN) for feature directory
4. Create directory using Bash tool: mkdir -p docx/features/[NN-feature-name]
5. 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:

1. Ubiquitous Requirements - Always true

   • Template: "The system SHALL [requirement]"
   • Example: "The system SHALL validate all user inputs before processing"

2. 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"

3. State-Driven Requirements - Active during specific states

   • Template: "WHILE [state] the system SHALL [requirement]"
   • Example: "WHILE processing payment the system SHALL display loading indicator"

4. 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"

5. Optional Requirements - Feature toggles

   • Template: "WHERE [feature included] the system SHALL [requirement]"
   • Example: "WHERE premium subscription is active the system SHALL enable advanced analytics"

Systematic Questioning Approach:

Ask the user these questions to elicit requirements:

1. Core Functionality

   • "What is the primary purpose of this feature?"
   • "What problem does it solve?"

2. Event-Driven Requirements

   • "What user actions trigger this feature?"
   • "What system events are involved?"

3. State-Driven Requirements

   • "Are there different states or modes?"
   • "What should happen during each state?"

4. Conditional Requirements

   • "Are there different behaviors for different users/roles?"
   • "What conditions affect functionality?"

5. Performance Requirements

   • "Are there response time requirements?"
   • "What's the expected load/scale?"

6. Security Requirements

   • "What data needs protection?"
   • "Who should have access?"

7. Error Handling

   • "What can go wrong?"
   • "How should errors be handled?"

8. 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

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

Process:

1. 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.

2. 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]

3. Recommendation

   • State recommended approach
   • Provide clear reasoning
   • Explain why it best fits requirements

4. 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 code-quality 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