---
name: debugging
description: "Systematic Claude Code debugging workflow adapted for LazyClaude: reproduce, localize, explain root cause, patch minimally, and verify the real failing surface."
---

# Debugging

Use this skill when behavior is broken, surprising, flaky, or contradicted by
evidence. Do not patch from vibes. First make the failure reproducible.

## Debugging Loop

1. Reproduce the failure with the smallest command or scenario.
2. Capture exact output, exit code, log, or transcript.
3. State expected vs actual behavior.
4. Localize the failing boundary.
5. Patch minimally.
6. Re-run the original reproduction.
7. Add or update a regression test.
8. Run one real-surface QA scenario.

## Reproduction Standards

A good reproduction is:

- runnable from the project root
- deterministic or has a bounded flake note
- small enough for the next agent to rerun
- tied to one expected observable

For LazyClaude examples:

- `printf ... | node plugins/lazyclaude/bin/lazyclaude-hook.js user-prompt-submit`
- `npm exec --yes --package ./ -- lazyclaude-ai --dry-run install`
- `CLAUDE_CONFIG_DIR=$(mktemp -d) node bin/lazyclaude-ai.js install`
- `node --test test/hooks.test.mjs --test-name-pattern ultrawork`

## Root Cause Discipline

Explain the mechanism, not just the symptom. "The test failed" is not a root
cause. "The command markdown mentions `$ARGUMENTS`, which Claude renders empty
and tests reject as a broken placeholder" is a root cause.

## Common LazyClaude Failure Classes

- npm same-name source checkout causes `npx lazyclaude-ai` resolution confusion.
- `npm publish` requires OTP and fails with `EOTP`.
- CLI smoke uses unsupported `--version` and receives usage.
- Claude Code exposes `/goal` as a slash command but not model-facing tools.
- Plugin manifest version differs from `package.json`.
- Hook JSON parsing fails with stack traces instead of controlled errors.
- Package `files` omit a new skill or command.

## Patch Rules

- Patch the failing boundary, not an unrelated symptom.
- Keep compatibility aliases unless a breaking change is intentional.
- Add tests before production behavior changes.
- Do not broaden catch blocks without asserting the new error path.
- Do not call network or publish in tests.

## Evidence

Record:

- failing command and output
- changed file
- regression test
- passing command and output
- manual QA artifact and cleanup
