# 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

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

```bash
# 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

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

```markdown
## 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

```markdown
## 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

```markdown
## 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

```markdown
## 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

```markdown
## 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

```markdown
## 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
```bash
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