Systematic Debugging

Structured methodology for finding root causes before writing fixes

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add 0xranx/agentbrief --skill systematic-debugging
Manual install
git clone --depth 1 https://github.com/0xranx/agentbrief.git /tmp/agentbrief
mkdir -p ~/.claude/skills
cp -r /tmp/agentbrief/briefs/devops-sre/skills/systematic-debugging ~/.claude/skills/systematic-debugging

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

> Methodology from [obra/superpowers](https://github.com/obra/superpowers) (MIT)

# Systematic Debugging

Core rule: **find the root cause before writing any fix.**

## Phase 1 -- Root Cause Investigation

1. Reproduce the bug with the simplest possible input.
2. Read the actual error message / stack trace. Do NOT guess.
3. Trace the data flow backwards from the failure site to the origin.
4. Identify the earliest point where observed behavior diverges from expected.

## Phase 2 -- Pattern Analysis

1. Search the codebase for similar patterns (same API, same data path).
2. Check recent changes (git log, git blame) near the failure site.
3. Look for related open issues or past fixes for the same component.
4. Note if the bug is deterministic or intermittent -- intermittent implies concurrency, timing, or external state.

## Phase 3 -- Hypothesis Testing

1. Form exactly one hypothesis at a time.
2. Design a minimal experiment that can confirm or refute it.
3. Run the experiment. Read the output fully.
4. If refuted, discard the hypothesis and return to Phase 1 or 2. Do NOT patch and hope.

## Phase 4 -- Implementation

1. Write a failing test that demonstrates the root cause.
2. Apply the smallest change that makes the test pass.
3. Run the full test suite to check for regressions.
4. Verify the original reproduction case is resolved.
5. Document *why* the bug happened, not just *what* you changed.

## Anti-patterns to Avoid
Read the full skill on GitHub

Details

Skill name
systematic-debugging
Path
briefs/devops-sre/skills/systematic-debugging/SKILL.md
License
MIT
Repo updated
28 March 2026

FAQ

What does the Systematic Debugging skill do?

Structured methodology for finding root causes before writing fixes

How do I install the Systematic Debugging skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add 0xranx/agentbrief --skill systematic-debugging. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Systematic Debugging popular?

It lives in 0xranx/agentbrief, which has 43 GitHub stars and 0 forks.

Related skills

Typescript Advanced Types

43

0xranx/agentbrief

Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects.

Software Development

Analytics Setup

43

0xranx/agentbrief

When the user needs to set up product analytics, event tracking, or says 'set up analytics,' 'add tracking,' 'GA4,' 'Mixpanel,' 'PostHog,' 'Amplitude,' 'what events should we track,' 'conversion tracking,' 'funnel tracking,' or is launching a product and needs to instrument it for data collection.

Data & Analytics

API Documentation

43

0xranx/agentbrief

Create comprehensive API documentation for developers. Use when documenting REST APIs, GraphQL schemas, or SDK methods. Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides.

Software Development

Adapt Architecture

45

pjt222/agent-almanac

Execute structural metamorphosis using strangler fig migration, chrysalis phases, and interface preservation. Covers transformation planning, parallel running, progressive cutover, rollback design, and post-metamorphosis stabilization for system architecture evolution. Use when assess-form has classified the system as READY for transformation, when migrating from monolith to microservices, when replacing a core subsystem while dependents continue operating, or when any architectural change must be gradual rather than big-bang.

Software DevelopmentIn 1 list

Sparc Methodology

48

frankxai/claude-skills-library

SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) development methodology with multi-agent orchestration. Use when running a structured spec-to-code workflow or decomposing a feature through the SPARC phases.

Software Development

Add Rcpp Integration

45

pjt222/agent-almanac

Add Rcpp or RcppArmadillo integration to an R package for high-performance C++ code. Covers setup, writing C++ functions, RcppExports generation, testing compiled code, and debugging. Use when an R function is too slow and profiling confirms a bottleneck, when you need to interface with existing C/C++ libraries, or when implementing algorithms (loops, recursion, linear algebra) that benefit from compiled code.

Software DevelopmentIn 1 list

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.