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

# Spec Author Instruction Guides

This directory contains comprehensive instruction guides for creating each type of specification document supported by the spec-author skill. Each guide includes:

- **Quick Start**: Get up and running quickly with basic commands
- **Research Phase**: Guidance on researching related specs and external documentation
- **Structure & Content Guide**: Detailed walkthrough of each section
- **Writing Tips**: Best practices and common pitfalls
- **Validation & Fixing Issues**: How to use the validation tools
- **Decision-Making Framework**: Questions to ask while writing
- **Next Steps**: Complete workflow from creation to completion

## Specification Types

### Business & Planning

#### [Business Requirement (brd-XXX)](./business-requirement.md)
Capture what problem you're solving and why it matters from a business perspective. Translate customer needs into requirements that engineering can build against.

**Use when**: Documenting new features, defining business value, creating stakeholder alignment
**Key sections**: Business value, user stories, acceptance criteria, success metrics

#### [Technical Requirement (prd-XXX)](./technical-requirement.md)
Translate business needs into specific, implementation-ready technical requirements. Bridge the gap between "what we want" and "how we'll build it."

**Use when**: Defining technical implementation details, mapping business requirements to solutions
**Key sections**: Technical requirements, design decisions, acceptance criteria, constraints

#### [Plan (pln-XXX)](./plan.md)
Document implementation roadmaps, project timelines, phases, and deliverables. Provide the "how and when" we'll build something.

**Use when**: Planning project execution, defining phases and timeline, identifying dependencies
**Key sections**: Phases, timeline, deliverables, dependencies, risks, resources

#### [Milestone (mls-XXX)](./milestone.md)
Define specific delivery checkpoints within a project, including deliverables, success criteria, and timeline.

**Use when**: Defining delivery targets, communicating progress, tracking against concrete deliverables
**Key sections**: Deliverables, success criteria, timeline, blockers, acceptance procedures

### Architecture & Design

#### [Design Document (des-XXX)](./design-document.md)
Provide the detailed architectural and technical design for a system, component, or significant feature.

**Use when**: Major system redesign, architectural decisions, technology choices
**Key sections**: Proposed solution, design decisions, technology stack, trade-offs, implementation plan

#### [Component (cmp-XXX)](./component.md)
Document individual system components or services, including responsibilities, interfaces, configuration, and deployment.

**Use when**: Documenting microservices, major system components, architectural pieces
**Key sections**: Responsibilities, interfaces, configuration, deployment, monitoring

#### [Flow Schematic (flow-XXX)](./flow-schematic.md)
Document business processes, workflows, and system flows visually and textually. Show how information moves through systems.

**Use when**: Documenting user workflows, system interactions, complex processes
**Key sections**: Flow diagram, step-by-step descriptions, decision points, error handling

### Data & Contracts

#### [Data Model (data-XXX)](./data-model.md)
Define entities, fields, relationships, and constraints for your application's data. Define the "shape" of data your system works with.

**Use when**: Planning database schema, documenting entity relationships, enabling API/UI teams
**Key sections**: Entity definitions, relationships, constraints, scaling considerations

#### [API Contract (api-XXX)](./api-contract.md)
Document the complete specification of REST/GraphQL endpoints, including request/response formats, error handling, and authentication.

**Use when**: Defining API endpoints, enabling parallel frontend/backend development, creating living documentation
**Key sections**: Authentication, endpoints, response formats, error handling, rate limiting

### Operations & Configuration

#### [Deployment Procedure (deploy-XXX)](./deployment-procedure.md)
Document step-by-step instructions for deploying systems to production, including prerequisites, procedures, rollback, and troubleshooting.

**Use when**: Deploying services, creating runbooks, enabling safe operations, ensuring repeatable deployments
**Key sections**: Prerequisites, deployment steps, rollback procedure, success criteria, troubleshooting

#### [Configuration Schema (config-XXX)](./configuration-schema.md)
Document all configurable parameters for a system, including types, valid values, defaults, and impact.

**Use when**: Documenting system configuration, enabling ops teams to configure safely, supporting multiple environments
**Key sections**: Configuration methods, field descriptions, validation rules, environment-specific examples

## How to Use These Guides

### For New Spec Types

1. **Choose your spec type** based on what you're documenting
2. **Go to the corresponding guide** (e.g., if creating a business requirement, read `business-requirement.md`)
3. **Follow the Quick Start** to generate a new spec from the template
4. **Work through the Research Phase** to understand context
5. **Use the Structure & Content Guide** to fill in each section
6. **Apply the Writing Tips** as you write
7. **Run validation** using the tools
8. **Follow the Decision-Making Framework** to reason through tough choices

### For Improving Existing Specs

1. **Check the appropriate guide** for what your spec should contain
2. **Review the "Validation & Fixing Issues"** section for common problems
3. **Use validation tools** to identify what's missing
4. **Fill in missing sections** using the structure guide
5. **Fix any issues** the validator identifies

### For Team Standards

1. **Each guide provides concrete standards** for each spec type
2. **Sections that are marked as "required"** should be in all specs
3. **Examples in each guide** show the expected quality and detail level
4. **Validation rules** ensure consistent structure across specs

## Quick Reference: CLI Commands

### Create a New Spec

```bash
# Generate a new spec from template
scripts/generate-spec.sh <spec-type> <spec-id>

# Examples:
scripts/generate-spec.sh business-requirement brd-001-user-export
scripts/generate-spec.sh design-document des-001-export-arch
scripts/generate-spec.sh api-contract api-001-export-endpoints
```

### Validate a Spec

```bash
# Check a spec for completeness and structure
scripts/validate-spec.sh docs/specs/business-requirement/brd-001-user-export.md
```

Returns:
- ✓ **PASS**: All required sections present and complete
- ⚠ **WARNINGS**: Missing optional sections or incomplete TODOs
- ✗ **ERRORS**: Missing critical sections or structural issues

### Check Completeness

```bash
# See what's incomplete and what TODOs need attention
scripts/check-completeness.sh docs/specs/business-requirement/brd-001-user-export.md
```

Shows:
- Completion percentage
- Missing sections with descriptions
- TODO items that need completion
- Referenced documents

### List Available Templates

```bash
# See what spec types are available
scripts/list-templates.sh
```

## Workflow Example: Creating a Feature End-to-End

### Step 1: Business Requirements
**Create**: `scripts/generate-spec.sh business-requirement brd-001-bulk-export`
**Guide**: Follow [business-requirement.md](./business-requirement.md)
**Output**: `docs/specs/business-requirement/brd-001-bulk-export.md`

### Step 2: Technical Requirements
**Create**: `scripts/generate-spec.sh technical-requirement prd-001-export-api`
**Guide**: Follow [technical-requirement.md](./technical-requirement.md)
**Reference**: Link to BRD created in Step 1
**Output**: `docs/specs/technical-requirement/prd-001-export-api.md`

### Step 3: Design Document
**Create**: `scripts/generate-spec.sh design-document des-001-export-arch`
**Guide**: Follow [design-document.md](./design-document.md)
**Reference**: Link to PRD and BRD
**Output**: `docs/specs/design-document/des-001-export-arch.md`

### Step 4: Data Model
**Create**: `scripts/generate-spec.sh data-model data-001-export-schema`
**Guide**: Follow [data-model.md](./data-model.md)
**Reference**: Entities used in design
**Output**: `docs/specs/data-model/data-001-export-schema.md`

### Step 5: API Contract
**Create**: `scripts/generate-spec.sh api-contract api-001-export-endpoints`
**Guide**: Follow [api-contract.md](./api-contract.md)
**Reference**: Link to technical requirements
**Output**: `docs/specs/api-contract/api-001-export-endpoints.md`

### Step 6: Component Specs
**Create**: `scripts/generate-spec.sh component cmp-001-export-service`
**Guide**: Follow [component.md](./component.md)
**Reference**: Link to design and technical requirements
**Output**: `docs/specs/component/cmp-001-export-service.md`

### Step 7: Implementation Plan
**Create**: `scripts/generate-spec.sh plan pln-001-export-implementation`
**Guide**: Follow [plan.md](./plan.md)
**Reference**: Link to all related specs
**Output**: `docs/specs/plan/pln-001-export-implementation.md`

### Step 8: Define Milestones
**Create**: `scripts/generate-spec.sh milestone mls-001-export-phase1`
**Guide**: Follow [milestone.md](./milestone.md)
**Reference**: Link to plan created in Step 7
**Output**: `docs/specs/milestone/mls-001-export-phase1.md`

### Step 9: Document Workflows
**Create**: `scripts/generate-spec.sh flow-schematic flow-001-export-process`
**Guide**: Follow [flow-schematic.md](./flow-schematic.md)
**Reference**: Illustrate flows described in design and API
**Output**: `docs/specs/flow-schematic/flow-001-export-process.md`

### Step 10: Configuration Schema
**Create**: `scripts/generate-spec.sh configuration-schema config-001-export-service`
**Guide**: Follow [configuration-schema.md](./configuration-schema.md)
**Reference**: Used by component and deployment
**Output**: `docs/specs/configuration-schema/config-001-export-service.md`

### Step 11: Deployment Procedure
**Create**: `scripts/generate-spec.sh deployment-procedure deploy-001-export-production`
**Guide**: Follow [deployment-procedure.md](./deployment-procedure.md)
**Reference**: Link to component, configuration, and plan
**Output**: `docs/specs/deployment-procedure/deploy-001-export-production.md`

## Tips for Success

### 1. Research Thoroughly
- Use the Research Phase section in each guide
- Look for related specs that have already been created
- Research external docs using doc tools or web search
- Understand the context before writing

### 2. Use CLI Tools Effectively
- Start with `scripts/generate-spec.sh` to create from template (saves time)
- Use `scripts/validate-spec.sh` frequently while writing (catches issues early)
- Use `scripts/check-completeness.sh` to find TODOs that need attention
- Run validation before considering a spec "done"

### 3. Complete All Sections
- "Required" sections should be in every spec
- "Optional" sections may be skipped if not applicable
- Never leave placeholder text or TODO items in final specs
- Incomplete specs cause confusion and rework

### 4. Link Specs Together
- Reference related specs using [ID] format (e.g., `[BRD-001]`)
- Show how specs depend on each other
- This creates a web of related documentation
- Makes specs more discoverable

### 5. Use Concrete Examples
- Concrete examples are clearer than abstract descriptions
- Show actual data, requests, responses
- Include sample configurations
- Show before/after if describing changes

### 6. Get Feedback Early
- Share early drafts with stakeholders
- Use validation to catch structural issues
- Get domain experts to review for accuracy
- Iterate based on feedback

### 7. Keep Updating
- Specs should reflect current state, not initial design
- Update when important decisions change
- Mark what was decided and when
- Document why changes were made

## Common Patterns Across Guides

### Quick Start Pattern
Every guide starts with:
```bash
scripts/generate-spec.sh <type> <id>
# Edit file
scripts/validate-spec.sh docs/specs/...
scripts/check-completeness.sh docs/specs/...
```

### Research Phase Pattern
Every guide recommends:
1. Finding related specs
2. Understanding external context
3. Reviewing existing patterns
4. Understanding constraints/requirements

### Structure Pattern
Every guide provides:
- Detailed walkthrough of each section
- Purpose of each section
- What should be included
- How detailed to be

### Validation Pattern
Every guide includes:
- Running the validator
- Common issues and how to fix them
- Checking completeness

### Decision Pattern
Every guide encourages thinking through:
1. Scope/boundaries
2. Options and trade-offs
3. Specific decisions and rationale
4. Communication and approval
5. Evolution and change

## Getting Help

### For questions about a specific spec type:
- Read the corresponding guide in this directory
- Check the examples section for concrete examples
- Review the decision-making framework for guidance

### For validation issues:
- Run `./scripts/validate-spec.sh` to see what's missing
- Read the "Validation & Fixing Issues" section of the guide
- Check if required sections are present and complete

### For understanding the bigger picture:
- Read through related guides to see how specs connect
- Look at the Workflow Example to see the full flow
- Review the Common Patterns section

## Next Steps

1. **Pick a spec type** you need to create
2. **Read the corresponding guide** thoroughly
3. **Run the generate command** to create from template
4. **Follow the structure guide** to fill in sections
5. **Validate frequently** as you work
6. **Fix issues** the validator identifies
7. **Get feedback** from stakeholders
8. **Consider this "complete"** when validator passes ✓

Good luck writing great specs! Remember: clear, complete specifications save time and prevent mistakes later in the development process.