debug

name	debug
description	Debugging workflow that MUST reproduce, investigate, fix, and verify unexpected behavior.
argument-hint	<describe what's broken>

Debugging Through Investigation

Debug issues through systematic investigation. This skill MUST debug problems using evidence: reproduce the issue, investigate likely causes, fix the root cause, and verify the result. It SHOULD form explicit hypotheses, test them one by one, and stop to ask for help when reproduction or confirmation is not possible.

Process

Understand the issue

• Read relevant code first.
• Ask one question at a time if clarification is needed.
• Focus on expected behavior, actual behavior, reproduction steps, timing, and recent changes.

Reproduce the issue

• Reproduce before investigating deeply.
• Run the failing test, command, or workflow when possible.
• If you cannot reproduce it, investigate why.
• Record the reproduction case so you can verify the fix later.

Form hypotheses

• Propose 2-3 likely causes.
• For each, state likelihood and how to test it.
• Present them to the user and wait for input.

Investigate

• Test hypotheses one by one.
• Read the relevant code paths.
• Check logs, state, and execution flow.
• When you find the root cause, present it clearly and wait for confirmation.

Fix

• Propose the fix before applying it.
• Make the smallest change that solves the root cause.
• Add a regression test when appropriate.

Verify

• Re-run the reproduction case.
• Run the relevant tests.
• Check nearby functionality for similar failures.

Report

Summarize:

• issue,
• root cause,
• fix,
• files changed,
• verification.

Key Principles

• One question at a time
• Reproduce first
• Follow evidence, not guesses
• Fix the root cause, not the symptom
• Verify thoroughly

When to Stop

Ask the user for help if:

• you cannot reproduce the issue,
• the fix needs domain knowledge you do not have,
• the change requires a broad architectural decision,
• multiple theories stay equally plausible.