Skip to content

jacob-balslev/skill-graph / marketplace/skills/debugging

debugging

Unverified

Use when behavior is broken, a test is failing, or runtime output contradicts expectations. Covers failure reproduction, scope reduction by bisection, evidence capture at the moment of failure, root-cause isolation (not symptom patching), fix verification against the same evidence path, and regression-test creation. Do NOT use for feature planning, architectural design, or behavior-preserving refactor. Do NOT use for plan test coverage for a new feature. Do NOT use for document what this function does for future readers. Do NOT use for refactor this messy code while the test suite is green.

Debugging

Concept of the skill

What it is: Debugging is the discipline of turning a broken behavior into a reproduced failure, isolating the cause, verifying the fix on the same evidence path, and preserving the case as a regression test.

Mental model: A debugging pass has six gates: reproduce the failure, reduce the scope, capture evidence at the failure point, form a hypothesis that explains all evidence, verify the fix with the same path, and add a regression test that fails without the fix.

Why it exists: Plausible explanations are cheap and often wrong. Debugging keeps the agent from patching the visible symptom before proving where the state first becomes wrong.

What it is NOT: It is not feature planning, architecture design, green-test refactoring, documentation, or test-strategy planning for a future change.

Common misconception: The newest change is not automatically the cause. It is only a hypothesis until it explains the failing path and the unaffected control paths.

Coverage

  • Reproduction: turning a vague bug report into a deterministic failing case
  • Scope reduction: isolating the smallest surface where the failure still reproduces
  • Evidence capture: collecting logs, stack traces, and state snapshots at the moment of failure
  • Root-cause isolation: distinguishing symptoms from causes and resisting the urge to patch symptoms
  • Fix verification: re-running the original failure path to confirm the fix is real
  • Regression prevention: converting the failing case into a permanent test so the same bug cannot return silently

Philosophy of the skill

The fastest way to fix a bug is usually the wrong fix. A working reproduction is worth more than a plausible hypothesis; a plausible hypothesis is worth more than a clever fix; a clever fix that skips the reproduction step ships the same bug again under a different name. When pressure is high the temptation to jump from symptom to patch is also high — resist it, because the cost of a wrong fix is paid again by the next person who hits the same failure with less context than you had.

Workflow

Each step asks a question. The answer decides the next step. Do not skip steps to save time; the steps exist because skipping them is how bugs return.

StepAskIf yesIf no
1. ReproduceDo you have a deterministic failing case?Go to step 2Add logging, narrow inputs, or run the failing path in a loop until the failure is reliable
2. ScopeCan you reproduce it in a surface smaller than the full system?Go to step 3Bisect — halve the code path, data, or config and retry
3. EvidenceDo you have the state at the moment of failure, not just the symptom after?Go to step 4Add instrumentation at the boundary where state flips wrong
4. CauseDoes your hypothesis explain ALL of the evidence, not just the visible symptom?Go to step 5Form a better hypothesis — partial explanations hide shared root causes
5. VerifyDoes the same evidence path pass with the fix applied, and fail with it reverted?Go to step 6The fix did not land or the cause was wrong — return to step 4
6. Regression testDoes the test you just wrote fail without the fix and pass with it?DoneYour test is not isolating the cause — rewrite it

When to stop and escalate

  • Step 1 is still unreproducible after ~60 min of narrowing → suspect non-determinism (race, timing, clock, network). This is a design issue, not a debugging issue.
  • Step 3 instrumentation shows contradictory state on the same object → suspect memory corruption, concurrent mutation, or stale cache. Out of scope for a single-file debugger; escalate to architectural review.
  • The same bug returned after a previous fix → the previous fix patched a symptom. Start over at step 1 and find the real cause.

Evals

This skill ships a comprehension-eval artifact at examples/evals/debugging.json. The Verification checklist below is the authoring gate for a completed debugging pass; the eval file is how this skill is graded by scripts/skill-audit.js --graded. Do not conflate them — the checklist is for the debugger, the eval is for the grader.

Verification

  • The original failure was reproduced deterministically, not just described
  • The hypothesis explains every piece of evidence collected, not a subset
  • The fix was verified by the same evidence path that revealed the bug
  • A regression test fails without the fix and passes with it
  • The next engineer who hits this failure can reach the fix from the regression test alone

Do NOT Use When

Use insteadWhen
refactorThe task is structural cleanup, not failure-driven diagnosis
testing-strategyThe task is planning what to test, not chasing a known failure
documentationThe task is explaining behavior, not fixing broken behavior

Skill Graph context

Classification

  • Subject: software-engineering-method
  • Public: true
  • Scope: Portable failure-reproduction and root-cause isolation discipline for software work: turning an observed broken behavior, failing test, or contradictory runtime output into a deterministic reproduction; narrowing scope; capturing evidence at the moment of failure; separating symptoms from causes; verifying the fix against the same evidence path; and adding a regression test. Excludes feature planning, architecture design, behavior-preserving refactor, general documentation, and choosing test coverage when no active failure is being investigated.

When to use

  • my tests pass locally but fail in CI — why?
  • this function used to work yesterday; what changed?
  • reproduce this Stripe webhook failure from production logs
  • I see the symptom but can't find the root cause of this nil panic
  • Triggers: debugging-skill

Not for

  • plan test coverage for a new feature
  • document what this function does for future readers
  • refactor this messy code while the test suite is green

Related skills

  • Verify with: testing-strategy, observability-modeling
  • Related: generative-ui, test-driven-development, testing-strategy, tool-call-strategy

Keywords

  • debugging, tests fail in CI, used to work, reproduce failure, failing test, root cause, symptom vs cause, minimum reproduction, regression, what changed
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall