← Back to Engineering & QA

Debug an existing codebase

Choose a root-cause workflow for a reproducible bug, failing test, or unexpected behavior before changing production code.

Last meaningful review July 20, 2026

The job

You have a bug, error, failing test, or incorrect runtime behavior in an existing repository and need to identify the cause and verify a focused fix.

Includedreproduction and evidence gathering · root-cause investigation · verification after a fix

Not this pagegeneral code review · behavior-preserving refactoring · penetration testing

30-second route

01

The repository or language is unspecified and the task is a reproducible bug, error, failing test, or unexpected behavior.

It is the strongest direct, general-purpose match and has the best Popular rank among the selected general workflows.

Editorial confidence: high
Consider Systematic Debugging
02

The user is working in NextClaw and wants debugging integrated with test-first and completion-verification workflow routing.

It explicitly routes debugging to its systematic-debugging reference and follows with TDD and verification.

Editorial confidence: high
Consider Superpowers
03

The affected code is Python and an interactive frame, post-mortem session, subprocess, service, or remote process must be inspected.

It provides explicit tooling choices for local, post-mortem, and remote Python debugging.

Editorial confidence: high
Consider Python Debugpy

Before you install

Install

Three distinct-content finalists directly perform the task and provide usable explicit-source evidence; no build is needed.

Read the intervention guide →

Source-led comparison

What changes the choice

Facts are extracted from each selected Skill’s declared workflow. Signals describe public adoption; they are not a universal score.

Source notes

Inspect evidence and candidate limits 3 candidates

Why these candidatesEach candidate comes from tracked public sources and has a source-attributed adoption signal. This is a shortlist, not a catalogue or global ranking.

What this cannot establishWe read declared instructions and public signals. We do not run skills, benchmark outputs, audit security, or claim a universal best choice.

01

Systematic Debugging

Source ↗

Use it forGeneral reproducible bugs, failing tests, unexpected behavior, build failures, and multi-component root-cause investigations.

Avoid ifYou specifically need an interactive Python debugger or a NextClaw-packaged workflow router.

ActionInstall

EditsNone.

SetupNo setup requirement is stated in SKILL.md.

Inspect workflow and compatibility details

ContextStart with the failure, reproduce it, inspect errors and recent changes, gather boundary evidence, compare working patterns, test one hypothesis at a time, then implement and verify a focused fix.

OutputFour-phase root-cause workflow, failing regression test, single focused fix, and verification evidence.

ControlStrict phase gates: no fixes before root-cause investigation; stop and reassess after repeated failed fixes.

InvocationNot yet mapped from the source.

Install scopeNot yet mapped from the source.

Agent fitHigh: directly targets the full task across languages and repository types.

Watch outIts cited workflow is process-heavy; keep the investigation proportionate for trivial, clearly reproducible failures.

Source-visible capabilitiesRoot-cause workflowRequires reading errors, consistent reproduction, change inspection, and evidence gathering before proposing a fix.explicit sourceFocused verificationCreates a failing case, applies one root-cause fix, and verifies the original issue and broader tests.explicit source
CompatibilityGeneral technical issuesdeclarednot runtime-tested
Public signal115 /SkillsMP source-specificbest-overallroot-cause-firstgeneral-purposeexplicit source
02

Superpowers

Source ↗

Use it forNextClaw users who want debugging routed into a broader disciplined workflow with test-first fixing and verification.

Avoid ifYou are not using NextClaw, or want a standalone detailed debugging procedure without a router and bundled references.

ActionInstall

EditsNone.

SetupNextClaw marketplace install: `nextclaw skills install superpowers`. The skill checks for bundled references in `skills/superpowers/references/`.

Inspect workflow and compatibility details

ContextClassify the issue as debugging, load the bundled systematic-debugging reference, then use test-driven development once the root cause is understood and verification before closing.

OutputA selected workflow reference followed by root-cause analysis, test-first fix work when appropriate, and fresh verification evidence.

ControlRouter that defers to user instructions, repository rules, runtime constraints, and more-specific skills.

Invocationnextclaw skills install superpowers

Install scopeNextClaw marketplace

Agent fitHigh for NextClaw; medium elsewhere because this is explicitly a NextClaw adaptation.

Watch outThe detailed debugging methodology is in a bundled reference, not the top-level SKILL.md; installation must include those assets.

Source-visible capabilitiesDebug workflow routingRoutes bugs, failing tests, and unexpected behavior to the bundled systematic-debugging reference, then to TDD and verification guidance.explicit sourceHost-rule reconciliationUses bundled methodology only after reconciling it with user instructions, AGENTS.md, runtime constraints, and more-specific skills.explicit source
CompatibilityNextClawdeclarednot runtime-tested
Public signal244 /SkillsMP source-specificnextclawworkflow-routerverificationexplicit source
03

Python Debugpy

Source ↗

Use it forPython failures that need inspection of hidden state, post-mortem analysis, subprocess debugging, or local/remote attach.

Avoid ifThe repository is not Python, or the main need is a language-agnostic investigation process rather than interactive debugging.

ActionInstall

EditsAdd temporary `breakpoint()` or source-edit debugpy attach code only when appropriate; remove debugger artifacts before committing.

SetupRequires `python3`; debugpy can be installed with `python3 -m pip install debugpy` when absent.

Inspect workflow and compatibility details

ContextReproduce with the smallest command or test, choose pdb, breakpoint(), post-mortem, or debugpy based on where the failing frame is, inspect state, then rerun the normal project gate without the debugger.

OutputInteractive frame/state inspection plus rerun of the normal project test or gate.

ControlChoose the smallest debugger that reaches the bad frame; includes cleanup and local-only debug-server safeguards.

Invocationpython3 -m pdb … or python3 -m debugpy …

Install scopePython environment

Agent fitHigh for Python-specific diagnosis; low for non-Python codebases.

Watch outPID attach is injection and the skill says to avoid security-sensitive or production targets without explicit approval.

Source-visible capabilitiesDebugger selectionSelects breakpoint(), pdb, post-mortem debugging, or debugpy remote/PID attach based on the failing context.explicit sourceSafe verification and cleanupRequires a smallest reproduction, debugger cleanup, and rerunning the normal project test or gate.explicit source
CompatibilityPythondeclarednot runtime-tested
Public signal128 /SkillsMP source-specificpythoninteractive-debuggingremote-attachexplicit source

Still comparing?

Tell us the job, not just the skill names.

Request a task guide
Did this decision map help?