with one click
debug
// Active bug investigation — reproduce, diagnose, root-cause analysis. Produces debug report for /unipi:fix.
// Active bug investigation — reproduce, diagnose, root-cause analysis. Produces debug report for /unipi:fix.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | debug |
| description | Active bug investigation — reproduce, diagnose, root-cause analysis. Produces debug report for /unipi:fix. |
Active investigation to reproduce, diagnose, and root-cause bugs. Produces a structured debug report that /unipi:fix can consume.
This skill MAY: read codebase, run diagnostic commands, spawn subagents, write debug report to .unipi/docs/debug/.
This skill MAY NOT: edit code, fix issues, run tests that modify state, deploy.
Write-permission clarification: "Read-only" means source/project code is read-only for diagnosis. It does not prohibit creating or updating the debug report. The agent should use available file-writing tools to write exactly the report under .unipi/docs/debug/. If writing that report fails, report the write failure explicitly.
This is diagnosis only — not fixing.
/unipi:debug <string(greedy)>
string(greedy) — bug description, error message, or reproduction steps.unipi/docs/debug/@unipi/subagents extension is installed.unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md
Exit: Bug understood, scope defined.
Attempt to reproduce the issue:
Find reproduction path:
Run diagnostic commands:
grep for error messages in codefind related filesIf subagents available:
Exit: Reproduction steps documented (or confirmed unreproducible).
Deep dive into root cause:
Trace the failure:
Check common causes:
Analyze data flow:
Check dependencies:
Exit: Root cause identified (or hypotheses listed if uncertain).
Write debug report to .unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md using the available file-writing tool. Do not skip this because the investigation is otherwise read-only:
---
title: "{Bug Title} — Debug Report"
type: debug
date: YYYY-MM-DD
severity: {critical|high|medium|low}
status: {root-caused|needs-investigation|unreproducible}
---
# {Bug Title} — Debug Report
## Summary
{One-line description of the bug}
## Expected Behavior
{What should happen}
## Actual Behavior
{What actually happens}
## Reproduction Steps
1. {Step 1}
2. {Step 2}
3. {Step 3}
## Environment
- {Relevant context: OS, version, config}
## Root Cause Analysis
### Failure Chain
1. {Entry point / trigger}
2. {Intermediate step}
3. {Failure point}
### Root Cause
{Detailed explanation of why the bug occurs}
### Evidence
- File: `{file}:{line}` — {what's wrong}
- File: `{file}:{line}` — {related code}
## Affected Files
- `{file}` — {role in the bug}
- `{file}` — {role in the bug}
## Suggested Fix
{High-level approach to fixing — NOT implementation}
### Fix Strategy
1. {Step 1}
2. {Step 2}
### Risk Assessment
- {Risk 1}: {mitigation}
- {Risk 2}: {mitigation}
## Verification Plan
How to verify the fix works:
1. {Test case 1}
2. {Test case 2}
## Related Issues
- {Link to related bugs, PRs, or discussions}
## Notes
{Any additional context, gotchas, or observations}
Present summary to user:
"Debug report written to
.unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md"Root Cause: {brief summary} Suggested Fix: {brief summary}
Then suggest:
If root cause found:
/unipi:fix debug:YYYY-MM-DD-<topic>-debug
If needs more investigation:
"Root cause unclear. Need to investigate {area} further."
/unipi:gather-context {area}
If unreproducible:
"Cannot reproduce with current steps. Can you provide more details?"
| Aspect | /unipi:debug | /unipi:scan-issues |
|---|---|---|
| Purpose | Investigate specific bug | Find potential issues |
| Input | Bug report / error message | Scope / category |
| Output | Debug report with root cause | Issue list with priorities |
| Depth | Deep single-issue analysis | Broad codebase scan |
| Handoff | /unipi:fix | /unipi:quick-work or /unipi:brainstorm |
/unipi:fix/unipi:fix can autocomplete them/unipi:consultant for expert analysis