Root cause investigation and solution design for issues, bugs, or feature requests.
Investigates issues and feature requests to find root causes and provide solutions.
/plugin marketplace add unclecode/claude-code-tools/plugin install unclecode-cc-toolkit@unclecode-toolsRoot cause investigation and solution design for issues, bugs, or feature requests.
$ARGUMENTS
Description of the issue or feature. Can include error messages, URLs, or attach screenshots.
Deep investigation to find ROOT CAUSES, not just symptoms. Uses triage-agent for systematic analysis.
Philosophy: Don't just treat the rash, find the root cause (diet, stress, etc.) and fix both.
From user query, gather:
If critical info missing, ask clarifying questions:
IMPORTANT: Before launching agent, gather context from PP files:
Read these files:
.context/project/INDEX.md - Identify active subproject.context/project/{active}/CODEBASE.md - Understand file structure.context/project/{active}/STATUS.md - Current state, known issues.context/project/{active}/CHANGELOG.md (last 5-10 entries) - Recent changes.context/project/{active}/LESSONS.md - Past solutions.context/project/PRINCIPLES.md - Project principlesThis context is passed to the agent so it doesn't re-explore everything.
Spawn the triage-agent with:
Use Task tool with subagent_type: "triage-agent"
Prompt: Investigate this issue using PP context:
Issue: {user's issue description}
PP Context:
- Active subproject: {from INDEX.md}
- Codebase structure: {from CODEBASE.md}
- Current status: {from STATUS.md}
- Recent changes: {from CHANGELOG.md}
- Past lessons: {from LESSONS.md}
- Principles: {from PRINCIPLES.md}
Find ROOT CAUSE and provide solution or debugging plan.
The triage-agent will:
Agent returns report in this format:
## Triage Report: {Issue Title}
**Date**: {YYYY-MM-DD HH:MM}
**Subproject**: {subproject name}
**Severity**: {Critical / High / Medium / Low}
---
### Issue Summary
{Brief description of reported issue}
---
### Root Cause Analysis
**Symptom**: {What appears to be happening}
**Investigation Path**:
1. {Step 1 of investigation}
2. {Step 2 of investigation}
3. {Step 3 of investigation}
**Root Cause**: {The actual underlying cause}
**Why This Matters**: {Explanation of causation, not just correlation}
---
### Solution
{IF ROOT CAUSE IS CLEAR}:
**Recommended Fix**:
1. {Step 1}
2. {Step 2}
3. {Step 3}
**Files to Modify**:
- `path/to/file.ext` - {what to change}
- `another/file.js` - {what to change}
**Implementation Notes**:
- {Important consideration 1}
- {Important consideration 2}
{IF ROOT CAUSE IS UNCLEAR}:
**Debugging Strategy**:
1. **Add logging**:
- In `file.ext` line X: log variable Y
- In `file2.js` line Z: log state before/after
2. **Test hypothesis**:
- {Hypothesis 1}: Test by {method}
- {Hypothesis 2}: Test by {method}
3. **Narrow down**:
- {Approach to isolate the issue}
**Next Steps**:
1. {Action item 1}
2. {Action item 2}
3. {Re-run /pp-triage after gathering data}
---
### Related Context
**Recent Changes That May Be Related**:
- {CHANGELOG entry if relevant}
**Past Similar Issues**:
- {LESSONS.md entry if relevant}
**Affected Components**:
- {Component 1}
- {Component 2}
---
### Recommended Documentation Updates
**Add to LESSONS.md**:
Problem: {Brief problem} Root Cause: {Cause} Solution: {Solution} Tag: [BUG] or [FEATURE] or [CONFIG]
**Update STATUS.md**:
- If blocking: Add to "Blocked" section
- If in progress: Add to "Current Focus"
---
### Confidence Level
**Root Cause Certainty**: {High / Medium / Low}
**Solution Confidence**: {High / Medium / Low}
{If low confidence, explain why and what additional info is needed}
After presenting report, offer:
## Next Steps
Would you like me to:
1. Implement the recommended fix?
2. Add debugging logs as suggested?
3. Update LESSONS.md with this finding?
4. Create a TODO task for this fix?
5. Something else?
# Bug report
/pp-triage Getting 500 errors on /api/users endpoint when user has no profile
# Feature request
/pp-triage Need to add email notifications when order status changes
# Performance issue
/pp-triage Dashboard loads slowly with more than 100 items
# With error message
/pp-triage TypeError: Cannot read property 'name' of undefined in UserProfile component
# With screenshot
/pp-triage [attach screenshot] Login button not working on mobile
The triage-agent is trained to: