diff --git a/.cursor/rules/harbor_pilot_universal.mdc b/.cursor/rules/harbor_pilot_universal.mdc index 1881da11..f2965394 100644 --- a/.cursor/rules/harbor_pilot_universal.mdc +++ b/.cursor/rules/harbor_pilot_universal.mdc @@ -202,4 +202,5 @@ Follow this exact order **after** the Base Contract’s **Objective β†’ Result **Notes for Implementers:** - Respect Base *Do-Not* (no filler, no invented facts, no censorship). - Prefer clarity over completeness when timeboxed; capture unknowns explicitly. -- Apply historical comment management rules (see `.cursor/rules/historical-comment-management.mdc`) +- Apply historical comment management rules (see `.cursor/rules/historical_comment_management.mdc`) +- Apply realistic time estimation rules (see `.cursor/rules/realistic_time_estimation.mdc`) diff --git a/.cursor/rules/realistic_time_estimation.mdc b/.cursor/rules/realistic_time_estimation.mdc new file mode 100644 index 00000000..aa48577a --- /dev/null +++ b/.cursor/rules/realistic_time_estimation.mdc @@ -0,0 +1,348 @@ +--- +description: when generating text that has project task work estimates +alwaysApply: false +--- +# No Time Estimates β€” Harbor Pilot Directive + +> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, milestones, and complexity levels. Time estimates are consistently wrong and create unrealistic expectations. + +## 🎯 Purpose + +Development time estimates are consistently wrong and create unrealistic expectations. This rule ensures we focus on phases, milestones, and complexity rather than trying to predict specific timeframes. + +## 🚨 Critical Rule + +**DO NOT MAKE TIME ESTIMATES** +- **Never provide specific time estimates** - they are always wrong +- **Use phases and milestones** instead of days/weeks +- **Focus on complexity and dependencies** rather than time +- **Set expectations based on progress, not deadlines** + +## πŸ“Š Planning Framework (Not Time Estimates) + +### **Complexity Categories** +- **Simple**: Text changes, styling updates, minor bug fixes +- **Medium**: New features, refactoring, component updates +- **Complex**: Architecture changes, integrations, cross-platform work +- **Unknown**: New technologies, APIs, or approaches + +### **Platform Complexity** +- **Single platform**: Web-only or mobile-only changes +- **Two platforms**: Web + mobile or web + desktop +- **Three platforms**: Web + mobile + desktop +- **Cross-platform consistency**: Ensuring behavior matches across all platforms + +### **Testing Complexity** +- **Basic**: Unit tests for new functionality +- **Comprehensive**: Integration tests, cross-platform testing +- **User acceptance**: User testing, feedback integration + +## πŸ” Planning Process (No Time Estimates) + +### **Step 1: Break Down the Work** +- Identify all subtasks and dependencies +- Group related work into logical phases +- Identify critical path and blockers + +### **Step 2: Define Phases and Milestones** +- **Phase 1**: Foundation work (basic fixes, core functionality) +- **Phase 2**: Enhancement work (new features, integrations) +- **Phase 3**: Polish work (testing, user experience, edge cases) + +### **Step 3: Identify Dependencies** +- **Technical dependencies**: What must be built first +- **Platform dependencies**: What works on which platforms +- **Testing dependencies**: What can be tested when + +### **Step 4: Set Progress Milestones** +- **Milestone 1**: Basic functionality working +- **Milestone 2**: All platforms supported +- **Milestone 3**: Fully tested and polished + +## πŸ“‹ Planning Checklist (No Time Estimates) + +- [ ] Work broken down into logical phases +- [ ] Dependencies identified and mapped +- [ ] Milestones defined with clear criteria +- [ ] Complexity levels assigned to each phase +- [ ] Platform requirements identified +- [ ] Testing strategy planned +- [ ] Risk factors identified +- [ ] Success criteria defined + +## 🎯 Example Planning (No Time Estimates) + +### **Example 1: Simple Feature** +``` +Phase 1: Core implementation +- Basic functionality +- Single platform support +- Unit tests + +Phase 2: Platform expansion +- Multi-platform support +- Integration tests + +Phase 3: Polish +- User testing +- Edge case handling +``` + +### **Example 2: Complex Cross-Platform Feature** +``` +Phase 1: Foundation +- Architecture design +- Core service implementation +- Basic web platform support + +Phase 2: Platform Integration +- Mobile platform support +- Desktop platform support +- Cross-platform consistency + +Phase 3: Testing & Polish +- Comprehensive testing +- Error handling +- User experience refinement +``` + +## 🚫 Anti-Patterns to Avoid + +- **"This should take X days"** - Red flag for time estimation +- **"Just a few hours"** - Ignores complexity and testing +- **"Similar to X"** - Without considering differences +- **"Quick fix"** - Nothing is ever quick in software +- **"No testing needed"** - Testing always takes effort + +## βœ… Best Practices + +### **When Planning:** +1. **Break down everything** - no work is too small to plan +2. **Consider all platforms** - web, mobile, desktop differences +3. **Include testing strategy** - unit, integration, and user testing +4. **Account for unknowns** - there are always surprises +5. **Focus on dependencies** - what blocks what + +### **When Presenting Plans:** +1. **Show the phases** - explain the logical progression +2. **Highlight dependencies** - what could block progress +3. **Define milestones** - clear success criteria +4. **Identify risks** - what could go wrong +5. **Suggest alternatives** - ways to reduce scope or complexity + +## πŸ”„ Continuous Improvement + +### **Track Progress** +- Record planned vs. actual phases completed +- Identify what took longer than expected +- Learn from complexity misjudgments +- Adjust planning process based on experience + +### **Learn from Experience** +- **Underestimated complexity**: Increase complexity categories +- **Missed dependencies**: Improve dependency mapping +- **Platform surprises**: Better platform research upfront + +## 🎯 Integration with Harbor Pilot + +This rule works in conjunction with: +- **Project Planning**: Focuses on phases and milestones +- **Resource Allocation**: Based on complexity, not time +- **Risk Management**: Identifies blockers and dependencies +- **Stakeholder Communication**: Sets progress-based expectations + +## πŸ“ Version History + +### v2.0.0 (2025-08-21) +- **Major Change**: Completely removed time estimation approach +- **New Focus**: Phases, milestones, and complexity-based planning +- **Eliminated**: All time multipliers, estimates, and calculations +- **Added**: Dependency mapping and progress milestone framework + +### v1.0.0 (2025-08-21) +- Initial creation based on user feedback about estimation accuracy +- ~~Established realistic estimation multipliers and process~~ +- ~~Added comprehensive estimation checklist and examples~~ +- Integrated with Harbor Pilot planning and risk management + +--- + +## 🚨 Remember + +**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.** + +## 🚨 Remember + +**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.** +# No Time Estimates β€” Harbor Pilot Directive + +> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, milestones, and complexity levels. Time estimates are consistently wrong and create unrealistic expectations. + +## 🎯 Purpose + +Development time estimates are consistently wrong and create unrealistic expectations. This rule ensures we focus on phases, milestones, and complexity rather than trying to predict specific timeframes. + +## 🚨 Critical Rule + +**DO NOT MAKE TIME ESTIMATES** +- **Never provide specific time estimates** - they are always wrong +- **Use phases and milestones** instead of days/weeks +- **Focus on complexity and dependencies** rather than time +- **Set expectations based on progress, not deadlines** + +## πŸ“Š Planning Framework (Not Time Estimates) + +### **Complexity Categories** +- **Simple**: Text changes, styling updates, minor bug fixes +- **Medium**: New features, refactoring, component updates +- **Complex**: Architecture changes, integrations, cross-platform work +- **Unknown**: New technologies, APIs, or approaches + +### **Platform Complexity** +- **Single platform**: Web-only or mobile-only changes +- **Two platforms**: Web + mobile or web + desktop +- **Three platforms**: Web + mobile + desktop +- **Cross-platform consistency**: Ensuring behavior matches across all platforms + +### **Testing Complexity** +- **Basic**: Unit tests for new functionality +- **Comprehensive**: Integration tests, cross-platform testing +- **User acceptance**: User testing, feedback integration + +## πŸ” Planning Process (No Time Estimates) + +### **Step 1: Break Down the Work** +- Identify all subtasks and dependencies +- Group related work into logical phases +- Identify critical path and blockers + +### **Step 2: Define Phases and Milestones** +- **Phase 1**: Foundation work (basic fixes, core functionality) +- **Phase 2**: Enhancement work (new features, integrations) +- **Phase 3**: Polish work (testing, user experience, edge cases) + +### **Step 3: Identify Dependencies** +- **Technical dependencies**: What must be built first +- **Platform dependencies**: What works on which platforms +- **Testing dependencies**: What can be tested when + +### **Step 4: Set Progress Milestones** +- **Milestone 1**: Basic functionality working +- **Milestone 2**: All platforms supported +- **Milestone 3**: Fully tested and polished + +## πŸ“‹ Planning Checklist (No Time Estimates) + +- [ ] Work broken down into logical phases +- [ ] Dependencies identified and mapped +- [ ] Milestones defined with clear criteria +- [ ] Complexity levels assigned to each phase +- [ ] Platform requirements identified +- [ ] Testing strategy planned +- [ ] Risk factors identified +- [ ] Success criteria defined + +## 🎯 Example Planning (No Time Estimates) + +### **Example 1: Simple Feature** +``` +Phase 1: Core implementation +- Basic functionality +- Single platform support +- Unit tests + +Phase 2: Platform expansion +- Multi-platform support +- Integration tests + +Phase 3: Polish +- User testing +- Edge case handling +``` + +### **Example 2: Complex Cross-Platform Feature** +``` +Phase 1: Foundation +- Architecture design +- Core service implementation +- Basic web platform support + +Phase 2: Platform Integration +- Mobile platform support +- Desktop platform support +- Cross-platform consistency + +Phase 3: Testing & Polish +- Comprehensive testing +- Error handling +- User experience refinement +``` + +## 🚫 Anti-Patterns to Avoid + +- **"This should take X days"** - Red flag for time estimation +- **"Just a few hours"** - Ignores complexity and testing +- **"Similar to X"** - Without considering differences +- **"Quick fix"** - Nothing is ever quick in software +- **"No testing needed"** - Testing always takes effort + +## βœ… Best Practices + +### **When Planning:** +1. **Break down everything** - no work is too small to plan +2. **Consider all platforms** - web, mobile, desktop differences +3. **Include testing strategy** - unit, integration, and user testing +4. **Account for unknowns** - there are always surprises +5. **Focus on dependencies** - what blocks what + +### **When Presenting Plans:** +1. **Show the phases** - explain the logical progression +2. **Highlight dependencies** - what could block progress +3. **Define milestones** - clear success criteria +4. **Identify risks** - what could go wrong +5. **Suggest alternatives** - ways to reduce scope or complexity + +## πŸ”„ Continuous Improvement + +### **Track Progress** +- Record planned vs. actual phases completed +- Identify what took longer than expected +- Learn from complexity misjudgments +- Adjust planning process based on experience + +### **Learn from Experience** +- **Underestimated complexity**: Increase complexity categories +- **Missed dependencies**: Improve dependency mapping +- **Platform surprises**: Better platform research upfront + +## 🎯 Integration with Harbor Pilot + +This rule works in conjunction with: +- **Project Planning**: Focuses on phases and milestones +- **Resource Allocation**: Based on complexity, not time +- **Risk Management**: Identifies blockers and dependencies +- **Stakeholder Communication**: Sets progress-based expectations + +## πŸ“ Version History + +### v2.0.0 (2025-08-21) +- **Major Change**: Completely removed time estimation approach +- **New Focus**: Phases, milestones, and complexity-based planning +- **Eliminated**: All time multipliers, estimates, and calculations +- **Added**: Dependency mapping and progress milestone framework + +### v1.0.0 (2025-08-21) +- Initial creation based on user feedback about estimation accuracy +- ~~Established realistic estimation multipliers and process~~ +- ~~Added comprehensive estimation checklist and examples~~ +- Integrated with Harbor Pilot planning and risk management + +--- + +## 🚨 Remember + +**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.** + +## 🚨 Remember + +**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.**