| name | pi-debug |
| description | Debug failures systematically by reproducing the issue, isolating the cause, applying a fix, and verifying the outcome. Use when the user reports a bug, crash, flaky behavior, or failing test. |
pi-debug
Use this skill for investigation-first debugging.
Debug Workflow
- Reproduce
- capture exact steps
- identify expected vs actual behavior
- create the smallest reliable reproduction possible
- Isolate
- narrow to a specific file, branch, request, or state transition
- inspect logs, stack traces, and recent changes
- Fix
- choose the smallest fix that addresses the root cause
- avoid papering over symptoms when possible
- Verify
- rerun reproduction steps
- add or update tests if appropriate
- check for nearby regressions
Common Bug Categories
- null / undefined errors
- async race conditions
- stale state
- boundary and indexing issues
- wrong assumptions about input shape
- environment/config mismatches
- retry and timeout bugs
Debugging Tactics
- read the failing code path first
- inspect stack traces carefully
- add temporary logging or assertions
- reduce the problem to one failing case
- compare working vs failing paths
- check recent diffs around the failure
Output Expectations
- reproduction steps
- likely root cause
- fix summary
- verification steps/results
Resources
See:
templates/debug-checklist.mdtemplates/issue-template.mdtemplates/common-fixes.mdtemplates/error-codes.md
