| name | systematic-debugging |
| description | Investigate Waitkit bugs, build failures, lint failures, test failures, package export issues, fetch interception regressions, Changesets problems, and npm publish failures by finding root cause before fixes. |
Waitkit Systematic Debugging
Use this skill before fixing bugs or validation failures.
Rule
Find root cause before editing code. A quick patch that only hides the symptom is
not a fix.
Phase 1: Evidence
- Read the full error, warning, stack trace, or user reproduction.
- Identify whether the issue is reproducible.
- Inspect recent diffs and directly related files.
- Compare against a working local pattern.
- State one root-cause hypothesis.
Phase 2: Boundary Trace
Choose the relevant trace:
Core behavior: setupWaitKit -> matcher -> rule application -> fetch/Response -> controller
Package output: package.json exports -> tsup config -> dist files -> consumer import
Release: changeset file -> version/changelog -> package metadata -> npm publish output
Build: first compiler error -> owning file -> imports/types -> recent diff
For failures that cross more than one boundary, read
${CLAUDE_SKILL_DIR}/references/root-cause-tracing.md before proposing a fix.
Phase 3: Minimal Fix
- Change one thing that addresses the hypothesis.
- Do not bundle cleanup or refactors.
- Prefer adding a focused regression test.
- If no test is suitable, document the smallest verification command.
Phase 4: Verification
Run the smallest meaningful check first, then the broader gate:
pnpm exec prettier --check .
pnpm lint
pnpm check-types
pnpm test
pnpm build
