/skill:triage -- Bug Investigation and Root Cause Analysis
Purpose: Systematically investigate a bug from reproduction through root cause identification. Produces a structured triage report with classification, risk assessment, and a recommended path forward. This skill investigates -- it does NOT write fixes. Project-agnostic -- adapts to any codebase by reading CLAUDE.md.
When to Use
- A bug report comes in and you need to understand what is happening
- Something broke and you do not know why
- You need to assess severity and blast radius before deciding how to fix
- You want a structured handoff to /skill:hotfix or /skill:execute-prd
When NOT to Use
- You already know the root cause and just need to fix it -- use /skill:hotfix or /skill:execute-prd
- The issue is a feature request, not a bug
- The issue is purely cosmetic with no functional impact -- just fix it directly
Usage
/skill:triage "users see 500 error on login after password reset"
/skill:triage "budget totals don't match line items" --ado 12345
/skill:triage "task dependency graph has cycles" --linear BF-42
/skill:triage "photos not uploading on iOS" --quick
Arguments
<description> -- what is happening, as reported (required)
--ado <item-id> -- fetch details from Azure DevOps work item via az boards work-item show --id <item-id>
--linear <issue-id> -- fetch details from Linear via the Linear MCP tool (linear issue read --id <issue-id>)
--quick -- skip regression analysis (Step 5), produce a shorter report
Step 1: Project Discovery
Read CLAUDE.md from the repo root to learn:
- Project structure, package boundaries, and conventions
- Error handling patterns (AppError, error codes, etc.)
- Logging approach (where to find logs, structured fields)
- Test framework and how to run tests
- Database/ORM layer (Drizzle, Prisma, etc.)
Step 2: Fetch Work Item (If Provided)
If --ado <item-id> or --linear <issue-id> was provided, use /skill:work-item to retrieve the full details. Extract:
- Title and description
- Reproduction steps (if documented)
- Acceptance criteria
- Related items or links
Step 3: Reproduce the Bug
Attempt to reproduce or confirm the bug through code analysis:
Pre-triage & context pruning (jev-gate): When the jev-gate MCP server is available (see _internal/jev-gate), pass the symptom description and initial candidate file paths (from Grep/Glob) to triage_coding_task(task_prompt, candidate_files) before reading large files into the cloud context window. Halt and ask for clarification if insufficient_context scores highest; read keep_full files completely, extract exported signatures (ast-grep) for keep_signatures_only files, and skip drop files. If looking up external SDK/hardware/framework error behavior, call smart_search(query, force_backend="auto") before running any raw web search.
Search for the symptom. Find the code path that produces the reported behavior:
- Error messages: search for the exact error text in the codebase
- HTTP status codes: trace the endpoint handler
- UI behavior: find the component and its data flow
- Data issues: trace the query/mutation path
Trace the execution path. Follow the code from entry point to failure:
- Identify the function/method where the bug manifests
- Walk backward through the call chain
- Note any branching logic, error handlers, or early returns
Identify inputs that trigger the bug. Determine:
- What specific input or state triggers the failure
- Is it deterministic or intermittent?
- Does it depend on timing, data state, or environment?
Step 4: Identify Root Cause
Classify the root cause into one of these categories:
| Category |
Description |
Examples |
| Logic Error |
Code does the wrong thing |
Off-by-one, wrong operator, missing negation, incorrect formula |
| Type Error |
Runtime type mismatch despite TypeScript |
Unsafe cast, as any, missing null check, incorrect Zod schema |
| Integration |
Contract mismatch between components |
API returns different shape than client expects, wrong enum value |
| Race Condition |
Timing-dependent failure |
Concurrent writes, stale cache, async ordering assumption |
| Config/Env |
Environment or configuration issue |
Missing env var, wrong URL, feature flag state |
| Data |
Unexpected data state |
Null in non-nullable column, orphaned reference, corrupted state |
For the root cause, identify:
- The exact location: file, function, line range
- The mechanism: what specifically goes wrong and why
- The trigger: what conditions cause this path to execute
Step 5: Regression Analysis (Skip with --quick)
Determine when this bug was introduced:
# Find recent changes to the affected files
git log --oneline -20 -- <affected-files>
If a specific commit is suspect:
git show <sha> -- <file>
Answer:
- Was this always broken, or did a recent change introduce it?
- If recent: which commit, who authored it, what was the intent?
- Are there related changes in the same PR that might also be affected?
Step 6: Risk Assessment
Assess four dimensions:
Blast Radius
- Isolated: affects one feature or edge case
- Moderate: affects a common workflow or multiple features
- Wide: affects all users or a core system function
Fix Complexity
- Simple: one-line fix or small localized change
- Moderate: changes to 2-5 files, straightforward logic
- Complex: cross-cutting change, multiple packages, requires design decisions
Regression Risk
- Low: fix is isolated, existing tests cover surrounding code
- Medium: fix touches shared code, test coverage is partial
- High: fix touches core logic, minimal test coverage, or has cascading effects
Test Coverage
- Good: affected code has tests, but they miss this case
- Partial: some tests exist but do not cover the affected path
- None: no tests for the affected code path
Step 7: Recommend Next Step
Based on the assessment, recommend one of:
| Recommendation |
When |
| /skill:hotfix |
Blast radius is Wide or Moderate AND fix complexity is Simple or Moderate |
| /skill:execute-prd |
Fix complexity is Complex OR regression risk is High |
| Direct fix |
Blast radius is Isolated AND fix complexity is Simple AND test coverage is Good |
| Needs more investigation |
Root cause is still unclear or there may be multiple contributing factors |
Step 8: Triage Report
Present the structured report:
Triage Report: <short title>
Reported Issue
<description as provided>
Root Cause
Category: <Logic Error | Type Error | Integration | Race Condition | Config/Env | Data>
Location: <file>:<function> (lines <N>-<M>)
Mechanism: <what goes wrong>
Trigger: <what conditions cause it>
Regression
Introduced: <commit sha> <date> | "pre-existing" | "unknown"
Related: <any related changes or PRs>
Risk Assessment
Blast Radius: <Isolated | Moderate | Wide>
Fix Complexity: <Simple | Moderate | Complex>
Regression Risk: <Low | Medium | High>
Test Coverage: <Good | Partial | None>
Recommendation: <next step>
Rationale: <one sentence>
Tracking: <ADO/Linear reference if provided>
Key Rules
- Investigate first, fix later. This skill does NOT write fixes. It produces a diagnosis.
- Be specific. Cite exact files, functions, and line numbers. Vague findings are useless.
- One root cause. If there are multiple contributing factors, identify the primary one and note the others.
- Do not guess. If you cannot determine the root cause with confidence, say so. "Needs more investigation" is a valid recommendation.
- Trace, do not assume. Actually follow the code path. Do not guess based on file names or function signatures alone.
- Respect scope. Do not start fixing the bug. Do not refactor. Do not add tests. Investigate and report.
1---2name: triage-23description: Investigate a bug from reproduction through root cause analysis and produce4 a structured triage report (classification, risk, recommended next step) — the deliverable5 is the report, not a fix. Preferred over superpowers:systematic-debugging when the6 goal is a handoff document for /hotfix, /execute-prd, or a human decision rather7 than an in-session fix.8whenToUse: Investigate a bug from reproduction through root cause analysis and produce9 a structured triage report (classification, risk, recommended next step) — the deliverable10 is the report, not a fix. Preferred over superpowers:systematic-debugging when the11 goal is a handoff document for /hotfix, /execute-prd, or a human decision rather12 than an in-session fix.13type: flow14disableModelInvocation: false15metadata:16 source: https://skillmd.com/skills/garyld1962/triage-217---181920# /skill:triage -- Bug Investigation and Root Cause Analysis2122**Purpose:** Systematically investigate a bug from reproduction through root cause identification. Produces a structured triage report with classification, risk assessment, and a recommended path forward. This skill investigates -- it does NOT write fixes. Project-agnostic -- adapts to any codebase by reading `CLAUDE.md`.2324## When to Use2526- A bug report comes in and you need to understand what is happening27- Something broke and you do not know why28- You need to assess severity and blast radius before deciding how to fix29- You want a structured handoff to /skill:hotfix or /skill:execute-prd3031## When NOT to Use3233- You already know the root cause and just need to fix it -- use /skill:hotfix or /skill:execute-prd34- The issue is a feature request, not a bug35- The issue is purely cosmetic with no functional impact -- just fix it directly3637## Usage3839```40/skill:triage "users see 500 error on login after password reset"41/skill:triage "budget totals don't match line items" --ado 1234542/skill:triage "task dependency graph has cycles" --linear BF-4243/skill:triage "photos not uploading on iOS" --quick44```4546## Arguments4748- `<description>` -- what is happening, as reported (required)49- `--ado <item-id>` -- fetch details from Azure DevOps work item via `az boards work-item show --id <item-id>`50- `--linear <issue-id>` -- fetch details from Linear via the Linear MCP tool (`linear issue read --id <issue-id>`)51- `--quick` -- skip regression analysis (Step 5), produce a shorter report5253## Step 1: Project Discovery5455Read `CLAUDE.md` from the repo root to learn:56- Project structure, package boundaries, and conventions57- Error handling patterns (AppError, error codes, etc.)58- Logging approach (where to find logs, structured fields)59- Test framework and how to run tests60- Database/ORM layer (Drizzle, Prisma, etc.)6162## Step 2: Fetch Work Item (If Provided)6364If `--ado <item-id>` or `--linear <issue-id>` was provided, use /skill:work-item to retrieve the full details. Extract:65- Title and description66- Reproduction steps (if documented)67- Acceptance criteria68- Related items or links6970## Step 3: Reproduce the Bug7172Attempt to reproduce or confirm the bug through code analysis:73740. **Pre-triage & context pruning (`jev-gate`):** When the `jev-gate` MCP server is available (see `_internal/jev-gate`), pass the symptom description and initial candidate file paths (from Grep/Glob) to `triage_coding_task(task_prompt, candidate_files)` before reading large files into the cloud context window. Halt and ask for clarification if `insufficient_context` scores highest; read `keep_full` files completely, extract exported signatures (`ast-grep`) for `keep_signatures_only` files, and skip `drop` files. If looking up external SDK/hardware/framework error behavior, call `smart_search(query, force_backend="auto")` before running any raw web search.75761. **Search for the symptom.** Find the code path that produces the reported behavior:77 - Error messages: search for the exact error text in the codebase78 - HTTP status codes: trace the endpoint handler79 - UI behavior: find the component and its data flow80 - Data issues: trace the query/mutation path81822. **Trace the execution path.** Follow the code from entry point to failure:83 - Identify the function/method where the bug manifests84 - Walk backward through the call chain85 - Note any branching logic, error handlers, or early returns86873. **Identify inputs that trigger the bug.** Determine:88 - What specific input or state triggers the failure89 - Is it deterministic or intermittent?90 - Does it depend on timing, data state, or environment?9192## Step 4: Identify Root Cause9394Classify the root cause into one of these categories:9596| Category | Description | Examples |97|----------|-------------|---------|98| **Logic Error** | Code does the wrong thing | Off-by-one, wrong operator, missing negation, incorrect formula |99| **Type Error** | Runtime type mismatch despite TypeScript | Unsafe cast, `as any`, missing null check, incorrect Zod schema |100| **Integration** | Contract mismatch between components | API returns different shape than client expects, wrong enum value |101| **Race Condition** | Timing-dependent failure | Concurrent writes, stale cache, async ordering assumption |102| **Config/Env** | Environment or configuration issue | Missing env var, wrong URL, feature flag state |103| **Data** | Unexpected data state | Null in non-nullable column, orphaned reference, corrupted state |104105For the root cause, identify:106- **The exact location:** file, function, line range107- **The mechanism:** what specifically goes wrong and why108- **The trigger:** what conditions cause this path to execute109110## Step 5: Regression Analysis (Skip with `--quick`)111112Determine when this bug was introduced:113114```bash115# Find recent changes to the affected files116git log --oneline -20 -- <affected-files>117```118119If a specific commit is suspect:120```bash121git show <sha> -- <file>122```123124Answer:125- Was this always broken, or did a recent change introduce it?126- If recent: which commit, who authored it, what was the intent?127- Are there related changes in the same PR that might also be affected?128129## Step 6: Risk Assessment130131Assess four dimensions:132133### Blast Radius134- **Isolated:** affects one feature or edge case135- **Moderate:** affects a common workflow or multiple features136- **Wide:** affects all users or a core system function137138### Fix Complexity139- **Simple:** one-line fix or small localized change140- **Moderate:** changes to 2-5 files, straightforward logic141- **Complex:** cross-cutting change, multiple packages, requires design decisions142143### Regression Risk144- **Low:** fix is isolated, existing tests cover surrounding code145- **Medium:** fix touches shared code, test coverage is partial146- **High:** fix touches core logic, minimal test coverage, or has cascading effects147148### Test Coverage149- **Good:** affected code has tests, but they miss this case150- **Partial:** some tests exist but do not cover the affected path151- **None:** no tests for the affected code path152153## Step 7: Recommend Next Step154155Based on the assessment, recommend one of:156157| Recommendation | When |158|----------------|------|159| **/skill:hotfix** | Blast radius is Wide or Moderate AND fix complexity is Simple or Moderate |160| **/skill:execute-prd** | Fix complexity is Complex OR regression risk is High |161| **Direct fix** | Blast radius is Isolated AND fix complexity is Simple AND test coverage is Good |162| **Needs more investigation** | Root cause is still unclear or there may be multiple contributing factors |163164## Step 8: Triage Report165166Present the structured report:167168```169Triage Report: <short title>170171Reported Issue172 <description as provided>173174Root Cause175 Category: <Logic Error | Type Error | Integration | Race Condition | Config/Env | Data>176 Location: <file>:<function> (lines <N>-<M>)177 Mechanism: <what goes wrong>178 Trigger: <what conditions cause it>179180Regression181 Introduced: <commit sha> <date> | "pre-existing" | "unknown"182 Related: <any related changes or PRs>183184Risk Assessment185 Blast Radius: <Isolated | Moderate | Wide>186 Fix Complexity: <Simple | Moderate | Complex>187 Regression Risk: <Low | Medium | High>188 Test Coverage: <Good | Partial | None>189190Recommendation: <next step>191 Rationale: <one sentence>192193Tracking: <ADO/Linear reference if provided>194```195196## Key Rules1971981. **Investigate first, fix later.** This skill does NOT write fixes. It produces a diagnosis.1992. **Be specific.** Cite exact files, functions, and line numbers. Vague findings are useless.2003. **One root cause.** If there are multiple contributing factors, identify the primary one and note the others.2014. **Do not guess.** If you cannot determine the root cause with confidence, say so. "Needs more investigation" is a valid recommendation.2025. **Trace, do not assume.** Actually follow the code path. Do not guess based on file names or function signatures alone.2036. **Respect scope.** Do not start fixing the bug. Do not refactor. Do not add tests. Investigate and report.