mtk-agent-toolkit: Skill for Claude Code

Debugging And Error Recovery

Current State

echo "--- Branch ---"
git branch --show-current 2>/dev/null || echo "(detached)"
echo "--- Working tree ---"
git status --short 2>/dev/null | head -15 || echo "(not a git repo)"

Overview

Start from the failure, confirm the cause, make the smallest correct fix, and verify it with build and test evidence. Guesswork is not debugging.

When To Use

• Bug fixes
• Failing tests
• Runtime errors
• Small behavioral regressions

When NOT To Use

• New feature design
• Large scope changes requiring formal planning first

Workflow

1. Reproduce: capture the failing test, error output, or behavioral evidence before editing.
2. Localize: read the failing file, its neighbors, and the most relevant standard sections.
3. Reduce: narrow the likely root cause to the smallest responsible area.
4. Hypothesize: state what you think is wrong before editing.
5. Fix: apply the smallest correction that matches the local codebase pattern.
6. Guard: add or update a regression test if behavior changed or failure could recur.
7. Verify: run the active tech stack's build/test commands (from .claude/skills/tech-stack-{stack}/SKILL.md ## Build & Test Commands).
8. Escalate to the full implementation workflow if the task grows past 3 files or needs new architecture.

Rules

• Read before editing.
• Match existing patterns.
• Do not gold-plate unrelated improvements.
• Stop after repeated failed attempts and explain what is blocking forward progress.
• Fix the root cause, not just the visible symptom.

Common Rationalizations

See .claude/skills/context-engineering/SKILL.md for the shared table. Debugging-specific traps: "the test already fails, I don't need a regression test" (if the failure can recur, guard it explicitly — an ad-hoc repro doesn't become a permanent test by accident), and "this quick change should fix it" (state the hypothesis first so the fix can be judged against it, not just against "the error is gone").