pm-troubleshoot
Skill2 starsChanged 8 months agoMITView on GitHub
Diagnose the root cause of a bug, error, crash, or unexpected behavior. Traces through code, logs, services, database state, and git history to find why something is broken. Researches error messages online for known issues. Produces a diagnosis with evidence and suggested fix. Use when the user reports a problem, error message, stack trace, test failure, or says things like "why is this happening", "this is broken", "I'm getting an error", "something's wrong with...", "debug this", or "figure out why...".
In this repository15 other files it gives its agents.
- pm-auditSkill
- pm-brainstormSkill
- pm-cleanupSkill
- pm-codesmellsSkill
- pm-doneSkill
- pm-exploreSkill
- pm-housekeepingSkill
- pm-implementSkill
- pm-nextSkill
- pm-planSkill
- pm-refine-frSkill
- pm-scaffoldSkill
- pm-statusSkill
- pm-triageSkill
- pm-verifySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 16 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Before diving into code, check if the issue is environmental.
- Distinctive: line 48
If services are down or unhealthy, that may be the root cause.
- Distinctive: line 60
If the symptom involves data issues, missing records, or FK violations:
- Distinctive: line 71
Check what changed recently — the cause is often in the last few commits:
- Very specific: line 78
If the symptom started after a specific change, git diff HEAD~1 or git log --oneline -5 -- {affected-file} narrows it down.
- Distinctive: line 88
If error message with file/line: Read that file directly, understand the context.
- Distinctive: line 95
Read each layer to find where the behavior diverges from expectation
- Distinctive: line 97
If test failure: Read the test, understand what it asserts, then trace into the code under test.
- Distinctive: line 101
Use Serena's tools for efficient code exploration:
- Distinctive: line 106
Look for common root cause patterns:
- Distinctive: line 117
If you've identified the suspect code but don't know when/why it was introduced:
- Very specific: line 136
Use WebSearch with the exact error message (in quotes) plus the technology stack
- Very specific: line 137
Use WebSearch with the library name + "correct usage" for pattern verification
- Very specific: line 138
Use WebFetch to pull relevant documentation or GitHub issues
- Very specific: line 206
Use the AskUserQuestion tool:
- Distinctive: line 219
If Investigate more: Ask what aspect needs more investigation and continue from Step 3.
- Distinctive: line 223
Always start with the symptom, not assumptions — let the evidence guide the investigation
- Distinctive: line 224
Check the live environment before diving into code — environmental issues are the most common and fastest to diagnose
- Distinctive: line 225
Follow the evidence chain: symptom → immediate cause → root cause.
- Distinctive: line 228
Keep the investigation proportional — a clear null pointer error doesn't need 10 minutes of git archaeology
- Distinctive: line 229
When multiple root causes are possible, present all of them ranked by likelihood rather than guessing at one
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Troubleshoot: Root Cause Analysis
Given a symptom — an error message, unexpected behavior, crash, test failure, or vague "something's wrong" — systematically trace through the codebase, logs, services, and git history to find the root cause. The goal is a clear diagnosis the user can act on, not a guess.
Step 1: Capture the Symptom
Parse $ARGUMENTS to understand what went wrong. Classify the symptom:
Error message / stack trace: Extract the key error, file path, line number, and exception type. This is the most actionable starting point.
Unexpected behavior: "X happens when it should do Y." Understand both the expected and actual behavior.
Test failure: Extract the test name, assertion that failed, expected vs actual values.
Vague report: "Something's wrong with the dashboard" or "the API is slow." Need to narrow down before investigating — ask one focused question using AskUserQuestion:
- Question: "Can you describe the specific symptom? For example: an error message, a page that doesn't load, a request that returns wrong data, or a test that fails?"
- Header: "What's happening?"
- Options:
[{label: "Error/crash", description: "I see an error message or stack trace"}, {label: "Wrong behavior", description: "Something works but does the wrong thing"}, {label: "Performance", description: "Something is slow or timing out"}, {label: "Test failure", description: "A test is failing"}]
Record the symptom clearly — this is the hypothesis to prove or disprove.
Step 2: Check the Live Environment
Before diving into code, check if the issue is environmental. These checks are fast and often reveal the problem immediately.
2a: Service Health
# Check if containers are running and healthy
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}" 2>/dev/nullIf services are down or unhealthy, that may be the root cause. Check container logs:
# Last 50 lines from each service
docker compose logs --tail=50 api 2>/dev/null
docker compose logs --tail=50 mcp 2>/dev/null
docker compose logs --tail=50 dashboard 2>/dev/null
docker compose logs --tail=50 postgres 2>/dev/null2b: Database State
If the symptom involves data issues, missing records, or FK violations:
# Check database connectivity and basic state
docker compose exec -T postgres psql -U postgres -d pinkrooster -c "SELECT count(*) FROM projects;" 2>/dev/nullFor specific entity issues, query the relevant table. Use the connection string from the environment.
2c: Recent Changes
Check what changed recently — the cause is often in the last few commits:
git log --oneline -10
git diff HEAD~3 --statIf the symptom started after a specific change, git diff HEAD~1 or git log --oneline -5 -- {affected-file} narrows it down.
Skip environment checks when: The user provides a clear error with file/line reference, or the issue is obviously in static code (type errors, logic bugs). Go straight to Step 3.
Step 3: Trace Through Code
This is the core investigation. Start from the symptom and work backward to the root cause.
3a: Locate the Error Origin
If error message with file/line: Read that file directly, understand the context.
If stack trace: Trace from the top (where the error surfaced) down to the bottom (where it originated). Read the key frames.
If behavioral bug: Identify the code path that produces the wrong behavior:
- Find the relevant endpoint/page/component using Grep
- Trace the data flow: controller → service → database (API) or component → hook → API call (dashboard)
- Read each layer to find where the behavior diverges from expectation
If test failure: Read the test, understand what it asserts, then trace into the code under test.
3b: Analyze the Suspect Code
Use Serena's tools for efficient code exploration:
mcp__serena__get_symbols_overviewto understand file structure without reading everythingmcp__serena__find_symbolwithinclude_body=Trueto read specific functionsmcp__serena__find_referencing_symbolsto trace callers and dependencies
Look for common root cause patterns:
- Null/undefined access: Missing guard on optional data (check if API returns null vs empty array)
- State mismatch: Entity in wrong state for the operation being attempted
- Missing migration: Schema changed but migration not applied
- Race condition: Concurrent access without proper locking
- Configuration: Missing or wrong env var, connection string, API key
- Dependency version: Package conflict or breaking change after upgrade
- Off-by-one / boundary: Edge case in pagination, array indexing, date ranges
3c: Git Blame
If you've identified the suspect code but don't know when/why it was introduced:
git log --oneline -5 -- {suspect-file}
git blame -L {startLine},{endLine} {suspect-file}This reveals who changed the code and what the commit message says — often explains the intent behind the bug.
Step 4: Research Online
For error messages, library issues, or patterns you're unsure about — search online. This catches known issues, version-specific bugs, and correct usage patterns that aren't obvious from code alone.
When to research:
- The error message includes a library name or framework-specific code (e.g., "Npgsql.PostgresException", "ERR_CONNECTION_REFUSED", "CORS policy")
- The suspect code uses an API or pattern you want to verify is correct
- The issue might be a known bug in a dependency
How to research:
- Use
WebSearchwith the exact error message (in quotes) plus the technology stack - Use
WebSearchwith the library name + "correct usage" for pattern verification - Use
WebFetchto pull relevant documentation or GitHub issues
When to skip:
- The root cause is clearly a logic error in project code (typo, wrong variable, missing guard)
- The issue is a data problem (wrong value in DB, missing record)
Step 5: Formulate Diagnosis
Synthesize findings into a clear diagnosis. The quality of the diagnosis determines whether the fix will be correct on the first attempt.
Build the Evidence Chain
Trace from symptom → immediate cause → root cause:
Symptom: Dashboard shows blank white screen on WP detail page
↓
Immediate cause: `phases.map()` throws because `phases` is undefined
↓
Root cause: API returns `null` for phases when WP has none;
TypeScript type says `Phase[]` (non-optional) but API doesn't guarantee it
↓
Fix: Add null coalescing in the component OR fix the API to return `[]` instead of `null`Assess Confidence
Rate your diagnosis:
- High confidence: Reproduced the issue, found the exact line, understand why it happens
- Medium confidence: Found the likely cause but couldn't fully reproduce, or there are multiple possible causes
- Low confidence: Narrowed the area but root cause is still uncertain — more investigation needed
Step 6: Report
## Diagnosis: {one-line summary}
### Symptom
{What the user reported or observed}
### Root Cause
{Clear explanation of WHY the issue occurs — not just WHERE}
### Evidence
1. {File:line — what was found and what it means}
2. {Log entry / DB state / git change — supporting evidence}
3. {Online reference — if research confirmed the diagnosis}
### Evidence Chain
{symptom} → {immediate cause} → {root cause}
### Confidence: {High | Medium | Low}
{Brief justification for the confidence level}
### Suggested Fix
{Specific code change or configuration fix}
- File: {path}
- Change: {what to do}
### Prevention
{How to prevent this class of issue in the future — optional, only if there's a clear pattern}
### Research (if performed)
- {key finding from online research}Step 7: Offer Next Steps
Use the AskUserQuestion tool:
- Question: "How would you like to proceed with this diagnosis?"
- Header: "Next step"
- Options:
[{label: "Create issue", description: "Track this as a bug via /pm-plan with the root cause pre-filled"}, {label: "Fix now", description: "Implement the fix directly"}, {label: "Investigate more", description: "The diagnosis isn't conclusive — dig deeper"}, {label: "Done", description: "I have what I need"}]
If Create issue: Invoke /pm-plan with a pre-formatted description:
Bug: {symptom summary}. Root cause: {root cause}. Fix: {suggested fix}.
Affected: {file paths}. Severity: {inferred from impact}.If Fix now: Invoke /pm-implement if a task exists, or implement the fix directly following the suggested change.
If Investigate more: Ask what aspect needs more investigation and continue from Step 3.
Constraints
- Always start with the symptom, not assumptions — let the evidence guide the investigation
- Check the live environment before diving into code — environmental issues are the most common and fastest to diagnose
- Follow the evidence chain: symptom → immediate cause → root cause. Don't stop at the immediate cause (e.g., "phases is undefined" is not the root cause — WHY is it undefined is)
- Rate your confidence honestly — a "medium confidence" diagnosis that says so is more useful than a wrong "high confidence" one
- Research online when the issue involves libraries, frameworks, or patterns — don't rely on stale knowledge when docs are a search away
- Keep the investigation proportional — a clear null pointer error doesn't need 10 minutes of git archaeology
- When multiple root causes are possible, present all of them ranked by likelihood rather than guessing at one
- The diagnosis should be actionable — if the user can't act on it, dig deeper
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

