Specification Progress:
- [ ] Step 1: Identify specification type and scope
- [ ] Step 2: Gather requirements through structured questions
- [ ] Step 3: Organize and structure collected information
- [ ] Step 4: Create specification document
- [ ] Step 5: Validate for completeness and clarity
- [ ] Step 6: Review and finalize

// Validation Checklist
const validation = {
  clarity: [
    'Are all technical terms defined?',
    'Are requirements specific and measurable?',
    'Is the language clear and unambiguous?',
  ],
  completeness: [
    'Are all sections filled out?',
    'Are dependencies identified?',
    'Are edge cases addressed?',
    'Are acceptance criteria defined?',
  ],
  consistency: [
    'Do different sections align with each other?',
    'Are naming conventions consistent?',
    'Are similar requirements handled similarly?',
  ],
  feasibility: [
    'Are requirements technically achievable?',
    'Are timelines realistic?',
    'Are resources adequate?',
  ],
};

Requirement: User Authentication
The system shall implement JWT-based authentication with the following requirements:

1. Login endpoint: POST /api/auth/login
   - Input: { email: string, password: string }
   - Output: { token: string, expiresIn: number, user: UserObject }
   - Response time: < 200ms (p95)

2. Token expiration: 24 hours
3. Password requirements:
   - Minimum 8 characters
   - Must contain: uppercase, lowercase, number, special character

4. Rate limiting: 5 failed attempts per email per 15 minutes
5. Security: Passwords hashed with bcrypt (cost factor: 12)

Acceptance Criteria:
- User can log in with valid credentials
- Invalid credentials return 401 with error message
- Expired tokens are rejected with 401
- Rate limit blocks after 5 failed attempts

Requirement: User Login
Users should be able to log in to the system. The login should be secure
and fast. Use industry best practices.

// Problems:
// - "secure" is vague
// - "fast" is not quantified
// - "best practices" is undefined
// - No acceptance criteria
// - No error handling specified
// - No technical details

# [Feature Name] - Product Specification

## Overview
[One-paragraph summary of what this feature does and why it matters]

## Problem Statement
[What user problem does this solve?]

## User Stories
As a [user type], I want to [action] so that [benefit]

## Requirements
### Must Have (P0)
- [Critical requirement 1]
- [Critical requirement 2]

### Should Have (P1)
- [Important requirement 1]

### Nice to Have (P2)
- [Optional enhancement 1]

## User Flows
[Step-by-step user interactions]

## Success Metrics
[How will we measure success?]

## Out of Scope
[What this does NOT include]

# [System/Feature Name] - Technical Specification

## Architecture Overview
[High-level system design]

## Components
### Component A
- Responsibility: [What it does]
- Technology: [Stack used]
- Dependencies: [What it depends on]
- API: [Interfaces it exposes]

## Data Models
[Database schemas, entities]

## API Endpoints
[If applicable]

## Security Considerations
[Authentication, authorization, data protection]

## Performance Requirements
[Latency, throughput, scalability targets]

## Error Handling
[How errors are handled and reported]

## Testing Strategy
[Unit, integration, e2e testing approach]

## Deployment
[How it will be deployed and configured]

# [Feature Name] - Design Specification

## Design Goals
[What experience are we creating?]

## User Personas
[Who are we designing for?]

## User Flows
[Visual or text-based flow diagrams]

## Component Library
[What UI components are used?]

## Visual Design
- Colors: [Palette]
- Typography: [Font families, sizes]
- Spacing: [Grid system]
- Icons: [Icon set]

## Interaction Patterns
[How users interact with elements]

## Responsive Behavior
[Mobile, tablet, desktop breakpoints]

## Accessibility
- WCAG Level: [A, AA, AAA]
- Keyboard navigation: [Requirements]
- Screen reader support: [Requirements]
- Color contrast: [Ratios]

## States
[Default, hover, active, disabled, error states]

# [API Name] - API Specification

## Base URL
https://api.example.com/v1

## Authentication
[OAuth 2.0, API Key, JWT, etc.]

## Endpoints

### GET /resource
**Description:** [What this endpoint does]

**Request:**
- Headers: [Required headers]
- Query params: [Parameters]
- Example:

**Response:**
- Status codes: [200, 400, 401, 404, 500]
- Body schema:
```json
{
  "id": "string",
  "name": "string",
  "created_at": "ISO8601 timestamp"
}

## Gap Identification

When reviewing requirements, actively look for:

**Missing Information:**
- Undefined error scenarios
- Unspecified performance requirements
- Missing user flows or interaction details
- Unclear data ownership
- Undefined integration points

**Ambiguities:**
- Subjective terms without definitions ("fast", "easy", "secure")
- Conflicting requirements
- Unclear priorities
- Vague success criteria

**Inconsistencies:**
- Different terminology for same concept
- Conflicting timelines
- Contradictory requirements

**When gaps are found:**
1. Document the gap clearly
2. Formulate specific questions to fill the gap
3. Get answers from stakeholders
4. Update specification
5. Re-validate

## Specification Formats

### Markdown Format
Best for: Internal documentation, version control, developer-focused specs

**Advantages:**
- Easy to read and write
- Version control friendly
- Supports code blocks and tables
- Can be rendered as HTML

### PDF Format
Best for: Client deliverables, formal sign-off, presentations

**Advantages:**
- Professional appearance
- Consistent rendering across platforms
- Can include rich graphics

### OpenAPI/Swagger Format
Best for: API specifications

**Advantages:**
- Machine-readable
- Auto-generates documentation
- Supports testing tools
- Industry standard

### Confluence/Notion Format
Best for: Team collaboration, living documents

**Advantages:**
- Real-time collaboration
- Rich media support
- Comments and discussions
- Easy to organize

## Tips for Effective Specification Creation

1. **Start with the problem, not the solution**
   - Understand the "why" before the "what"
   - Validate the problem exists

2. **Use concrete examples**
   - Include actual data samples
   - Show input/output examples
   - Demonstrate edge cases

3. **Define acceptance criteria upfront**
   - Make success measurable
   - Use specific, testable criteria

4. **Iterate early and often**
   - Share drafts for feedback
   - Validate assumptions
   - Refine based on questions

5. **Keep stakeholders aligned**
   - Regular check-ins during creation
   - Document decisions and rationale
   - Get sign-off on major decisions

6. **Version your specifications**
   - Track changes over time
   - Document what changed and why
   - Maintain history

7. **Link related specifications**
   - Reference dependencies
   - Cross-link related features
   - Maintain traceability

## When to Use This Skill

Use specification creation when:
- Starting a new project or feature
- Converting client conversations into formal requirements
- Documenting an existing system
- Preparing for development handoff
- Resolving ambiguous or conflicting requirements
- Creating API or integration documentation
- Defining design systems or component libraries

Specifications are especially valuable for:
- Complex features with multiple stakeholders
- Projects requiring formal approval or sign-off
- Systems with compliance requirements
- Features requiring cross-team coordination
- Long-term projects needing documentation