Spec Author Skill

Create and validate specification documents following project standards. This skill creates specs for users based on their requests while ensuring proper structure, completeness, and quality.

How This Skill Works

When a user asks for a spec to be created:

1. Clarify Requirements - Use AskUserQuestion to understand scope, audience, and detail level
2. Research Context - Read related specs, codebase, and existing documentation
3. Read the Guide - Always consult guides/{spec-type}.md for detailed instructions
4. Generate from Template - Use scripts/generate-spec.sh to create the initial structure
5. Fill Content Properly - Follow template structure and guide instructions precisely
6. Validate & Fix - Run validation tools and fix all issues before completion
7. Review for Quality - Ensure all sections have meaningful, user-written content

11 Specification Types

Type	ID Format	Purpose	Read Guide When
Business Requirement	brd-XXX	Capture business problems, value, and user needs	Planning a new feature from business perspective
Technical Requirement	prd-XXX	Translate business needs into technical specs	Defining how to build what business requires
Design Document	des-XXX	Detailed architecture and technical design	Making major architectural decisions
Component	cmp-XXX	Specify individual services/components	Documenting a microservice or major component
API Contract	api-XXX	Define REST endpoints and data formats	Designing API for parallel frontend/backend work
Data Model	data-XXX	Define entities, fields, relationships	Planning database schema or data structure
Plan	pln-XXX	Implementation roadmap with phases and timeline	Organizing work into phases for execution
Milestone	mls-XXX	Define delivery checkpoints with success criteria	Setting specific completion targets
Flow Schematic	flow-XXX	Document workflows and process flows	Illustrating user/system interactions
Deployment Procedure	deploy-XXX	Step-by-step production deployment instructions	Creating operational runbooks
Configuration Schema	config-XXX	Document all configurable parameters	Defining how system is configured

Quick Start

# 1. Create spec from template
scripts/generate-spec.sh <type> <id>
# Example: scripts/generate-spec.sh business-requirement brd-001-export

# 2. Read the corresponding guide
# Example: guides/business-requirement.md

# 3. Fill in sections following the guide

# 4. Validate completeness
scripts/validate-spec.sh docs/specs/<type>/<id>.md

# 5. Fix any issues
scripts/check-completeness.sh docs/specs/<type>/<id>.md

Note: Specs are now organized in folders by type under docs/specs/:

• docs/specs/business-requirement/ - Business requirement documents
• docs/specs/technical-requirement/ - Technical requirement documents
• docs/specs/design-document/ - Design documents
• And so on for each spec type...

How Specs Connect

Specs flow together when implementing a feature:

Business Requirement (BRD)
  ↓ answers "what problem?"
Technical Requirement (PRD)
  ↓ answers "what to build technically?"
Design Document (DES)
  ↓ answers "how to architect this?"
  ├→ Data Model (DATA) - what data structure?
  ├→ API Contract (API) - what endpoints?
  └→ Component (CMP) - what services?

Plan (PLN)
  ↓ answers "how to execute?"
Milestone (MLS) - specific checkpoints
Flow Schematic (FLOW) - how it works
Deployment Procedure (DEPLOY) - how to launch
Configuration Schema (CONFIG) - how to configure

Key interactions:

• BRD → PRD: Business problem becomes technical requirement
• PRD → DES: Technical spec becomes architectural design
• DES → {DATA, API, CMP}: Architecture drives data/API/component specs
• DES → PLN: Design informs implementation plan
• PRD + DES → FLOW: Requirements and design inform workflows
• CMP + CONFIG → DEPLOY: Component and config specs inform deployment

CLI Tools

Get Next Available ID

scripts/next-id.sh <spec-type>
scripts/next-id.sh <spec-type> --with-slug <slug>

Determines the next available ID number for a spec type. Useful before creating a new spec.

Examples:

• scripts/next-id.sh business-requirement → brd-002
• scripts/next-id.sh api-contract --with-slug notifications → api-002-notifications

Generate Spec

# Manual ID
scripts/generate-spec.sh <spec-type> <spec-id>

# Auto-generate next ID
scripts/generate-spec.sh <spec-type> --next <slug>
scripts/generate-spec.sh <spec-type> --next

Creates new spec in docs/specs/{spec-type}/{spec-id}.md from template.

When to use --next:

• Creating the first spec of a type (auto-assigns ID 001)
• Don't know what the next number should be
• Want to ensure no ID conflicts

Examples:

• scripts/generate-spec.sh business-requirement brd-001-export (manual ID)
• scripts/generate-spec.sh business-requirement --next export (auto ID: brd-002-export)
• scripts/generate-spec.sh milestone --next (auto ID: mls-001)

Validate Spec

scripts/validate-spec.sh docs/specs/<type>/<id>.md

Returns: ✓ PASS | ⚠ WARNINGS | ✗ ERRORS

Check Completeness

scripts/check-completeness.sh docs/specs/<type>/<id>.md

Shows completion %, TODO items, missing sections.

List Templates

scripts/list-templates.sh

Shows all 11 available specification templates.

Tool Usage Guide

When creating a new spec, use this workflow:

1. First, determine the next ID:

   scripts/next-id.sh <spec-type>
   

2. Then generate with that ID:

   scripts/generate-spec.sh <spec-type> --next <slug>
   

Or combine in one step:

scripts/generate-spec.sh <spec-type> --next <descriptive-slug>

This ensures sequential numbering and prevents ID conflicts.

Step-by-Step Spec Creation Process

Step 1: Clarify Requirements (MANDATORY)

Before creating any spec, use AskUserQuestion to gather:

Question 1: Scope & Purpose

• What problem/feature/system are we documenting?
• What's the primary goal of this specification?
• What should be included vs. excluded?

Question 2: Audience & Detail Level

• Who will read/use this spec? (developers, stakeholders, operations team)
• How technical should it be? (high-level overview, detailed implementation)
• Are there specific sections that need extra detail?

Question 3: Context & Dependencies

• Are there related specs or systems to reference?
• What existing documentation should inform this spec?
• What constraints or requirements exist?

Step 2: Research Phase (REQUIRED)

Before filling the template:

1. Read the corresponding guide - guides/{spec-type}.md contains critical instructions
2. Search for related specs - Use Glob to find specs that might be referenced
3. Review codebase context - Grep for relevant code if documenting existing systems
4. Check template structure - Read templates/{spec-type}.md to understand required sections

Step 3: Generate Spec Structure

Determine the next ID and generate:

# Option 1: Auto-generate with slug (RECOMMENDED)
scripts/generate-spec.sh <spec-type> --next <descriptive-slug>

# Option 2: Check ID first, then generate
scripts/next-id.sh <spec-type>
scripts/generate-spec.sh <spec-type> <full-id-with-slug>

This creates the file with proper template structure at docs/specs/{spec-type}/{spec-id}.md.

Why use --next?

• Automatically determines the next sequential ID
• Prevents ID conflicts
• No need to manually check existing specs
• Ensures consistent numbering

Step 4: Fill Content Following Guide

Critical Rules:

• Follow the guide's section-by-section instructions exactly
• Replace ALL template placeholders with real content
• Write meaningful, specific content - no generic text
• Include concrete examples, not abstract descriptions
• Reference related specs using [spec-id] format
• Complete every required section before validation

Section Writing Approach:

1. Read guide instructions for the section
2. Gather specific information from research
3. Write clear, concise content
4. Add examples or diagrams if helpful
5. Ensure it answers the section's core question

Step 5: Validation & Quality Check

Run both validation scripts:

# Check structure and completeness
scripts/validate-spec.sh docs/specs/<id>.md

# Find TODOs and incomplete sections
scripts/check-completeness.sh docs/specs/<id>.md

Fix all issues:

• ✗ ERRORS must be resolved (missing required sections)
• ⚠ WARNINGS should be addressed (incomplete content)
• Remove all TODO markers
• Ensure no template guidance text remains

Step 6: Final Review

Before considering the spec complete:

✓ All required sections have meaningful content ✓ No template placeholders or TODOs remain ✓ Related specs are properly referenced ✓ Examples and specifics are included ✓ Validation passes with no errors ✓ Content matches user's requirements from Step 1

Instruction Guides

Comprehensive guides in guides/ directory. Always read the guide for your spec type before starting.

Each guide includes:

• Quick Start - Get going in 5 minutes
• Research Phase - How to research context and related specs
• Structure & Content - Detailed walkthrough of each section
• Writing Tips - Best practices and examples
• Validation & Fixes - How to use tools and fix issues
• Decision Framework - Questions to guide your thinking

Start here: guides/README.md - Master guide with complete end-to-end workflows showing how all 11 specs connect.

Common Mistakes to Avoid

❌ DON'T:

• Skip asking clarifying questions - assumptions lead to wrong specs
• Leave template guidance text or TODOs in final spec
• Write generic/abstract content instead of specific details
• Ignore the guide for the spec type
• Skip validation before considering spec complete
• Create specs without researching related specs and context
• Fill sections without understanding their purpose

✅ DO:

• Always use AskUserQuestion before starting
• Read the spec-type guide thoroughly
• Research related specs and codebase
• Write specific, concrete content with examples
• Validate and fix all issues
• Ensure every section answers its core question
• Reference related specs using proper format

Quality Standards for Specs

Every completed spec must meet these standards:

Content Quality:

• Specific and concrete (not abstract or generic)
• Includes real examples, not placeholder text
• All sections fully completed with meaningful content
• Technical accuracy verified against codebase/requirements
• Clear and understandable by target audience

Structural Integrity:

• Proper ID format: type-number-descriptive-slug
• All required sections present and complete
• Follows template structure exactly
• Related specs properly referenced with [spec-id]
• No TODO markers or template guidance text

Validation Status:

• ✓ PASS from validate-spec.sh
• 100% completion from check-completeness.sh
• No errors or warnings
• All user requirements from clarification phase met

Validation Rules

All specs require:

• Properly formatted ID (type-number-slug)
• Clear overview/description
• Key content sections (varies by type)

Spec type specifics: See ./templates/{type}.md for required sections.

Naming Convention

Format: <type>-<number>-<descriptive-slug>

Types: brd, prd, des, api, data, cmp, pln, mls, flow, deploy, config

Examples:

• brd-001-bulk-export
• prd-001-export-async-api
• des-001-microservices-architecture

Validation Levels

• ✓ PASS - Production-ready, all sections complete
• ⚠ WARNINGS - Usable but incomplete TODOs or optional sections
• ✗ ERRORS - Critical sections missing, not ready

When to Use This Skill

• Create new specs for features, systems, or components
• Validate existing specs for completeness and quality
• Review specs and provide feedback
• Understand spec structure and content requirements
• See how specs connect and inform each other
• Get step-by-step guidance through spec writing process

When creating a spec, always ask clarifying questions about:

• Who will use this specification (audience)
• What level of detail is needed
• What's in scope vs. out of scope
• Which aspects are highest priority

What Each Component Does

Templates (templates/)

Starting structure for each spec type. Used by generate-spec.sh.

Guides (guides/)

Read these. Comprehensive how-to for each spec type with research guidance, structure details, writing tips, and decision frameworks.

Scripts (scripts/)

• generate-spec.sh - Create from template
• validate-spec.sh - Check completeness
• check-completeness.sh - Find TODOs
• list-templates.sh - List types

Docs (docs/specs/)

Location where all generated specs are stored, organized by type into folders:

• business-requirement/ - BRD specs
• technical-requirement/ - PRD specs
• design-document/ - Design specs
• api-contract/ - API specs
• data-model/ - Data model specs
• component/ - Component specs
• plan/ - Plan specs
• milestone/ - Milestone specs
• flow-schematic/ - Flow specs
• deployment-procedure/ - Deployment specs
• configuration-schema/ - Config specs

Workflow Examples

Example 1: User Requests "Create a BRD for export feature"

Step 1: Clarify (Use AskUserQuestion)

• Q: "What's the export feature scope - what data, for whom, why needed?"
• Q: "Who's the audience - developers, product team, or executives?"
• Q: "Detail level - business justification only or include user stories?"

Step 2: Research

• Read guides/business-requirement.md
• Glob search: docs/specs/business-requirement/brd-*.md for related BRDs
• Grep: Search codebase for existing export functionality

Step 3: Generate

# Use --next to auto-generate the next ID
scripts/generate-spec.sh business-requirement --next export-feature
# This will auto-assign brd-002-export-feature (or next available)

Step 4: Fill Content

• Follow guide's section-by-section instructions
• Problem Statement: Specific pain points from user research
• Business Value: Concrete metrics and ROI
• User Stories: Real scenarios with acceptance criteria
• Success Metrics: Measurable KPIs

Step 5: Validate

scripts/validate-spec.sh docs/specs/business-requirement/brd-002-export-feature.md
scripts/check-completeness.sh docs/specs/business-requirement/brd-002-export-feature.md

Step 6: Review

• ✓ All sections have specific, real content
• ✓ No TODOs or template text
• ✓ Validation passes
• ✓ Matches user's requirements from clarification

Example 2: User Requests "Document the API for notifications"

Step 1: Clarify

• Q: "Is this for a new API design or documenting existing?"
• Q: "Who will use this - frontend developers, mobile team, third parties?"
• Q: "What endpoints - all CRUD operations or specific flows?"

Step 2: Research

• Read guides/api-contract.md
• Read existing notification service code
• Check for related specs in relevant folders:
  • docs/specs/technical-requirement/prd-*-notification.md
  • docs/specs/design-document/des-*-notification.md

Step 3-6: Generate, Fill, Validate, Review

• Create specific endpoint definitions with real request/response examples
• Include authentication, error codes, rate limits
• Document actual data models from codebase
• Validate all examples are syntactically correct

Critical Reminders

🎯 Every spec creation MUST start with AskUserQuestion - No assumptions!

🔢 Use --next to auto-generate IDs - Prevents numbering conflicts and ensures sequential IDs

📚 Always read the guide - guides/{spec-type}.md contains essential instructions

🔍 Research before writing - Understand context, related specs, and codebase

✍️ Write concrete content - Real examples, specific details, no placeholders

✅ Validate before completion - Fix all errors and warnings

🎓 Quality over speed - A complete, accurate spec is worth the extra time