Initial commit
This commit is contained in:
Zhongwei Li
523
skills/spec-author/guides/plan.md
Normal file
523
skills/spec-author/guides/plan.md
Normal file
@@ -0,0 +1,523 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user