# Systematic Debugging

4-phase root cause debugging: understand bugs before fixing.

- Repository: https://github.com/mateaix/mateclaw (1176 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mateaix/mateclaw --skill systematic-debugging -g -a claude-code -y`
Codex: `npx skills add mateaix/mateclaw --skill systematic-debugging -g -a codex -y`
Cursor: `npx skills add mateaix/mateclaw --skill systematic-debugging -g -a cursor -y`
Gemini CLI: `npx skills add mateaix/mateclaw --skill systematic-debugging -g -a gemini-cli -y`

## Description

4-phase root cause debugging: understand bugs before fixing.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

If you haven't completed Phase 1, you cannot propose fixes.

## When to Use

Use for ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

**Use this ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue

**Don't skip when:**
- Issue seems simple (simple bugs have root causes too)
- You're in a hurry (rushing guarantees rework)
- Someone wants it fixed NOW (systematic is faster than thrashing)

## The Four Phases

You MUST complete each phase before proceeding to the next.

---

## Phase 1: Root Cause Investigation

**BEFORE attempting ANY fix:**

### 1. Read Error Messages Carefully

- Don't skip past errors or warnings
- They often contain the exact solution
- Read stack traces completely
- Note line numbers, file paths, error codes

**Action:** Use `read_file` on the relevant source files. Use `search_files` to find the error string in the codebase.

### 2. Reproduce Consistently

- Can you trigger it reliably?
- What are the exact steps?
- Does it happen every time?
- If not reproducible → gather more data, don't guess

**Action:** Use the `terminal` tool to run the failing test or trigger the bug:

```bash
# Run specific failing test
pytest tests/test_module.py::test_name -v

# Run with verbose output
pytest tests/test_module.py -v --tb=long
```

### 3. Check Recent Changes

The rest: https://github.com/mateaix/mateclaw/blob/HEAD/mateclaw-server/src/main/resources/skills/systematic-debugging/SKILL.md