refactor: restructure cursor rules with new meta-rule architecture
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
This commit is contained in:
Matthew Raymer
288
.cursor/rules/meta_bug_diagnosis.mdc
Normal file
288
.cursor/rules/meta_bug_diagnosis.mdc
Normal file
@@ -0,0 +1,288 @@
|
||||
# Meta-Rule: Bug Diagnosis Workflow
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: August 24, 2025
|
||||
**Status**: 🎯 **ACTIVE** - Core workflow for all bug investigation
|
||||
|
||||
## Purpose
|
||||
|
||||
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
|
||||
|
||||
**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 Foundation**
|
||||
|
||||
- **`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
|
||||
|
||||
### **Development Workflow**
|
||||
|
||||
- **`workflow/version_control.mdc`** - Version control during investigation
|
||||
- **`development/software_development.mdc`** - Development best practices
|
||||
|
||||
## Critical Development Constraints
|
||||
|
||||
### **🚫 NEVER Use Build Commands During Diagnosis**
|
||||
|
||||
**Critical Rule**: Never use `npm run build:web` or similar build commands during bug diagnosis
|
||||
|
||||
- **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
|
||||
|
||||
### **Safe Diagnosis Commands**
|
||||
|
||||
✅ **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
|
||||
|
||||
❌ **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
|
||||
|
||||
## Investigation Workflow
|
||||
|
||||
### **Phase 1: Problem Definition**
|
||||
|
||||
1. **Gather Evidence**
|
||||
- Error messages and stack traces
|
||||
- User-reported symptoms
|
||||
- System logs and timestamps
|
||||
- Reproduction steps
|
||||
|
||||
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
|
||||
|
||||
### **Investigation Mistakes**
|
||||
|
||||
- **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
|
||||
|
||||
### **Communication Issues**
|
||||
|
||||
- **Technical Jargon**: Using unclear terminology
|
||||
- **Missing Context**: Insufficient background information
|
||||
- **Unclear Recommendations**: Vague or ambiguous next steps
|
||||
- **Poor Documentation**: Incomplete or unclear investigation records
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] **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
|
||||
|
||||
## Integration with Other Meta-Rules
|
||||
|
||||
### **Bug Fixing**
|
||||
|
||||
- **Investigation Results**: Provide foundation for fix implementation
|
||||
- **Solution Requirements**: Define what needs to be built
|
||||
- **Testing Strategy**: Inform validation approach
|
||||
- **Documentation**: Support implementation guidance
|
||||
|
||||
### **Feature Planning**
|
||||
|
||||
- **Root Cause Analysis**: Identify systemic issues
|
||||
- **Prevention Measures**: Plan future issue avoidance
|
||||
- **Architecture Improvements**: Identify structural enhancements
|
||||
- **Process Refinements**: Improve development workflows
|
||||
|
||||
### **Research and Documentation**
|
||||
|
||||
- **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_bug_fixing.mdc` for implementing fixes
|
||||
- `.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
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: All bundled sub-rules
|
||||
**Stakeholders**: Development team, QA team, DevOps team
|
||||
Reference in New Issue
Block a user