feat(harbor-pilot): add historical comment management and no time estimates rules

Add two new Harbor Pilot directives to improve code quality and planning: 1. Historical Comment Management: Guidelines for transforming or removing obsolete comments into actionable architectural guidance 2. No Time Estimates: Rule prohibiting time estimates in favor of phase-based planning with complexity levels and milestones Both rules are integrated into main Harbor Pilot directive for automatic application across all operations.
21 hours ago · 6afe1c4c13
3 changed files with 586 additions and 0 deletions
--- a/.cursor/rules/harbor_pilot_universal.mdc
+++ b/.cursor/rules/harbor_pilot_universal.mdc
@ -202,3 +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 realistic time estimation rules (see `.cursor/rules/realistic_time_estimation.mdc`)
--- a/.cursor/rules/historical_comment_management.mdc
+++ b/.cursor/rules/historical_comment_management.mdc
@ -0,0 +1,236 @@
 ---
 description: when comments are generated by the model
 alwaysApply: false
 ---
 # Historical Comment Management — Harbor Pilot Directive
 > **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance.
 ## 🎯 Purpose
 Historical comments should either be **removed entirely** or **transformed into actionable guidance** for future developers. Avoid keeping comments that merely state what was removed without explaining why or what to do instead.
 ## 📋 Decision Framework
 ### Remove Historical Comments When:
 - **Obsolete Information**: Comment describes functionality that no longer exists
 - **No Action Required**: Comment doesn't help future developers make decisions
 - **Outdated Context**: Comment refers to old patterns that are no longer relevant
 - **Self-Evident**: The current code clearly shows the current approach
 ### Transform Historical Comments When:
 - **Architectural Context**: The change represents a significant pattern shift
 - **Migration Guidance**: Future developers might need to understand the evolution
 - **Decision Rationale**: The "why" behind the change is still relevant
 - **Alternative Approaches**: The comment can guide future implementation choices
 ## 🔄 Transformation Patterns
 ### 1. From Removal Notice to Migration Note
 ```typescript
 // ❌ REMOVE THIS
 // turnOffNotifyingFlags method removed - notification state is now managed by NotificationSection component
 // ✅ TRANSFORM TO THIS
 // Note: Notification state management has been migrated to NotificationSection component
 // which handles its own lifecycle and persistence via PlatformServiceMixin
 ```
 ### 2. From Deprecation Notice to Implementation Guide
 ```typescript
 // ❌ REMOVE THIS
 // This will be handled by the NewComponent now
 // No need to call oldMethod() as it's no longer needed
 // ✅ TRANSFORM TO THIS
 // Note: This functionality has been migrated to NewComponent
 // which provides better separation of concerns and testability
 ```
 ### 3. From Historical Note to Architectural Context
 ```typescript
 // ❌ REMOVE THIS
 // Old approach: used direct database calls
 // New approach: uses service layer
 // ✅ TRANSFORM TO THIS
 // Note: Database access has been abstracted through service layer
 // for better testability and platform independence
 ```
 ## 🚫 Anti-Patterns to Remove
 - Comments that only state what was removed
 - Comments that don't explain the current approach
 - Comments that reference non-existent methods
 - Comments that are self-evident from the code
 - Comments that don't help future decision-making
 ## ✅ Best Practices
 ### When Keeping Historical Context:
 1. **Explain the "Why"**: Why was the change made?
 2. **Describe the "What"**: What is the current approach?
 3. **Provide Context**: When might this information be useful?
 4. **Use Actionable Language**: Guide future decisions, not just document history
 ### When Removing Historical Context:
 1. **Verify Obsoleteness**: Ensure the information is truly outdated
 2. **Check for Dependencies**: Ensure no other code references the old approach
 3. **Update Related Docs**: If removing from code, consider adding to documentation
 4. **Preserve in Git History**: The change is preserved in version control
 ## 🔍 Implementation Checklist
 - [ ] Identify historical comments about removed/deprecated functionality
 - [ ] Determine if comment provides actionable guidance
 - [ ] Transform useful comments into migration notes or architectural context
 - [ ] Remove comments that are purely historical without guidance value
 - [ ] Ensure remaining comments explain current approach and rationale
 - [ ] Update related documentation if significant context is removed
 ## 📚 Examples
 ### Good Historical Comment (Keep & Transform)
 ```typescript
 // Note: Database access has been migrated from direct IndexedDB calls to PlatformServiceMixin
 // This provides better platform abstraction and consistent error handling across web/mobile/desktop
 // When adding new database operations, use this.$getContact(), this.$saveSettings(), etc.
 ```
 ### Bad Historical Comment (Remove)
 ```typescript
 // Old method getContactFromDB() removed - now handled by PlatformServiceMixin
 // No need to call the old method anymore
 ```
 ## 🎯 Integration with Harbor Pilot
 This rule works in conjunction with:
 - **Component Creation Ideals**: Maintains architectural consistency
 - **Migration Patterns**: Documents evolution of patterns
 - **Code Review Guidelines**: Ensures comments provide value
 ## 📝 Version History
 ### v1.0.0 (2025-08-21)
 - Initial creation based on notification system cleanup
 - Established decision framework for historical comment management
 - Added transformation patterns and anti-patterns
 - Integrated with existing Harbor Pilot architecture rules
 # Historical Comment Management — Harbor Pilot Directive
 > **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance.
 ## 🎯 Purpose
 Historical comments should either be **removed entirely** or **transformed into actionable guidance** for future developers. Avoid keeping comments that merely state what was removed without explaining why or what to do instead.
 ## 📋 Decision Framework
 ### Remove Historical Comments When:
 - **Obsolete Information**: Comment describes functionality that no longer exists
 - **No Action Required**: Comment doesn't help future developers make decisions
 - **Outdated Context**: Comment refers to old patterns that are no longer relevant
 - **Self-Evident**: The current code clearly shows the current approach
 ### Transform Historical Comments When:
 - **Architectural Context**: The change represents a significant pattern shift
 - **Migration Guidance**: Future developers might need to understand the evolution
 - **Decision Rationale**: The "why" behind the change is still relevant
 - **Alternative Approaches**: The comment can guide future implementation choices
 ## 🔄 Transformation Patterns
 ### 1. From Removal Notice to Migration Note
 ```typescript
 // ❌ REMOVE THIS
 // turnOffNotifyingFlags method removed - notification state is now managed by NotificationSection component
 // ✅ TRANSFORM TO THIS
 // Note: Notification state management has been migrated to NotificationSection component
 // which handles its own lifecycle and persistence via PlatformServiceMixin
 ```
 ### 2. From Deprecation Notice to Implementation Guide
 ```typescript
 // ❌ REMOVE THIS
 // This will be handled by the NewComponent now
 // No need to call oldMethod() as it's no longer needed
 // ✅ TRANSFORM TO THIS
 // Note: This functionality has been migrated to NewComponent
 // which provides better separation of concerns and testability
 ```
 ### 3. From Historical Note to Architectural Context
 ```typescript
 // ❌ REMOVE THIS
 // Old approach: used direct database calls
 // New approach: uses service layer
 // ✅ TRANSFORM TO THIS
 // Note: Database access has been abstracted through service layer
 // for better testability and platform independence
 ```
 ## 🚫 Anti-Patterns to Remove
 - Comments that only state what was removed
 - Comments that don't explain the current approach
 - Comments that reference non-existent methods
 - Comments that are self-evident from the code
 - Comments that don't help future decision-making
 ## ✅ Best Practices
 ### When Keeping Historical Context:
 1. **Explain the "Why"**: Why was the change made?
 2. **Describe the "What"**: What is the current approach?
 3. **Provide Context**: When might this information be useful?
 4. **Use Actionable Language**: Guide future decisions, not just document history
 ### When Removing Historical Context:
 1. **Verify Obsoleteness**: Ensure the information is truly outdated
 2. **Check for Dependencies**: Ensure no other code references the old approach
 3. **Update Related Docs**: If removing from code, consider adding to documentation
 4. **Preserve in Git History**: The change is preserved in version control
 ## 🔍 Implementation Checklist
 - [ ] Identify historical comments about removed/deprecated functionality
 - [ ] Determine if comment provides actionable guidance
 - [ ] Transform useful comments into migration notes or architectural context
 - [ ] Remove comments that are purely historical without guidance value
 - [ ] Ensure remaining comments explain current approach and rationale
 - [ ] Update related documentation if significant context is removed
 ## 📚 Examples
 ### Good Historical Comment (Keep & Transform)
 ```typescript
 // Note: Database access has been migrated from direct IndexedDB calls to PlatformServiceMixin
 // This provides better platform abstraction and consistent error handling across web/mobile/desktop
 // When adding new database operations, use this.$getContact(), this.$saveSettings(), etc.
 ```
 ### Bad Historical Comment (Remove)
 ```typescript
 // Old method getContactFromDB() removed - now handled by PlatformServiceMixin
 // No need to call the old method anymore
 ```
 ## 🎯 Integration with Harbor Pilot
 This rule works in conjunction with:
 - **Component Creation Ideals**: Maintains architectural consistency
 - **Migration Patterns**: Documents evolution of patterns
 - **Code Review Guidelines**: Ensures comments provide value
 ## 📝 Version History
 ### v1.0.0 (2025-08-21)
 - Initial creation based on notification system cleanup
 - Established decision framework for historical comment management
 - Added transformation patterns and anti-patterns
 - Integrated with existing Harbor Pilot architecture rules
--- a/.cursor/rules/realistic_time_estimation.mdc
+++ 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.**