crowd-funder-for-time-pwa/.cursor/rules/meta_bug_diagnosis.mdc

# 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