# Structured Debugging

Hypothesis-driven debugging methodology for hard bugs.

- Repository: https://github.com/QwenLM/qwen-code (28858 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

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

## Description

Hypothesis-driven debugging methodology for hard bugs. Use this skill whenever you're investigating non-trivial bugs, unexpected behavior, flaky tests, or tracing issues through complex systems. Activate proactively when debugging requires more than a quick glance, especially when the first attempt at a fix didn't work, when behavior seems "impossible", or when you're tempted to blame an external system (model, API, library) without evidence.

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

# Structured Debugging

When debugging hard issues, the natural instinct is to form a theory and
immediately apply a fix. This fails more often than it works. The fix addresses
the wrong cause, adds complexity, creates false confidence, and obscures the
real issue. Worse, after several failed attempts you lose track of what's been
tried and start guessing randomly.

This methodology replaces guessing with a disciplined cycle that converges on
the root cause. Each iteration narrows the search space. It's slower per attempt
but dramatically faster overall because you stop wasting runs on wrong theories.

## The Cycle

### 1. Hypothesize

Before touching code, write down what you think is happening and why. Be
specific about the expected state at each step in the execution path.

Bad: "Something is wrong with the wait loop." Good: "The leader hangs because
`hasActiveTeammates()` returns true after all agents have reported completed,
likely because terminal status isn't being set on the agent object after the
backend process exits."

For bugs you expect to take more than one round, create a side note file for the
investigation in whichever location the project uses for such notes.

Write your hypothesis there. This file persists across conversation turns and
even across sessions, it's your investigation journal.

### 2. Design Instrumentation

Add targeted debug logs or assertions at the exact decision points that would
confirm or reject your hypothesis. Think about what data you need to see.

Don't scatter `console.log` everywhere. Identify the 2-3 places where your
hypothesis makes a testable prediction, and instrument those.

Prefer logging _values_ (return codes, payload contents, stream types, message
bodies, env state) over _presence checks_ ("was this function called?", "was
this branch taken?"). Code-path traces tell you what ran; data traces tell you
what it ran on. Most non-trivial bugs are correct code processing wrong data.

The rest: https://github.com/QwenLM/qwen-code/blob/HEAD/.qwen/skills/structured-debugging/SKILL.md