# Meta-Rule: Bug Diagnosis

**Author**: Matthew Raymer
**Date**: 2025-08-21
**Status**: 🎯 **ACTIVE** - Bug investigation workflow bundling

## 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.

## 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

## Bundled Rules

### **Investigation Process**

- **`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

### **Evidence Collection**

- **`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

### **Technical Context**

- **`app/timesafari.mdc`** - Core application context and
  architecture for understanding the system
- **`app/timesafari_platforms.mdc`** - Platform-specific
  considerations and constraints

## Workflow Sequence

### **Phase 1: Initial Investigation (Start Here)**

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

### **Phase 2: Deep Investigation**

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

### **Phase 3: Documentation & Reporting**

1. **Investigation Report** - Use `investigation_report_example.mdc`
   for comprehensive documentation
2. **Root Cause Analysis** - Synthesize findings into actionable
   insights

## Success Criteria

- [ ] **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

## 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

## Integration Points

### **With Other Meta-Rules**

- **Feature Planning**: Use complexity assessment for investigation planning
- **Bug Fixing**: Investigation results feed directly into fix implementation
- **Feature Implementation**: Investigation insights inform future development

### **With Development Workflow**

- Investigation findings inform testing strategy
- Root cause analysis drives preventive measures
- Evidence collection improves logging standards

## Feedback & Improvement

### **Sub-Rule Ratings (1-5 scale)**

- **Research Diagnostic**: ___/5 - Comments: _______________
- **Investigation Report**: ___/5 - Comments: _______________
- **Technical Guide Creation**: ___/5 - Comments: _______________
- **Logging Standards**: ___/5 - Comments: _______________
- **Time Standards**: ___/5 - Comments: _______________

### **Workflow Feedback**

- **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?

### **Sub-Rule Improvements**

- **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

---

**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

**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