Systematic 4-phase debugging with root cause analysis - no random fixes
Systematic 4-phase debugging that investigates root causes before proposing fixes. Use when you need methodical problem-solving instead of random trial-and-error changes.
/plugin marketplace add astrosteveo/claude-code-plugins/plugin install superharness@astrosteveo-plugins<description of issue or path to relevant file>You are tasked with helping debug issues using systematic 4-phase root cause analysis. This command allows you to investigate problems methodically - no random fixes allowed.
Phase 1: Root Cause Investigation - Gather evidence first Phase 2: Pattern Analysis - Compare working vs broken Phase 3: Hypothesis Testing - One change at a time Phase 4: Implementation - TDD for regression test
NO FIXES until you complete Phases 1-3. Find the root cause FIRST.
Debug is for SYSTEMATIC investigation, not random fixes. Use it to:
I'll help debug the issue with [context] using systematic 4-phase analysis.
Before I investigate, what specific problem are you encountering?
- What were you trying to do?
- What went wrong?
- Any error messages?
I'll find the root cause FIRST, then propose a TDD fix approach.
I'll help debug your current issue using systematic 4-phase analysis.
Please describe what's going wrong:
- What are you working on?
- What specific problem occurred?
- When did it last work?
Remember: We find root cause FIRST. No random fixes.
Wait for user input.
Goal: Gather evidence. Do NOT propose fixes yet.
Read any provided context (plan, ticket, error file):
Spawn parallel investigation tasks:
Task 1 - Check Recent Logs:
Find and analyze logs for errors:
1. Find relevant log files
2. Search for errors, warnings around problem timeframe
3. Look for stack traces or repeated errors
4. Note timestamps and error patterns
Return: Key errors/warnings with timestamps
Task 2 - Application/Database State:
Check relevant application state:
1. Examine configuration files
2. Check database state if applicable
3. Look for stuck states, stale data, anomalies
Return: Relevant state findings
Task 3 - Git and File State:
Understand what changed recently:
1. Check git status and current branch
2. Look at recent commits: git log --oneline -10
3. Check uncommitted changes: git diff
4. Check if changes correlate with issue timing
Return: Git state and any file issues
Task 4 - Code Investigation:
Examine the code around the issue:
1. Read files involved in the error
2. Trace the call path if possible
3. Look for recent changes to these files
Return: Code findings and potential issues
Wait for ALL tasks - Don't jump to conclusions
Document evidence:
Goal: Compare working behavior to broken behavior.
Find working examples:
Compare working vs broken:
Document patterns:
Goal: Form and test a SINGLE hypothesis.
Form ONE specific hypothesis:
Test MINIMALLY:
Evaluate results:
3 FAILED FIXES = STOP
If you've tried 3 fixes and none worked:
Goal: Fix with a regression test.
Write failing test FIRST:
Implement the fix:
Verify no regressions:
## Debug Report
### Issue Summary
[Clear statement of the issue based on user description and evidence]
### Phase 1: Root Cause Investigation
**From Logs:**
- [Error/warning with timestamp]
- [Pattern or repeated issue]
**From Application State:**
- [Relevant state finding]
- [Configuration issue if any]
**From Git/Files:**
- [Recent changes related to issue]
- [Uncommitted changes]
**From Code Investigation:**
- [Relevant code finding at file:line]
- [Potential bug location]
### Phase 2: Pattern Analysis
**Working Example Found:**
- `path/to/working.ts:45` - [How it works correctly]
**Comparison:**
- Working code: [description]
- Broken code: [description]
- Key difference: [what changed]
### Phase 3: Root Cause
**Hypothesis**: [Specific cause statement]
**Evidence**: [Why we believe this]
**Confidence Level**: [High/Medium/Low]
### Phase 4: Recommended Fix (TDD)
**Step 1 - Write Failing Test:**
```typescript
// Test that reproduces the bug
test('should handle [case] correctly', () => {
// Arrange
// Act
// Assert - this will fail before fix
});
Step 2 - Implement Fix:
File: path/to/file.ts:line
Change: [Description of minimal fix]
Step 3 - Verify:
npm test # All tests should pass
## Red Flags (You're Skipping the Process)
| Thought | Reality |
|---------|---------|
| "Let me try this fix" | NO. Complete Phases 1-3 first. |
| "I think I know what's wrong" | Prove it with evidence. |
| "Quick fix should work" | Quick fixes hide bugs. Find root cause. |
| "Just restart the service" | That's not debugging, that's hoping. |
| "It worked before" | What changed? Investigate. |
## Cross-References
- After debugging: `/superharness:create-plan` to plan the fix
- To document findings: `/superharness:handoff`
- For codebase understanding: `/superharness:research`