Feature Design

Transform rough feature ideas into detailed requirements and technical design documents through an iterative, user-collaborative process.

Overview

This skill implements a Spec-Driven Development (SDD) workflow that systematically:

1. Captures and refines feature requirements using EARS (Easy Approach to Requirements Syntax)
2. Validates requirements against INCOSE semantic quality rules
3. Creates technical design documents with architecture, components, and implementation plans

Glossaries

EARS (Easy Approach to Requirements Syntax)

EARS provides standardized templates for writing clear, unambiguous requirements:

INCOSE Semantic Quality Rules

Requirements must comply with these quality rules:

• Active voice - Clearly state who does what
• No vague terms - Avoid "quickly", "adequate", "user-friendly"
• No escape clauses - Avoid "where possible", "if feasible"
• No negative statements - Avoid "SHALL NOT" (rephrase positively)
• One thought per requirement - Single, testable concept
• Explicit conditions - Measurable criteria and thresholds
• Consistent terminology - Use defined terms from glossary
• No pronouns - Avoid "it", "them", "this"
• No absolutes - Avoid "never", "always", "100%"
• Solution-free - Focus on what, not how

Document Templates

Requirements Document (requirements.md)

# Requirements Document

## Introduction

[Summary of the feature/system]

## Glossary

- **System/Term**: [Definition]

## Requirements

### Requirement 1

**User Story:** AS [role], I want [feature], so that [benefit]

#### Acceptance Criteria

1. WHEN [event], [system] SHALL [response]
2. WHILE [state], [system] SHALL [response]
3. IF [unwanted event], [system] SHALL [response]
... (2-5 EARS definitions per requirement)

[Repeat for other requirements]

Design Document (design.md)

# [Feature Title]

Feature Name: feature-name
Updated: yyyy-mm-dd

## Description

[Feature description]

## Architecture

[Mermaid diagrams as needed]
[Architecture explanation]

## Components and Interfaces

[Component and interface descriptions]

## Data Models

[Data structure descriptions]

## Correctness Properties

[Invariants and constraints]

## Error Handling

[Error scenarios and handling strategies]

## Test Strategy

[Testing approach and coverage]

## References

[^1]: (Website) - [Page description](URL)
[^2]: (Filename#Lnnn) - [File link](relative/path)

Workflow

Phase 1: Requirements Generation

1. Initialize Feature
   • Generate a short feature name in kebab-case format (e.g., user-authentication)
   • Create directory specs/{FEATURE_NAME}/
2. Gather Context
   • Read project documentation from docs/ if available:
     • INDEX.md - Project overview
     • ARCHITECTURE.md - System architecture
   • Scan specs/*/ for related historical requirements
   • Understand existing code structure
3. Generate Initial Requirements
   • Decompose the feature idea into user stories
   • Apply EARS patterns to each acceptance criterion
   • Validate against INCOSE quality rules
   • Write to specs/{FEATURE_NAME}/requirements.md
4. Iterate with User
   • Present requirements document to user
   • Ask clarifying questions (maximum 3 questions per round)
   • Provide options with reasonable defaults
   • Update document based on feedback
5. Special Handling for Parsers/Serializers
   • Explicitly list all parsers and serializers as requirements
   • Add pretty-printer requirements for each parser
   • Include round-trip validation in acceptance criteria

Phase 2: Technical Design

1. Initialize Design Document
   • Get current date via date '+%Y-%m-%d'
   • Create feature name with date prefix (e.g., 2025-01-15-user-authentication)
   • Create initial design outline in specs/{FEATURE_NAME}/design.md
2. Gather Technical Context
   • Read docs/INDEX.md and docs/ARCHITECTURE.md
   • Analyze project structure and existing patterns
   • Review related specifications in specs/
3. Generate Design Document
   • Include all required sections:
     • Description
     • Architecture (with Mermaid diagrams)
     • Components and Interfaces
     • Data Models
     • Correctness Properties
     • Error Handling
     • Test Strategy
   • Ensure design addresses all requirements from Phase 1
   • Highlight design decisions and rationale
4. Iterate with User
   • Present design document to user
   • Ask technical questions (maximum 3 per round)
   • Update based on feedback
5. Finalize
   • Commit changes with git commit
   • Push to remote with git push
   • Summarize deliverables to user

Decision Points

During the workflow, ask the user about:

Output Files

specs/{FEATURE_NAME}/
├── requirements.md    # EARS-compliant requirements
└── design.md          # Technical design specification

Notes

• All communication with users must use the project's configured language
• Maximum 3 clarifying questions per iteration round
• Always validate requirements against both EARS and INCOSE rules
• Correct non-compliant user inputs and explain corrections
• Design documents should be solution-agnostic where possible
• Include Mermaid diagrams for complex architectures
• Reference specific files with line numbers when applicable