debuglisted
Install: claude install-skill viettdann/arclight-kit
# Debug
Find the cause before changing code, then fix it once, with a test that failed before the fix. A diff that makes the symptom disappear without a confirmed cause is a guess.
## 1. Pin the symptom
- Write it as one line: `Under X, it does Y; expected Z.` Take X from the report, stack trace, or logs. If Z is unclear, ask.
- Collect what exists: the full stack trace, the log lines, the request or input, versions, environment. Start from the first error in time, not the loudest; later errors are often its consequences.
- Production-only failure: work from the logs. Filter by correlation or trace id, read about two minutes around the first error, and list deploys, config changes, and flag flips in the hour before it.
## 2. Reproduce
- Get a command that fails now, trying in this order: an existing failing test; a new test at the lowest level that shows the bug (unit before integration, never e2e); a `curl` or script against the running app; a CLI call on a fixture input diffed against known-good output; a captured request, payload, or event replayed through the code path; a throwaway harness that calls the failing path with its dependencies stubbed; the same input run through the old and new version and diffed. When only a person can trigger it (a click, a device), copy `scripts/hitl-loop.sh`, edit its steps, and run it so the user's observations come back as `KEY=VALUE` lines.
- Tighten it before moving on: assert the reported symptom (the wrong value, the exact error