Bug Triage Workflow

---
id: "b8d4f2e5-9c3a-4f7b-a02d-4e6c8b1f3d5a"
name: "Bug Triage Workflow"
type: workflow
category: coding
version: "1.0.0"
author: "markeddown"
license: MIT
min_context_tokens: 4096
target_frameworks:
  - markeddown
  - cursor
  - claude
  - generic
tags:
  - debugging
  - triage
  - bugfix
  - troubleshooting
---

# Bug Triage Workflow

A systematic debugging process that moves from symptom to root cause to verified fix.

## Step 1 — Reproduce the Issue

- Gather the exact reproduction steps from the report: environment, inputs, expected vs actual behavior.
- Attempt to reproduce locally using the same environment and inputs.
- Record the exact error message, stack trace, or observable misbehavior.

> **Branch — Cannot Reproduce:**
> - Verify you are on the correct branch, commit, and environment.
> - Check for environment-specific factors: OS, runtime version, env vars, feature flags.
> - Ask the reporter for a screen recording or session log.
> - If still not reproducible after exhausting environment differences, label the issue as "needs-info" and document what you tried. Do not guess at a fix.

## Step 2 — Isolate the Scope

- Identify the subsystem: which files, modules, or services are involved?
- Determine when it started: check recent commits with `git bisect` or manual log inspection.
- Narrow the blast radius: is this one code path or does it affect multiple features?

## Step 3 — Form Hypotheses

- Based on the reproduction and scope, list 2-4 plausible root causes ranked by likelihood.
- For each hypothesis, write down what evidence would confirm or eliminate it.
- Start with the most likely hypothesis.

## Step 4 — Test Each Hypothesis

- For each hypothesis in order:
  1. Add targeted logging, breakpoints, or assertions to gather evidence.
  2. Run the reproduction steps.
  3. Evaluate: does the evidence confirm or eliminate this hypothesis?
  4. If eliminated, move to the next hypothesis.

> **Branch — Root Cause Is Upstream:**
> - If the bug originates in a dependency, third-party API, or infrastructure layer you do not control:
>   1. Document the upstream root cause with evidence.
>   2. Check if a newer version of the dependency fixes it.
>   3. If no fix exists, implement a workaround and add a comment with a link to the upstream issue.
>   4. Open or reference an issue in the upstream project.

## Step 5 — Implement the Fix

- Write the minimal change that addresses the root cause.
- Do not fix unrelated issues in the same change — scope the fix tightly.
- Add or update tests that cover the exact failure scenario.
- Ensure the test fails without the fix and passes with it (red-green verification).

## Step 6 — Verify the Fix

- Run the original reproduction steps and confirm the issue is resolved.
- Run the full test suite to check for regressions.
- If the bug was environment-specific, verify in that environment (not just locally).
- Have a second person confirm the fix if the bug was customer-facing or data-affecting.

## Step 7 — Document What Was Learned

Write a short post-fix summary:

- **Symptom:** What the user observed.
- **Root cause:** What was actually broken and why.
- **Fix:** What was changed (with file/line references).
- **Prevention:** What could prevent this class of bug in the future (test, lint rule, type check, etc.).

## Constraints

- Never push a fix you cannot reproduce the original bug for — you cannot verify what you cannot see.
- Never combine a bugfix with unrelated refactoring in the same commit.
- Always leave the codebase with at least one new test that guards against regression.
- If you spent more than 30 minutes without progress, re-evaluate your hypotheses from scratch rather than continuing down the same path.