---
name: debugging
description: Help a beginner reproduce a concrete error, compare at least two plausible causes, apply a narrow fix and rerun the original operation. Use when an Agent task or small script fails and the learner needs evidence rather than random retries.
---

# Reproduce, explain, fix, check

Main quest 2-3. Save the original error and a verified result.

## Start from an actual failure

Ask for the exact command, selected folder, observed error and expected behavior.
Read the relevant source and input before changing anything.
Reproduce only within the authorized project and with harmless local inputs.
Preserve the original error text and failing exit status.
If reproducing would send messages, spend money or modify live data, first choose a read-only or isolated reproduction.

## Compare hypotheses before editing

Write at least two plausible causes and one observation that could distinguish them.
For a missing file, compare an incorrect relative path with a missing input file.
For wrong values, compare parsing with incorrect source data.
Check the discriminating observation; do not label a guess as the root cause.
Prefer the smallest change that explains the actual failure.
Do not reset repositories, delete user files or reinstall everything to hide an error.

## Fix and verify

Save a narrow patch in the practice copy or the authorized existing file.
Rerun the exact failed operation with the same original input.
Then use a second different normal input to catch a hardcoded fix.
Check the expected error when required input is genuinely absent.
Save command, exit status, observed output and why the result resolves the failure.
Separate a successful local reproduction from production compatibility.

## Practice files

`inputs/missing-file/` contains an intentional path mistake and a harmless public JSON input.
Run its `run.mjs` inside that folder to observe the error.
Keep the original broken file as evidence; save the repair to a new practice output directory.
Read `references/hypothesis-log.md` for the short evidence record format.

## Self-tests and failure criteria

1. Reproduce the missing-file error, record two hypotheses, confirm which path exists and repair the reference. Result must preserve the JSON title and quantity.
2. Replace the input with the separate Unicode fixture, rerun the repaired code and verify the different values. Do not copy test one's output.
3. Run without any input file. It must fail visibly; do not create a guessed input to report success.
4. If the fix changes unrelated files or only suppresses the exception, the task fails.

## Continue

Return `/path/debugging/`. Next `/path/skill-chain/`: keep intermediate files and prove the next step consumes them.
Original free workflow; personal and commercial use allowed, no complete-package resale.