Bug triage

Bug triage

Goal

Turn an ambiguous bug report into:

• a reliable repro (or a clear “cannot reproduce yet” with next info to collect)
• a root-cause explanation
• a minimal, reviewed fix
• verification steps (commands + manual checks)

First checks

1. Read any repo-specific guidance (AGENTS.md, CONTRIBUTING.md, README).
2. Clarify impact: severity, who is affected, and whether it’s a regression.

If info is missing, ask for it

• Exact steps to reproduce (starting state + inputs).
• Expected vs actual behavior.
• Error text / stack trace / logs (full, unedited if possible).
• Environment: OS, runtime versions (Node/​Bun), browser, commit hash/​tag.
• Frequency: always / sometimes / only certain data.
• “Last known good” version or approximate date when it started.

Workflow (checklist)

1. Reproduce locally
   • Prefer the simplest, fastest repro.
   • If it’s flaky, try to reduce nondeterminism (seed, fixed time, retries).
2. Localize the failure
   • Narrow to a file/​function/​component/​config.
   • Use rg to find relevant code paths and error strings.
3. Identify root cause
   • Form a hypothesis, confirm with logs/​breakpoints, then refine.
   • If it’s a regression and git history exists, consider git bisect.
4. Implement the minimal fix
   • Fix the cause, not the symptom.
   • Avoid drive-by refactors and formatting churn.
5. Verify
   • Run the project’s standard checks (lint/​tests/​build).
   • Re-run the repro steps and confirm the fix.

Repo-aware command hints

Use what the repo actually uses:

• If bun.lock exists: prefer bun ... (e.g. bun lint, bun build, bun dev).
• Otherwise: use the project’s documented commands (npm, pnpm, yarn, etc.).
• If bun.lock exists but bun is not available, tell the user and ask whether to install bun or use the repo’s alternative package manager.

Deliverable (paste this in the chat / PR / issue)

Use this format:

• Summary: ...
• Repro: ...
• Root cause: ...
• Fix: ...
• Verification: ...
• Risk/​notes: ...

If you need a bug-report structure to ask the user for, use references/​bug-report-template.md.