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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

# 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

# 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

# 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

# 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 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 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 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 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 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 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 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 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 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 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 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:

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.