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

How to Create a Plan Specification

Plan specifications document implementation roadmaps, project timelines, phases, and deliverables. They provide the "how and when" we'll build something.

Quick Start

# 1. Create a new plan
scripts/generate-spec.sh plan pln-001-descriptive-slug

# 2. Open and fill in the file
# (The file will be created at: docs/specs/plan/pln-001-descriptive-slug.md)

# 3. Fill in phases and deliverables, then validate:
scripts/validate-spec.sh docs/specs/plan/pln-001-descriptive-slug.md

# 4. Fix issues and check completeness:
scripts/check-completeness.sh docs/specs/plan/pln-001-descriptive-slug.md

When to Write a Plan

Use a Plan Spec when you need to:

• Document project phases and timeline
• Define deliverables and milestones
• Identify dependencies and blockers
• Track progress against plan
• Communicate timeline to stakeholders
• Align team on implementation sequence

Research Phase

1. Research Related Specifications

Find what you're planning:

# Find business requirements
grep -r "brd" docs/specs/ --include="*.md"

# Find technical requirements and design docs
grep -r "prd\|design" docs/specs/ --include="*.md"

# Find existing plans that might be related
grep -r "plan" docs/specs/ --include="*.md"

2. Understand the Scope

• What are you building?
• What are the business priorities?
• What are the technical dependencies?
• What constraints exist (timeline, resources)?

3. Review Similar Projects

• How long did similar projects take?
• What teams are involved?
• What risks arose and how were they managed?
• What was the actual vs. planned timeline?

Structure & Content Guide

Title & Metadata

• Title: "Export Feature Implementation Plan", "Q1 2024 Roadmap", etc.
• Timeline: Start date through completion
• Owner: Project lead or team lead
• Status: Planning | In Progress | Completed

Overview Section

# Export Feature Implementation Plan

## Summary
Plan to implement bulk user data export feature across 8 weeks.
Includes job queue infrastructure, API endpoints, UI, and deployment.

**Timeline**: January 15 - March 10, 2024 (8 weeks)
**Team Size**: 3-4 engineers, 1 product manager
**Owner**: Engineering Lead
**Status**: Planning

## Key Objectives
1. Enable enterprise customers to bulk export their data
2. Build reusable async job processing infrastructure
3. Achieve 99% reliability for export system
4. Complete testing and documentation before production launch

Phases Section

Document phases with timing:

## Implementation Phases

### Phase 1: Infrastructure Setup (Weeks 1-2)
**Timeline**: Jan 15 - Jan 28 (2 weeks)
**Team**: 2 engineers

**Goals**
- Implement job queue infrastructure (Redis + Bull)
- Build worker process foundation
- Deploy to staging environment

**Deliverables**
- Redis job queue with worker processes
- Monitoring and alerting setup
- Health checks and graceful shutdown
- Documentation of queue architecture

**Tasks**
- [ ] Set up Redis cluster (managed service)
- [ ] Implement Bull queue with worker processors
- [ ] Add Prometheus metrics for queue depth
- [ ] Configure Kubernetes deployment manifests
- [ ] Create staging deployment
- [ ] Document queue architecture

**Dependencies**
- None (can start immediately)

**Success Criteria**
- Job queue processes 10 jobs/second without errors
- Workers can be scaled horizontally in Kubernetes
- Monitoring shows queue depth and worker status

Phase 2: Export Service Development (Weeks 3-5)

Timeline: Jan 29 - Feb 18 (3 weeks) Team: 2-3 engineers

Goals

• Implement export processing logic
• Add database export functionality
• Support multiple export formats

Deliverables

• Export service that processes jobs from queue
• CSV and JSON export format support
• Data validation and error handling
• Comprehensive unit tests

Tasks

• Implement data query and export logic
• Add CSV formatter
• Add JSON formatter
• Implement error handling and retries
• Add data compression
• Write unit tests (target: 90%+ coverage)
• Performance test with 100MB+ files

Dependencies

• Phase 1 complete (queue infrastructure)
• Data model spec finalized ([DATA-001])

Success Criteria

• Export processes complete in < 5 minutes for 100MB files
• All data exports match source data exactly
• Error retry logic works correctly
• 90%+ test coverage

### Phase 3: API & Storage (Weeks 4-6)
**Timeline**: Feb 5 - Feb 25 (3 weeks, 1 week overlap with Phase 2)
**Team**: 2 engineers

**Goals**
- Implement REST API for export management
- Set up S3 storage for export files
- Build export status tracking

**Deliverables**
- REST API endpoints (create, get status, download)
- S3 integration for file storage
- Export metadata storage in database
- API documentation

**Tasks**
- [ ] Implement POST /exports endpoint
- [ ] Implement GET /exports/{id} endpoint
- [ ] Implement GET /exports/{id}/download endpoint
- [ ] Add S3 integration for storage
- [ ] Create export metadata schema
- [ ] Implement TTL-based cleanup
- [ ] Add API rate limiting
- [ ] Create API documentation

**Dependencies**
- Phase 1 complete (queue infrastructure)
- Phase 2 progress (service processing)
- Data model spec finalized ([DATA-001])

**Success Criteria**
- API responds to requests in < 100ms (p95)
- Files stored and retrieved from S3 correctly
- Cleanup removes files after 7-day TTL

Phase 4: Testing & Optimization (Weeks 6-7)

Timeline: Feb 19 - Mar 3 (2 weeks, overlap with Phase 3) Team: 2-3 engineers

Goals

• Comprehensive testing across all components
• Performance optimization
• Security audit

Deliverables

• Integration tests for full export flow
• Load tests verifying performance targets
• Security audit report
• Performance tuning applied

Tasks

• Write integration tests for full export flow
• Load test with 100 concurrent exports
• Security audit of data handling
• Performance profiling and optimization
• Test large file handling (500MB+)
• Test error scenarios and retries
• Document known limitations

Dependencies

• Phase 2, 3 complete (service and API)

Success Criteria

• 95%+ automated test coverage
• Load tests show < 500ms p95 latency
• Security audit finds no critical issues
• Performance meets targets (< 5 min for 100MB)

### Phase 5: Documentation & Launch (Weeks 7-8)
**Timeline**: Mar 4 - Mar 10 (2 weeks, 1 week overlap)
**Team**: Full team (all 4)

**Goals**
- Complete documentation
- Customer communication
- Production deployment

**Deliverables**
- API documentation (for customers)
- Runbook for operations team
- Customer launch announcement
- Production deployment checklist

**Tasks**
- [ ] Create customer-facing API docs
- [ ] Create operational runbook
- [ ] Write troubleshooting guide
- [ ] Create launch announcement
- [ ] Train support team
- [ ] Deploy to production
- [ ] Monitor for issues
- [ ] Collect initial feedback

**Dependencies**
- All prior phases complete
- Security audit passed

**Success Criteria**
- Documentation is complete and clear
- Support team can operate system independently
- Launch goes smoothly with no incidents
- Users successfully export data

Dependencies & Blocking Section

## Dependencies & Blockers

### External Dependencies
- **Data Model Spec ([DATA-001])**: Required to understand data structure
  - Status: Draft
  - Timeline: Must be approved by Jan 20
  - Owner: Data team

- **API Contract Spec ([API-001])**: API design must be finalized
  - Status: In Review
  - Timeline: Must be approved by Feb 5
  - Owner: Product team

- **Infrastructure Resources**: Need S3 bucket and Redis cluster
  - Status: Requested
  - Timeline: Must be available by Jan 15
  - Owner: Infrastructure team

### Internal Dependencies
- **Phase 1 → Phase 2**: Queue infrastructure must be stable
- **Phase 2 → Phase 3**: Service must process exports correctly
- **Phase 3 → Phase 4**: API and storage must be working
- **Phase 4 → Phase 5**: All testing must pass

### Known Blockers
- Infrastructure team is currently overloaded
  - Mitigation: Request resources early, use managed services
- Data privacy review needed for export functionality
  - Mitigation: Schedule review meeting in first week

Timeline & Gantt Chart Section

## Timeline

Phase 1: Infrastructure (2 wks) [====================] Phase 2: Export Service (3 wks) ___[============================] Phase 3: API & Storage (3 wks) _______[============================] Phase 4: Testing (2 wks) ______________[====================] Phase 5: Launch (2 wks) __________________[====================]

Week: 1 2 3 4 5 6 7 8 |||||||_|

### Key Milestones

| Milestone | Target Date | Owner | Deliverable |
|-----------|------------|-------|-------------|
| Queue Infrastructure Ready | Jan 28 | Eng Lead | Staging deployment |
| Export Processing Works | Feb 18 | Eng Lead | Service passes tests |
| API Complete & Working | Feb 25 | Eng Lead | API docs + endpoints |
| Testing Complete | Mar 3 | QA Lead | Test report |
| Production Launch | Mar 10 | Eng Lead | Live feature |

Resource & Team Section

## Resources

### Team Composition

**Engineering Team**
- 2 Backend Engineers (Weeks 1-8): Infrastructure, export service, API
- 1 Backend Engineer (Weeks 4-8): Testing, optimization
- Optional: 1 Frontend Engineer (Weeks 7-8): Documentation, demos

**Support & Operations**
- Product Manager (all weeks): Requirements, prioritization
- QA Lead (Weeks 4-8): Testing coordination

### Skills Required
- Backend development (Node.js, PostgreSQL)
- Infrastructure/DevOps (Kubernetes, AWS)
- Performance testing and optimization
- Security best practices

### Training Needs
- Team review of job queue pattern
- S3 and AWS integration workshop

Risk Management Section

## Risks & Mitigation

### Technical Risks

**Risk: Job Queue Reliability Issues**
- **Likelihood**: Medium
- **Impact**: High (feature doesn't work)
- **Mitigation**:
  - Use managed Redis service (AWS ElastiCache)
  - Implement comprehensive error handling
  - Load test thoroughly before production
  - Have rollback plan

**Risk: Large File Performance Problems**
- **Likelihood**: Medium
- **Impact**: Medium (performance targets missed)
- **Mitigation**:
  - Start performance testing early (Week 2)
  - Profile and optimize in Phase 4
  - Document performance constraints
  - Set data size limits if needed

**Risk: Data Consistency Issues**
- **Likelihood**: Low
- **Impact**: High (data corruption)
- **Mitigation**:
  - Implement data validation
  - Use database transactions
  - Test with edge cases
  - Have data audit procedures

### Scheduling Risks

**Risk: Phase Dependencies Cause Delays**
- **Likelihood**: Medium
- **Impact**: High (slips launch date)
- **Mitigation**:
  - Phase 2 and 3 overlap to parallelize
  - Start Phase 4 testing early
  - Have clear done criteria

**Risk: Data Model Spec Not Ready**
- **Likelihood**: Low
- **Impact**: High (blocks implementation)
- **Mitigation**:
  - Confirm spec status before starting
  - Have backup data model if needed
  - Schedule early review meetings

Success Metrics Section

## Success Criteria

### Technical Metrics
- [ ] Export API processes 1000+ requests/day
- [ ] p95 latency < 100ms for status queries
- [ ] Export processing completes in < 5 minutes for 100MB files
- [ ] System reliability > 99.5%
- [ ] Zero data loss or corruption incidents

### Adoption Metrics
- [ ] 30%+ of enterprise users adopt feature in first month
- [ ] Average of 2+ exports per adopting user per month
- [ ] Support tickets about exports < 5/week

### Quality Metrics
- [ ] 90%+ test coverage
- [ ] Zero critical security issues
- [ ] Documentation completeness = 100%
- [ ] Team can operate independently

Writing Tips

Be Realistic About Timelines

• Include buffer time for unknowns (add 20-30%)
• Consider team capacity and interruptions
• Account for review and testing cycles
• Document assumptions about team size/availability

Break Down Phases Clearly

• Each phase should have clear deliverables
• Phases should be independable or clearly sequenced
• Dependencies should be explicit
• Success criteria should be measurable

Link to Related Specs

• Reference business requirements: [BRD-001]
• Reference technical requirements: [PRD-001]
• Reference design documents: [DES-001]
• Reference component specs: [CMP-001]

Identify Risk Early

• What could go wrong?
• What's outside your control?
• What mitigations exist?
• What's the contingency plan?

Track Against Plan

• Update plan weekly with actual progress
• Note slippages and root causes
• Adjust future phases if needed
• Use as learning for future planning

Validation & Fixing Issues

Run the Validator

scripts/validate-spec.sh docs/specs/plan/pln-001-your-spec.md

Common Issues & Fixes

Issue: "Phases lack clear deliverables"

• Fix: Add specific, measurable deliverables for each phase

Issue: "No timeline or dates specified"

• Fix: Add start/end dates and duration for each phase

Issue: "Dependencies not documented"

• Fix: Identify and document blocking dependencies between phases

Issue: "Resource allocation unclear"

• Fix: Specify team members, their roles, and time commitment per phase

Decision-Making Framework

When planning implementation:

1. Scope: What exactly are we building?

   • Must-haves vs. nice-to-haves?
   • What can we defer?

2. Sequence: What must be done in order?

   • What can happen in parallel?
   • Where are critical path bottlenecks?

3. Phases: How do we break this into manageable chunks?

   • 1-3 week phases work well
   • Each should produce something shippable/testable
   • Clear entry/exit criteria

4. Resources: What do we need?

   • Team skills and capacity?
   • Infrastructure and tools?
   • External dependencies?

5. Risk: What could derail us?

   • Technical risks?
   • Timeline risks?
   • Resource risks?
   • Mitigation strategies?

Next Steps

1. Create the spec: scripts/generate-spec.sh plan pln-XXX-slug
2. Research: Find related specs and understand scope
3. Define phases: Break work into logical chunks
4. Map dependencies: Understand what blocks what
5. Estimate effort: How long will each phase take?
6. Identify risks: What could go wrong?
7. Validate: scripts/validate-spec.sh docs/specs/plan/pln-XXX-slug.md
8. Share with team for feedback and planning