## Minimal Reproducible Example

**Environment**:
- OS: macOS 13.2
- Python: 3.11.2
- Key packages: pandas==2.0.0, numpy==1.24.1

**Steps to reproduce**:
1. Create file `test.py` with:
   ```python
   [minimal code]

**If not reproducible**:
- Document pattern: Time of day? Specific data? After certain actions?
- Gather logs from failed vs successful runs
- Consider: Race conditions, memory leaks, network issues, caching

### Phase 3: Hypothesize (Extended Thinking for Complex Issues)

**Goal**: Generate testable theories about the root cause

**For simple bugs** (single-layer, obvious):
- Quick hypothesis based on error message or symptoms
- Example: "Import error → missing package"
- Skip extended thinking, proceed to test

**For complex bugs** (multi-layer, unclear root cause):
- **Use extended thinking** (8,192-16,384 token budget)
- Think deeply about possible causes before proposing solutions
- Consider multiple hypotheses, evaluate likelihood
- Map dependency chains and interaction points

**Extended thinking prompt for complex bugs**:
> "I need to think deeply about the root cause of this issue before proposing a fix. Let me consider:
> 1. What are all the possible causes for these symptoms?
> 2. Which hypotheses are most likely based on the evidence?
> 3. What would distinguish between these hypotheses?
> 4. What's the most efficient testing order?"

**Hypothesis evaluation criteria**:
- **Evidence fit**: Does this explain all observed symptoms?
- **Simplicity**: Prefer simpler explanations (Occam's razor)
- **Precedent**: Have similar bugs had this cause?
- **Testability**: Can we quickly verify this theory?

**Good hypothesis characteristics**:
- Specific and testable: "The file path contains spaces, breaking the shell command"
- Explains all symptoms: "This accounts for why it works in directory A but not B"
- Falsifiable: "If I escape spaces in the path, it should work"

**Bad hypothesis characteristics**:
- Vague: "Something's wrong with the environment"
- Untestable: "It's probably a race condition somewhere"
- Doesn't fit evidence: "Must be a version mismatch" when versions are identical

### Phase 4: Test (Validate Hypotheses)

**Goal**: Systematically test each hypothesis until root cause is found

**Testing principles**:
- **One variable at a time**: Change only what's needed to test the hypothesis
- **Controlled comparison**: Failed case vs working case, differ by one variable
- **Document results**: Record what was tested and what happened
- **Iterate quickly**: Start with fastest tests first

**Test design template**:
```markdown
## Hypothesis Test

**Hypothesis**: [What you think is causing the issue]

**Prediction**: If this hypothesis is correct, then [specific expected outcome]

**Test**:
1. [Specific change to make]
2. [How to run the test]
3. [What to observe]

**Result**: [What actually happened]

**Conclusion**: Hypothesis [CONFIRMED | REJECTED | PARTIALLY SUPPORTED]

# FIX: Escape spaces in file path to prevent shell command failure
# Root cause: Path "/home/user/my files/data.csv" treated as two arguments
# Without escaping, shell sees: cat /home/user/my files/data.csv
#                                     ^^^arg1^^^ ^^^arg2^^^
# With escaping: cat "/home/user/my files/data.csv"
file_path = shlex.quote(file_path)

## Fix Verification

**Test 1: Original reproduction case**
- Steps: [exact steps from Phase 2]
- Result: ✅ PASS - No longer fails

**Test 2: Edge case - empty input**
- Steps: Run with empty file
- Result: ✅ PASS - Handles gracefully

**Test 3: Edge case - very large file**
- Steps: Run with 10GB file
- Result: ✅ PASS - No memory errors

**Test 4: Regression check**
- Steps: Run existing test suite (pytest)
- Result: ✅ PASS - All 127 tests pass

**Test 5: Performance check**
- Before fix: 2.3s average
- After fix: 2.4s average
- Result: ✅ ACCEPTABLE - <5% change

# Bug Report: [Brief Description]

**Date**: 2026-01-29
**Severity**: Critical | Major | Minor
**Status**: RESOLVED

## Symptoms
[What was happening - error messages, unexpected behavior]

## Root Cause
[What was actually wrong - the underlying issue, not just symptoms]

## Investigation Process
[Brief summary of how root cause was found]
- Hypothesis 1: [Tested, rejected because...]
- Hypothesis 2: [Tested, confirmed because...]

## Solution
[What was changed to fix it]

```diff
- [old code]
+ [new code]

**Where to document**:
- **Code comments**: At the fix location (brief)
- **Commit message**: Detailed explanation
- **Issue tracker**: If using GitHub Issues, Jira, etc.
- **Project documentation**: Common issues and solutions
- **Personal notes**: Lessons learned for similar future bugs

## Escalation Triggers

Stop and use AskUserQuestion when:

- [ ] **Cannot reproduce**: Tried multiple approaches, issue won't reproduce reliably
- [ ] **Insufficient information**: Missing critical context (credentials, data, environment access)
- [ ] **Multiple viable hypotheses**: Extended thinking identified 2-3 equally plausible causes, need domain expertise to choose
- [ ] **Fix requires architectural change**: Root cause suggests need for major refactoring
- [ ] **Uncertain about safety**: Proposed fix might have unintended consequences in production
- [ ] **Time budget exceeded**: Estimated time was 2 hours, now at 4+ hours with no resolution
- [ ] **Needs expert knowledge**: Issue involves unfamiliar domain (e.g., network protocols, database internals)
- [ ] **Intermittent with no pattern**: Bug appears randomly, no discernible trigger
- [ ] **Affects production**: Issue is in live system, need approval before making changes

**Escalation format** (use AskUserQuestion):

## Integration with Other Skills

**Hand off to Copilot**:
- After fixing: "Review this fix for edge cases I might have missed"
- Use copilot's adversarial review to catch regressions

**Hand off to Software-Developer**:
- After identifying architectural issue: "Root cause suggests need for [refactoring]"
- Software-developer can design proper solution

**Hand off to Bioinformatician**:
- For domain-specific debugging: "Bug is in RNA-seq normalization, need domain expertise"

**Hand off to Systems-Architect**:
- When fix requires system redesign: "Current architecture can't handle [requirement]"

**Coordinate with Technical-PM**:
- When debugging exceeds time estimate: "Need to re-prioritize vs other tasks"

## Extended Thinking Integration

**When to use extended thinking**:
- Complex multi-layer bugs (network + database + application)
- Intermittent issues with no obvious pattern
- Multiple interacting systems (microservices, distributed systems)
- Performance bugs (profiling data is ambiguous)
- Security vulnerabilities (need to think about attack vectors)

**Extended thinking budget**:
- Simple bugs (single component, clear error): 0 tokens (don't use extended thinking)
- Moderate complexity (2-3 components, unclear cause): 4,096 tokens
- High complexity (multi-layer, intermittent): 8,192 tokens
- Very high complexity (distributed systems, race conditions): 16,384 tokens

**How to use extended thinking effectively**:
- Frame as open-ended exploration: "Let me think deeply about..."
- Avoid step-by-step prescriptive prompts (2026 best practice)
- Let the model creatively explore the problem space
- Use for hypothesis generation in Phase 3

## Common Pitfalls

### 1. Jumping to Solutions Without Understanding
**Symptom**: Proposing fixes in first 5 minutes without investigation
**Why it happens**: Pressure to resolve quickly, pattern matching to similar past issues
**Fix**: Force yourself through Phase 1 (Understand) and Phase 2 (Reproduce) before Phase 5 (Fix). Understand the problem fully.

### 2. Changing Multiple Variables Simultaneously
**Symptom**: "I upgraded pandas, changed the normalization method, and switched to Python 3.11 - now it works!"
**Why it happens**: Impatience, wanting to try "everything that might help"
**Fix**: Change one variable at a time. If you must batch changes, binary search: revert half, see if still works.

### 3. Stopping at Symptoms Instead of Root Cause
**Symptom**: Adding `try/except` to suppress error without understanding why error occurs
**Why it happens**: Pressure to "make it work," treating symptom as the problem
**Fix**: Ask "why does this error occur in the first place?" Keep asking "why" until you reach root cause.

### 4. Not Creating Minimal Reproducible Example
**Symptom**: Debugging in full production codebase with 50 files and 20 dependencies
**Why it happens**: Fear of missing context, not wanting to "waste time" simplifying
**Fix**: Simplification often reveals the bug immediately. Isolate to minimal case—this is rarely wasted time.

### 5. Confirmation Bias in Testing
**Symptom**: Only testing scenarios where you expect the fix to work
**Why it happens**: Wanting the fix to work, avoiding evidence of failure
**Fix**: Actively test edge cases and scenarios where fix might fail. Be adversarial with your own solution.

### 6. Skipping Documentation
**Symptom**: Fix works, move on immediately without recording what was learned
**Why it happens**: Time pressure, "I'll remember this"
**Fix**: Document immediately while details are fresh. Future you (3 months later) won't remember.

### 7. Not Verifying No Regressions
**Symptom**: Fix solves new issue but breaks existing functionality
**Why it happens**: Narrow focus on the bug, not considering broader system
**Fix**: Run full test suite. If no tests exist, manually verify key workflows still work.

### 8. Ignoring Intermittent Issues
**Symptom**: "It failed once, but I can't reproduce it, so I'll ignore it"
**Why it happens**: Can't fix what can't be reproduced
**Fix**: Intermittent bugs are the most dangerous. Add logging, run stress tests, document pattern even if can't reproduce on demand.

## Handoffs

| Condition | Hand off to |
|-----------|-------------|
| Fix needs code review | **Copilot** |
| Bug requires domain expertise | **Bioinformatician** or **Biologist-Commentator** |
| Root cause suggests architectural issue | **Systems-Architect** |
| Fix is complex implementation | **Software-Developer** |
| Debugging exceeds time budget | **Technical-PM** (re-prioritize) |

## Outputs

- Minimal reproducible examples
- Hypothesis test results
- Root cause analysis
- Implemented fixes with verification
- Bug reports and documentation
- Prevention recommendations

## Success Criteria

Fix is complete when:
- [ ] Root cause identified and understood (not just symptom)
- [ ] Fix implemented and tested
- [ ] Original reproduction case no longer fails
- [ ] No regressions in existing functionality
- [ ] Edge cases verified
- [ ] Solution documented (code comments + bug report)
- [ ] Prevention strategy identified (if applicable)

---

## Supporting Resources

**Example outputs** (see `examples/` directory):
- `bug-report-example.md` - Complete bug report from symptom to solution
- `minimal-reproduction-example.md` - How to create minimal test cases
- `hypothesis-testing-example.md` - Systematic hypothesis validation

**Quick references** (see `references/` directory):
- `common-error-patterns.md` - Frequent bugs and their typical causes
- `debugging-tools.md` - Profilers, debuggers, logging strategies
- `testing-strategies.md` - Binary search, isolation, differential testing

**When to consult**:
- Before starting → Review workflow phases to stay systematic
- When stuck → Check common-error-patterns.md for similar issues
- When testing → Use testing-strategies.md for effective test design
- When documenting → Reference bug-report-example.md for format