Debugging

Find where observed behavior first departs from its contract before choosing a repair. This workflow combines Matt Pocock's diagnosing-bugs, obra/superpowers' systematic-debugging, Octocode's problem framing and causal receipts, and Cursor's verify-this. Their process choices are attributed below; they are not guarantees about debugging speed or success.

Apply only the routes and checks for the selected job. Read a linked skill's named file from its installed folder when available, or from the linked source. Report an unavailable required reference instead of inventing it. [skill-authoring, DISTRIBUTION.md#composing-skills]

The job	Read
Classify the request, build a reproducer, trace the cause and choose a repair	SKILL.md
Test a falsifiable claim, compare evidence and state a verdict	VERIFICATION.md

The rules

Name the violated contract. Record actual behavior, expected behavior, its authority, the trigger, impact, success criterion and non-goals. A test, specification, schema, documented promise, accepted criterion or established behavior can supply that authority. Keep the classification unresolved while decisive facts are missing. [bgauryy/octocode, octocode-research/references/problem-framing.md]
Get a signal that can catch this bug. Prefer a small repeatable reproducer that fails on the user's exact symptom. A command merely finishing without an error is insufficient. If a reproducer is unavailable, describe the equivalent evidence and its limit rather than claim reproduction. [mattpocock/skills, diagnosing-bugs/SKILL.md] [bgauryy/octocode, octocode-research/references/workflow-debug.md]
Trace the cause through callers. Read the complete error and stack, follow the bad value back to its origin, and inspect the relevant component boundaries. Repair the shared cause rather than add a patch to each symptomatic caller. [obra/superpowers, systematic-debugging/SKILL.md, systematic-debugging/root-cause-tracing.md]
Separate competing explanations. State a prediction for each plausible cause, then change one variable at a time. A failed probe revises the explanation; it does not justify stacking another speculative fix on the last one. [mattpocock/skills, diagnosing-bugs/SKILL.md] [obra/superpowers, systematic-debugging/SKILL.md]
Make one repair and verify the original case. A smaller reproducer helps diagnosis, but success must also cover the original scenario. Keep unrelated refactoring outside the repair. [mattpocock/skills, diagnosing-bugs/SKILL.md] [obra/superpowers, systematic-debugging/SKILL.md]
Keep claims within the evidence. State the mechanism, trigger, decisive anchors, rejected alternative and remaining uncertainty. Use VERIFICATION.md for a completion or improvement claim. [bgauryy/octocode, octocode-research/references/workflow-debug.md] [cursor/plugins, verify-this/SKILL.md]