Debug Systematically

Five-phase systematic debugging: reproduce → isolate → root-cause → fix-with-regression-test → verify. Follows Code.md §11.4. Never proposes a fix before root cause is confirmed. Fixes address the root cause, not the surface symptom. Every fix begins with a failing test that reproduces the bug.

Class skillID skill/debug-systematicallyVersion 1.0.0Lifecycle stableAuthor convergent-systems-key

codedebugtddroot-causeregression

Inputs

Name	Type	Description
`bug_report`	`string`	Description of the observed failure, error message, or unexpected behavior.
`reproduction_steps` optional	`string`	Known steps to trigger the bug, if available.
`codebase_context` optional	`string`	Relevant code snippets, file paths, or architectural context.

Outputs

Name	Type	Description
`reproduction`	`string`	Confirmed reproduction case.
`root_cause`	`string`	Named root cause with evidence.
`fix`	`string`	Minimal fix addressing the root cause.
`regression_test`	`string`	Test that would have caught this bug.
`gap_analysis`	`string`	Why this was not caught and what closes the gap.

Side effects

may write files (regression test and fix)

System prompt fragment

Debug using the five-phase protocol. Do not skip or reorder phases.

REPRODUCE — establish a reliable reproduction. If you cannot reproduce, the bug report is the work product; do not guess. Name the exact steps, inputs, and observed versus expected output.
ISOLATE — narrow the failure to the smallest possible surface. Strip away unrelated code, config, and environment variables until the bug is isolated.
ROOT CAUSE — name the root cause explicitly. The fix must address this, not the surface symptom. A symptom-fix is a defect dressed as a fix.
FIX WITH REGRESSION TEST — write a failing test that reproduces the bug first. Then write the minimal fix. The fix is the smallest change that addresses the root cause.
VERIFY — run the test suite. Cite the test-runner output. Claim 'fixed' only after citing the run. After fixing, ask: 'Why was this not caught?' Name the gap — missing coverage, missing validation, missing type safety, missing observability — and either address it or file a follow-up.

Apply the 3-cycle local cap: after three failed attempts using the same approach, stop, name what is not working, propose an alternative, and ask before continuing.

Attribution: convergent-systems-key. License: Apache-2.0 or as stated by the originating repository.