Questions? hello@viberation.devGet supportBlogDocsChangelog

Colour mode

XGitHub
Get started

Systematic Debugging

Skills#testing

Find the root cause before proposing a fix.

From Superpowers. On any bug, failing test or unexpected behaviour, your agent investigates systematically and finds the cause before it changes any code.

Install this skill

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

Runs the open-source skills CLI in your own terminal. It asks which agents to add the skill to. Read what it tells your agent to do before you install it.

Download skill (.zip)

Install for your agent

  • Claude Code

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill systematic-debugging -a claude-code

    Add -g to install it for every project instead.

    Or ask Claude Code to do it

    Install the "systematic-debugging" skill from https://github.com/obra/superpowers for Claude Code.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .claude/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .claude/skills/ for this project, or ~/.claude/skills/ for all your projects.

    Picked up in the current session, no restart needed.

    Claude Code skills docs
  • Claude.ai

    Upload the ZIP

    1. In Settings > Capabilities, turn on Code execution and file creation.
    2. Go to Customize > Skills, press +, then Create skill.
    3. Choose Upload a skill and pick the ZIP you downloaded.

    Free, Pro and Max plans. On Team and Enterprise, an owner turns skills on in Organization settings first.

    Claude.ai skills docs
  • ChatGPT

    Upload the ZIP

    1. Open Skills in ChatGPT and select Create.
    2. Select Upload from your computer and pick the ZIP you downloaded.
    3. Wait for ChatGPT's safety scan. A skill marked Needs Review asks you to check it before use.

    Skills that rely on scripts or a terminal may not work unchanged in ChatGPT.

    ChatGPT skills docs
  • Codex

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill systematic-debugging -a codex

    Add -g to install it for every project instead.

    Or ask Codex to do it

    Install the "systematic-debugging" skill from https://github.com/obra/superpowers for Codex.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .agents/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .agents/skills/ for this project, or ~/.agents/skills/ for all your projects.

    Restart Codex if the skill does not show up.

    Codex skills docs
  • Cursor

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill systematic-debugging -a cursor

    Add -g to install it for every project instead.

    Or ask Cursor to do it

    Install the "systematic-debugging" skill from https://github.com/obra/superpowers for Cursor.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .cursor/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .cursor/skills/ for this project, or ~/.cursor/skills/ for all your projects.

    Run it by typing / and the skill name in chat.

    Cursor skills docs
  • GitHub Copilot

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill systematic-debugging -a github-copilot

    Add -g to install it for every project instead.

    Or ask GitHub Copilot to do it

    Install the "systematic-debugging" skill from https://github.com/obra/superpowers for GitHub Copilot.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .github/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .github/skills/ for this project, or ~/.copilot/skills/ for all your projects.

    Works in Copilot CLI, the cloud agent and agent mode in VS Code and JetBrains.

    GitHub Copilot skills docs
  • Antigravity

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill systematic-debugging -a antigravity

    Add -g to install it for every project instead.

    Or ask Antigravity to do it

    Install the "systematic-debugging" skill from https://github.com/obra/superpowers for Antigravity.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .agents/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .agents/skills/ for this project, or ~/.gemini/config/skills/ for all your projects.

    Antigravity skills docs
  • Gemini CLI

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill systematic-debugging -a gemini-cli

    Add -g to install it for every project instead.

    Or ask Gemini CLI to do it

    Install the "systematic-debugging" skill from https://github.com/obra/superpowers for Gemini CLI.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .gemini/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .gemini/skills/ for this project, or ~/.gemini/skills/ for all your projects.

    Run /skills to check it was found.

    Gemini CLI skills docs
Installs
257.7K via skills.sh
GitHub
286.3K stars ↗
Last updated
12 Sept 2026
Licence
MIT

Security checks

Run by independent scanners and published on skills.sh. Their results, not a Viberation review.

  • Gen Agent Trust Hub Pass

    This skill is a collection of best practices for systematic software debugging. It provides a four-phase framework (Root Cause, Pattern Analysis, Hypothesis, and Implementation) designed to prevent random fixes and symptom-masking. The included scripts and evaluation scenarios are legitimate development tools intended to reinforce engineering rigor. No malicious behavior or security risks were detected.

    5 May 2026

  • Socket Pass

    No alerts

    5 May 2026

  • Snyk Pass

    Risk: LOW · No issues

    5 May 2026

  • Runlayer Pass

    2/11 files flagged

    26 Feb 2026

  • ZeroLeaks Pass

    Score: 93/100 · 2 sections analyzed

    16 Apr 2026
What's inside (11 files)
  • condition-based-waiting-example.ts5.1K chars
  • condition-based-waiting.md3.5K chars
  • CREATION-LOG.md4.2K chars
  • defense-in-depth.md3.6K chars
  • find-polluter.sh2K chars
  • root-cause-tracing.md5.3K chars
  • SKILL.md9.4K chars
  • test-academic.md653 chars
  • test-pressure-1.md1.9K chars
  • test-pressure-2.md2.3K chars
  • test-pressure-3.md2.7K chars

SKILL.md, first part. Shown as plain text.

---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---

# Systematic Debugging

## Overview

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

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

3. **Check Recent Changes**
   - What changed that could cause this?
   - Git diff, recent commits
   - New dependencies, config changes
   - Environmental differences

4. **Gather Evidence in Multi-Component Systems**

   **WHEN system has multiple components (CI → build → signing, API → service → database):**

   **BEFORE proposing fixes, add diagnostic instrumentation:**
   ```
   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer

   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   ```

   **Example (multi-layer system):**
   ```bash
   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"

   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v

   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   ```

   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)

5. **Trace Data Flow**

   **WHEN error is deep in call stack:**

   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.

   **Quick version:**
   - Where does bad value originate?
   - What called this with bad value?
   - Keep tracing up until you find the source
   - Fix at source, not at symptom

### Phase 2: Pattern Analysis

**Find the pattern before fixing:**

1. **Find Working Examples**
   - Locate similar working code in same codebase
   - What works that's similar to what's broken?

2. **Compare Against References**
   - If implementing pattern, read reference implementation COMPLETELY
   - Don't skim - read every line
   - Understand the pattern fully before applying

3. **Identify Differences**
   - What's different between working and broken?
   - List every difference, however small
   - Don't assume "that can't matter"

4. **Understand Dependencies**
   - What other components does this need?
   - What settings, config, environment?
   - What assumptions does it make?

### Phase 3

Key info

Pricing
Open source
Category
Skills

Related reading

  • Fundamentals

    Reviewing code you did not write

    You are going to merge a lot of code you did not type. Reviewing it is a different skill from writing it, and it is the one that actually keeps a vibe-coded…

    Intermediate

More in Skills