feat: implement enhanced workflow state system with commit override capability
- Add commit override mechanism to workflow state constraints - Enhance meta_bug_diagnosis.mdc with comprehensive investigation workflow - Implement workflow state enforcement across all meta-rules - Add always_on_rules.mdc for core rule bundling - Update all meta-rules to support workflow state management - Maintain version control standards while providing workflow flexibility Security: No code execution changes, workflow rule updates only Migration: Workflow infrastructure enhancement, no database changes Testing: Manual validation of workflow state constraints Documentation: Comprehensive workflow documentation and examples Closes: Workflow state rigidity issue Enables: Commits on demand during investigation phases
This commit is contained in:
Matthew Raymer
@@ -1,169 +1,285 @@
|
||||
# Meta-Rule: Bug Diagnosis
|
||||
# Meta-Rule: Bug Diagnosis Workflow
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-21
|
||||
**Status**: 🎯 **ACTIVE** - Bug investigation workflow bundling
|
||||
**Date**: August 24, 2025
|
||||
**Status**: 🎯 **ACTIVE** - Core workflow for all bug investigation
|
||||
|
||||
## Purpose
|
||||
|
||||
This meta-rule bundles all the rules needed for systematic bug investigation
|
||||
and root cause analysis. Use this when bugs are reported, performance
|
||||
issues occur, or unexpected behavior happens.
|
||||
This meta-rule defines the systematic approach for investigating and diagnosing
|
||||
bugs, defects, and unexpected behaviors in the TimeSafari application. It ensures
|
||||
consistent, thorough, and efficient problem-solving workflows.
|
||||
|
||||
## Workflow Constraints
|
||||
|
||||
**This meta-rule enforces DIAGNOSIS MODE for all bundled sub-rules:**
|
||||
|
||||
```json
|
||||
{
|
||||
"workflowMode": "diagnosis",
|
||||
"constraints": {
|
||||
"mode": "read_only",
|
||||
"forbidden": ["modify", "create", "build", "commit"],
|
||||
"required": "complete_investigation_before_fixing"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**All bundled sub-rules automatically inherit these constraints.**
|
||||
|
||||
## Workflow State Update
|
||||
|
||||
**When this meta-rule is invoked, update the workflow state file:**
|
||||
|
||||
```json
|
||||
{
|
||||
"currentMode": "diagnosis",
|
||||
"lastInvoked": "meta_bug_diagnosis.mdc",
|
||||
"timestamp": "2025-01-27T15:30:00Z",
|
||||
"constraints": {
|
||||
"mode": "read_only",
|
||||
"forbidden": ["modify", "create", "build", "commit"],
|
||||
"allowed": ["read", "search", "analyze", "document"],
|
||||
"required": "complete_investigation_before_fixing"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**State File Location**: `.cursor/rules/.workflow_state.json`
|
||||
|
||||
**This enables the core always-on rule to enforce diagnosis mode constraints.**
|
||||
|
||||
## When to Use
|
||||
|
||||
- **Bug Reports**: Investigating reported bugs or issues
|
||||
- **Performance Issues**: Diagnosing slow performance or bottlenecks
|
||||
- **Unexpected Behavior**: Understanding why code behaves unexpectedly
|
||||
- **Production Issues**: Investigating issues in live environments
|
||||
- **Test Failures**: Understanding why tests are failing
|
||||
- **Integration Problems**: Diagnosing issues between components
|
||||
**ALWAYS** - Apply this workflow to every bug investigation, regardless of
|
||||
severity or complexity. This ensures systematic problem-solving and prevents
|
||||
common investigation pitfalls.
|
||||
|
||||
## Bundled Rules
|
||||
|
||||
### **Investigation Process**
|
||||
### **Investigation Foundation**
|
||||
|
||||
- **`development/research_diagnostic.mdc`** - Systematic investigation
|
||||
workflow with evidence collection and analysis
|
||||
- **`development/investigation_report_example.mdc`** - Investigation
|
||||
documentation templates and examples
|
||||
- **`core/harbor_pilot_universal.mdc`** - Technical guide creation
|
||||
for complex investigations
|
||||
- **`development/research_diagnostic.mdc`** - Research and investigation methodologies
|
||||
- **`development/logging_standards.mdc`** - Logging and debugging best practices
|
||||
- **`development/type_safety_guide.mdc`** - Type safety and error prevention
|
||||
|
||||
### **Evidence Collection**
|
||||
### **Development Workflow**
|
||||
|
||||
- **`development/logging_standards.mdc`** - Logging implementation
|
||||
standards for debugging and evidence collection
|
||||
- **`development/time.mdc`** - Timestamp requirements and time
|
||||
handling standards for evidence
|
||||
- **`development/time_examples.mdc`** - Practical examples of
|
||||
proper time handling in investigations
|
||||
- **`workflow/version_control.mdc`** - Version control during investigation
|
||||
- **`development/software_development.mdc`** - Development best practices
|
||||
|
||||
### **Technical Context**
|
||||
## Critical Development Constraints
|
||||
|
||||
- **`app/timesafari.mdc`** - Core application context and
|
||||
architecture for understanding the system
|
||||
- **`app/timesafari_platforms.mdc`** - Platform-specific
|
||||
considerations and constraints
|
||||
### **🚫 NEVER Use Build Commands During Diagnosis**
|
||||
|
||||
## Workflow Sequence
|
||||
**Critical Rule**: Never use `npm run build:web` or similar build commands during bug diagnosis
|
||||
|
||||
### **Phase 1: Initial Investigation (Start Here)**
|
||||
- **Reason**: These commands block the chat and prevent effective troubleshooting
|
||||
- **Impact**: Blocks user interaction, prevents real-time problem solving
|
||||
- **Alternative**: Use safe, fast commands for investigation
|
||||
- **When to use build**: Only after diagnosis is complete and fixes are ready for testing
|
||||
|
||||
1. **Research Diagnostic** - Use `research_diagnostic.mdc` for
|
||||
systematic investigation approach
|
||||
2. **Evidence Collection** - Apply `logging_standards.mdc` and
|
||||
`time.mdc` for proper evidence gathering
|
||||
3. **Context Understanding** - Review `timesafari.mdc` for
|
||||
application context
|
||||
### **Safe Diagnosis Commands**
|
||||
|
||||
### **Phase 2: Deep Investigation**
|
||||
✅ **Safe to use during diagnosis:**
|
||||
- `npm run lint-fix` - Syntax and style checking
|
||||
- `npm run type-check` - TypeScript validation (if available)
|
||||
- `git status` - Version control status
|
||||
- `ls` / `dir` - File listing
|
||||
- `cat` / `read_file` - File content inspection
|
||||
- `grep_search` - Text pattern searching
|
||||
|
||||
1. **Platform Analysis** - Check `timesafari_platforms.mdc` for
|
||||
platform-specific issues
|
||||
2. **Technical Guide Creation** - Use `harbor_pilot_universal.mdc`
|
||||
for complex investigation documentation
|
||||
3. **Evidence Analysis** - Apply `time_examples.mdc` for proper
|
||||
timestamp handling
|
||||
❌ **Never use during diagnosis:**
|
||||
- `npm run build:web` - Blocks chat
|
||||
- `npm run build:electron` - Blocks chat
|
||||
- `npm run build:capacitor` - Blocks chat
|
||||
- Any long-running build processes
|
||||
|
||||
### **Phase 3: Documentation & Reporting**
|
||||
## Investigation Workflow
|
||||
|
||||
1. **Investigation Report** - Use `investigation_report_example.mdc`
|
||||
for comprehensive documentation
|
||||
2. **Root Cause Analysis** - Synthesize findings into actionable
|
||||
insights
|
||||
### **Phase 1: Problem Definition**
|
||||
|
||||
## Success Criteria
|
||||
1. **Gather Evidence**
|
||||
- Error messages and stack traces
|
||||
- User-reported symptoms
|
||||
- System logs and timestamps
|
||||
- Reproduction steps
|
||||
|
||||
- [ ] **Root cause identified** with supporting evidence
|
||||
- [ ] **Evidence properly collected** with timestamps and context
|
||||
- [ ] **Investigation documented** using appropriate templates
|
||||
- [ ] **Platform factors considered** in diagnosis
|
||||
- [ ] **Reproduction steps documented** for verification
|
||||
- [ ] **Impact assessment completed** with scope defined
|
||||
- [ ] **Next steps identified** for resolution
|
||||
2. **Context Analysis**
|
||||
- When did the problem start?
|
||||
- What changed recently?
|
||||
- Which platform/environment?
|
||||
- User actions leading to the issue
|
||||
|
||||
### **Phase 2: Systematic Investigation**
|
||||
|
||||
1. **Code Inspection**
|
||||
- Relevant file examination
|
||||
- Import and dependency analysis
|
||||
- Syntax and type checking
|
||||
- Logic flow analysis
|
||||
|
||||
2. **Environment Analysis**
|
||||
- Platform-specific considerations
|
||||
- Configuration and settings
|
||||
- Database and storage state
|
||||
- Network and API connectivity
|
||||
|
||||
### **Phase 3: Root Cause Identification**
|
||||
|
||||
1. **Pattern Recognition**
|
||||
- Similar issues in codebase
|
||||
- Common failure modes
|
||||
- Platform-specific behaviors
|
||||
- Recent changes impact
|
||||
|
||||
2. **Hypothesis Testing**
|
||||
- Targeted code changes
|
||||
- Configuration modifications
|
||||
- Environment adjustments
|
||||
- Systematic elimination
|
||||
|
||||
## Investigation Techniques
|
||||
|
||||
### **Safe Code Analysis**
|
||||
|
||||
- **File Reading**: Use `read_file` tool for targeted inspection
|
||||
- **Pattern Searching**: Use `grep_search` for code patterns
|
||||
- **Semantic Search**: Use `codebase_search` for related functionality
|
||||
- **Import Tracing**: Follow dependency chains systematically
|
||||
|
||||
### **Error Analysis**
|
||||
|
||||
- **Stack Trace Analysis**: Identify error origin and propagation
|
||||
- **Log Correlation**: Match errors with system events
|
||||
- **Timeline Reconstruction**: Build sequence of events
|
||||
- **Context Preservation**: Maintain investigation state
|
||||
|
||||
### **Platform Considerations**
|
||||
|
||||
- **Web Platform**: Browser-specific behaviors and limitations
|
||||
- **Electron Platform**: Desktop app considerations
|
||||
- **Capacitor Platform**: Mobile app behaviors
|
||||
- **Cross-Platform**: Shared vs. platform-specific code
|
||||
|
||||
## Evidence Collection Standards
|
||||
|
||||
### **Timestamps**
|
||||
|
||||
- **UTC Format**: All timestamps in UTC for consistency
|
||||
- **Precision**: Include milliseconds for precise correlation
|
||||
- **Context**: Include relevant system state information
|
||||
- **Correlation**: Link events across different components
|
||||
|
||||
### **Error Context**
|
||||
|
||||
- **Full Error Objects**: Capture complete error information
|
||||
- **Stack Traces**: Preserve call stack for analysis
|
||||
- **User Actions**: Document steps leading to error
|
||||
- **System State**: Capture relevant configuration and state
|
||||
|
||||
### **Reproduction Steps**
|
||||
|
||||
- **Clear Sequence**: Step-by-step reproduction instructions
|
||||
- **Environment Details**: Platform, version, configuration
|
||||
- **Data Requirements**: Required data or state
|
||||
- **Expected vs. Actual**: Clear behavior comparison
|
||||
|
||||
## Investigation Documentation
|
||||
|
||||
### **Problem Summary**
|
||||
|
||||
- **Issue Description**: Clear, concise problem statement
|
||||
- **Impact Assessment**: Severity and user impact
|
||||
- **Scope Definition**: Affected components and users
|
||||
- **Priority Level**: Based on impact and frequency
|
||||
|
||||
### **Investigation Log**
|
||||
|
||||
- **Timeline**: Chronological investigation steps
|
||||
- **Evidence**: Collected information and findings
|
||||
- **Hypotheses**: Tested theories and results
|
||||
- **Conclusions**: Root cause identification
|
||||
|
||||
### **Solution Requirements**
|
||||
|
||||
- **Fix Description**: Required changes and approach
|
||||
- **Testing Strategy**: Validation and verification steps
|
||||
- **Rollback Plan**: Reversion strategy if needed
|
||||
- **Prevention Measures**: Future issue prevention
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### **Investigation Completeness**
|
||||
|
||||
- **Evidence Sufficiency**: Adequate information for root cause
|
||||
- **Alternative Theories**: Considered and eliminated
|
||||
- **Platform Coverage**: All relevant platforms investigated
|
||||
- **Edge Cases**: Unusual scenarios considered
|
||||
|
||||
### **Documentation Quality**
|
||||
|
||||
- **Clear Communication**: Understandable to all stakeholders
|
||||
- **Technical Accuracy**: Precise technical details
|
||||
- **Actionable Insights**: Clear next steps and recommendations
|
||||
- **Knowledge Transfer**: Lessons learned for future reference
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Don't skip evidence collection** - leads to speculation
|
||||
- **Don't ignore platform differences** - misses platform-specific issues
|
||||
- **Don't skip documentation** - loses investigation insights
|
||||
- **Don't assume root cause** - verify with evidence
|
||||
- **Don't ignore time context** - misses temporal factors
|
||||
- **Don't skip reproduction steps** - makes verification impossible
|
||||
### **Investigation Mistakes**
|
||||
|
||||
## Integration Points
|
||||
- **Jumping to Solutions**: Implementing fixes before understanding
|
||||
- **Insufficient Evidence**: Making assumptions without data
|
||||
- **Platform Blindness**: Ignoring platform-specific behaviors
|
||||
- **Scope Creep**: Expanding investigation beyond original problem
|
||||
|
||||
### **With Other Meta-Rules**
|
||||
### **Communication Issues**
|
||||
|
||||
- **Feature Planning**: Use complexity assessment for investigation planning
|
||||
- **Bug Fixing**: Investigation results feed directly into fix implementation
|
||||
- **Feature Implementation**: Investigation insights inform future development
|
||||
- **Technical Jargon**: Using unclear terminology
|
||||
- **Missing Context**: Insufficient background information
|
||||
- **Unclear Recommendations**: Vague or ambiguous next steps
|
||||
- **Poor Documentation**: Incomplete or unclear investigation records
|
||||
|
||||
### **With Development Workflow**
|
||||
## Success Criteria
|
||||
|
||||
- Investigation findings inform testing strategy
|
||||
- Root cause analysis drives preventive measures
|
||||
- Evidence collection improves logging standards
|
||||
- [ ] **Problem clearly defined** with sufficient evidence
|
||||
- [ ] **Root cause identified** through systematic investigation
|
||||
- [ ] **Solution approach determined** with clear requirements
|
||||
- [ ] **Documentation complete** for knowledge transfer
|
||||
- [ ] **No chat-blocking commands** used during investigation
|
||||
- [ ] **Platform considerations** properly addressed
|
||||
- [ ] **Timeline and context** properly documented
|
||||
|
||||
## Feedback & Improvement
|
||||
## Integration with Other Meta-Rules
|
||||
|
||||
### **Sub-Rule Ratings (1-5 scale)**
|
||||
### **Bug Fixing**
|
||||
|
||||
- **Research Diagnostic**: ___/5 - Comments: _______________
|
||||
- **Investigation Report**: ___/5 - Comments: _______________
|
||||
- **Technical Guide Creation**: ___/5 - Comments: _______________
|
||||
- **Logging Standards**: ___/5 - Comments: _______________
|
||||
- **Time Standards**: ___/5 - Comments: _______________
|
||||
- **Investigation Results**: Provide foundation for fix implementation
|
||||
- **Solution Requirements**: Define what needs to be built
|
||||
- **Testing Strategy**: Inform validation approach
|
||||
- **Documentation**: Support implementation guidance
|
||||
|
||||
### **Workflow Feedback**
|
||||
### **Feature Planning**
|
||||
|
||||
- **Investigation Effectiveness**: How well did the process help find root cause?
|
||||
- **Missing Steps**: What investigation steps should be added?
|
||||
- **Process Gaps**: Where did the workflow break down?
|
||||
- **Root Cause Analysis**: Identify systemic issues
|
||||
- **Prevention Measures**: Plan future issue avoidance
|
||||
- **Architecture Improvements**: Identify structural enhancements
|
||||
- **Process Refinements**: Improve development workflows
|
||||
|
||||
### **Sub-Rule Improvements**
|
||||
### **Research and Documentation**
|
||||
|
||||
- **Clarity Issues**: Which rules were unclear or confusing?
|
||||
- **Missing Examples**: What examples would make rules more useful?
|
||||
- **Template Improvements**: How could investigation templates be better?
|
||||
|
||||
### **Overall Experience**
|
||||
|
||||
- **Time Saved**: How much time did this meta-rule save you?
|
||||
- **Quality Improvement**: Did following these rules improve your investigation?
|
||||
- **Recommendation**: Would you recommend this meta-rule to others?
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Bug Investigation
|
||||
|
||||
- [ ] **Problem Definition**: Clearly define what needs to be investigated
|
||||
- [ ] **Scope Definition**: Determine investigation scope and boundaries
|
||||
- [ ] **Evidence Planning**: Plan evidence collection strategy
|
||||
- [ ] **Stakeholder Identification**: Identify who needs to be involved
|
||||
|
||||
### During Bug Investigation
|
||||
|
||||
- [ ] **Rule Application**: Apply bundled rules in recommended sequence
|
||||
- [ ] **Evidence Collection**: Collect evidence systematically with timestamps
|
||||
- [ ] **Documentation**: Document investigation process and findings
|
||||
- [ ] **Validation**: Verify findings with reproduction steps
|
||||
|
||||
### After Bug Investigation
|
||||
|
||||
- [ ] **Report Creation**: Create comprehensive investigation report
|
||||
- [ ] **Root Cause Analysis**: Document root cause with evidence
|
||||
- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness
|
||||
- [ ] **Process Improvement**: Identify improvements for future investigations
|
||||
- **Knowledge Base**: Contribute to troubleshooting guides
|
||||
- **Pattern Recognition**: Identify common failure modes
|
||||
- **Best Practices**: Develop investigation methodologies
|
||||
- **Team Training**: Improve investigation capabilities
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/meta_feature_planning.mdc` for planning investigation work
|
||||
- `.cursor/rules/meta_bug_fixing.mdc` for implementing fixes
|
||||
- `.cursor/rules/meta_feature_implementation.mdc` for preventive measures
|
||||
- `.cursor/rules/meta_feature_planning.mdc` for planning improvements
|
||||
- `.cursor/rules/meta_documentation.mdc` for documentation standards
|
||||
|
||||
**Status**: Active meta-rule for bug diagnosis
|
||||
**Priority**: High
|
||||
|
||||
Reference in New Issue
Block a user