/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 /hotfix or /execute-prd
When NOT to Use
- You already know the root cause and just need to fix it -- use /hotfix or /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
/triage "users see 500 error on login after password reset"
/triage "budget totals don't match line items" --ado 12345
/triage "task dependency graph has cycles" --linear BF-42
/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 /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 |
| /hotfix |
Blast radius is Wide or Moderate AND fix complexity is Simple or Moderate |
| /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: triage3description: "Investigate a bug from reproduction through root cause analysis and produce a structured triage report (classification, risk, recommended next step) — the deliverable is the report, not a fix. Preferred over superpowers:systematic-debugging when the goal is a handoff document for /hotfix, /execute-prd, or a human decision rather than an in-session fix."4model: opus5metadata:6 source: https://skillmd.com/skills/garyld1962/triage7---89# /triage -- Bug Investigation and Root Cause Analysis1011**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`.1213## When to Use1415- A bug report comes in and you need to understand what is happening16- Something broke and you do not know why17- You need to assess severity and blast radius before deciding how to fix18- You want a structured handoff to /hotfix or /execute-prd1920## When NOT to Use2122- You already know the root cause and just need to fix it -- use /hotfix or /execute-prd23- The issue is a feature request, not a bug24- The issue is purely cosmetic with no functional impact -- just fix it directly2526## Usage2728```29/triage "users see 500 error on login after password reset"30/triage "budget totals don't match line items" --ado 1234531/triage "task dependency graph has cycles" --linear BF-4232/triage "photos not uploading on iOS" --quick33```3435## Arguments3637- `<description>` -- what is happening, as reported (required)38- `--ado <item-id>` -- fetch details from Azure DevOps work item via `az boards work-item show --id <item-id>`39- `--linear <issue-id>` -- fetch details from Linear via the Linear MCP tool (`linear issue read --id <issue-id>`)40- `--quick` -- skip regression analysis (Step 5), produce a shorter report4142## Step 1: Project Discovery4344Read `CLAUDE.md` from the repo root to learn:45- Project structure, package boundaries, and conventions46- Error handling patterns (AppError, error codes, etc.)47- Logging approach (where to find logs, structured fields)48- Test framework and how to run tests49- Database/ORM layer (Drizzle, Prisma, etc.)5051## Step 2: Fetch Work Item (If Provided)5253If `--ado <item-id>` or `--linear <issue-id>` was provided, use /work-item to retrieve the full details. Extract:54- Title and description55- Reproduction steps (if documented)56- Acceptance criteria57- Related items or links5859## Step 3: Reproduce the Bug6061Attempt to reproduce or confirm the bug through code analysis:62630. **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.64651. **Search for the symptom.** Find the code path that produces the reported behavior:66 - Error messages: search for the exact error text in the codebase67 - HTTP status codes: trace the endpoint handler68 - UI behavior: find the component and its data flow69 - Data issues: trace the query/mutation path70712. **Trace the execution path.** Follow the code from entry point to failure:72 - Identify the function/method where the bug manifests73 - Walk backward through the call chain74 - Note any branching logic, error handlers, or early returns75763. **Identify inputs that trigger the bug.** Determine:77 - What specific input or state triggers the failure78 - Is it deterministic or intermittent?79 - Does it depend on timing, data state, or environment?8081## Step 4: Identify Root Cause8283Classify the root cause into one of these categories:8485| Category | Description | Examples |86|----------|-------------|---------|87| **Logic Error** | Code does the wrong thing | Off-by-one, wrong operator, missing negation, incorrect formula |88| **Type Error** | Runtime type mismatch despite TypeScript | Unsafe cast, `as any`, missing null check, incorrect Zod schema |89| **Integration** | Contract mismatch between components | API returns different shape than client expects, wrong enum value |90| **Race Condition** | Timing-dependent failure | Concurrent writes, stale cache, async ordering assumption |91| **Config/Env** | Environment or configuration issue | Missing env var, wrong URL, feature flag state |92| **Data** | Unexpected data state | Null in non-nullable column, orphaned reference, corrupted state |9394For the root cause, identify:95- **The exact location:** file, function, line range96- **The mechanism:** what specifically goes wrong and why97- **The trigger:** what conditions cause this path to execute9899## Step 5: Regression Analysis (Skip with `--quick`)100101Determine when this bug was introduced:102103```bash104# Find recent changes to the affected files105git log --oneline -20 -- <affected-files>106```107108If a specific commit is suspect:109```bash110git show <sha> -- <file>111```112113Answer:114- Was this always broken, or did a recent change introduce it?115- If recent: which commit, who authored it, what was the intent?116- Are there related changes in the same PR that might also be affected?117118## Step 6: Risk Assessment119120Assess four dimensions:121122### Blast Radius123- **Isolated:** affects one feature or edge case124- **Moderate:** affects a common workflow or multiple features125- **Wide:** affects all users or a core system function126127### Fix Complexity128- **Simple:** one-line fix or small localized change129- **Moderate:** changes to 2-5 files, straightforward logic130- **Complex:** cross-cutting change, multiple packages, requires design decisions131132### Regression Risk133- **Low:** fix is isolated, existing tests cover surrounding code134- **Medium:** fix touches shared code, test coverage is partial135- **High:** fix touches core logic, minimal test coverage, or has cascading effects136137### Test Coverage138- **Good:** affected code has tests, but they miss this case139- **Partial:** some tests exist but do not cover the affected path140- **None:** no tests for the affected code path141142## Step 7: Recommend Next Step143144Based on the assessment, recommend one of:145146| Recommendation | When |147|----------------|------|148| **/hotfix** | Blast radius is Wide or Moderate AND fix complexity is Simple or Moderate |149| **/execute-prd** | Fix complexity is Complex OR regression risk is High |150| **Direct fix** | Blast radius is Isolated AND fix complexity is Simple AND test coverage is Good |151| **Needs more investigation** | Root cause is still unclear or there may be multiple contributing factors |152153## Step 8: Triage Report154155Present the structured report:156157```158Triage Report: <short title>159160Reported Issue161 <description as provided>162163Root Cause164 Category: <Logic Error | Type Error | Integration | Race Condition | Config/Env | Data>165 Location: <file>:<function> (lines <N>-<M>)166 Mechanism: <what goes wrong>167 Trigger: <what conditions cause it>168169Regression170 Introduced: <commit sha> <date> | "pre-existing" | "unknown"171 Related: <any related changes or PRs>172173Risk Assessment174 Blast Radius: <Isolated | Moderate | Wide>175 Fix Complexity: <Simple | Moderate | Complex>176 Regression Risk: <Low | Medium | High>177 Test Coverage: <Good | Partial | None>178179Recommendation: <next step>180 Rationale: <one sentence>181182Tracking: <ADO/Linear reference if provided>183```184185## Key Rules1861871. **Investigate first, fix later.** This skill does NOT write fixes. It produces a diagnosis.1882. **Be specific.** Cite exact files, functions, and line numbers. Vague findings are useless.1893. **One root cause.** If there are multiple contributing factors, identify the primary one and note the others.1904. **Do not guess.** If you cannot determine the root cause with confidence, say so. "Needs more investigation" is a valid recommendation.1915. **Trace, do not assume.** Actually follow the code path. Do not guess based on file names or function signatures alone.1926. **Respect scope.** Do not start fixing the bug. Do not refactor. Do not add tests. Investigate and report.