gh-onezerocompany-claude-project-basics/skills/spec-author/SKILL.md

---
name: Spec Author
description: Create, validate, and improve specification documents. Use this when writing business requirements, technical requirements, design documents, data models, API contracts, components, plans, milestones, flow schematics, deployment procedures, or configuration schemas.
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
---

# 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

```bash
# 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
```bash
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
```bash
# 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
```bash
scripts/validate-spec.sh docs/specs/<type>/<id>.md
```
Returns: ✓ PASS | ⚠ WARNINGS | ✗ ERRORS

### Check Completeness
```bash
scripts/check-completeness.sh docs/specs/<type>/<id>.md
```
Shows completion %, TODO items, missing sections.

### List Templates
```bash
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:**
   ```bash
   scripts/next-id.sh <spec-type>
   ```

2. **Then generate with that ID:**
   ```bash
   scripts/generate-spec.sh <spec-type> --next <slug>
   ```

**Or combine in one step:**
```bash
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:**
```bash
# 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:
```bash
# 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**
```bash
# 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**
```bash
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