playbooks

home / skills / jmerta / codex-skills / bug-triage

bug-triage skill

/bug-triage

This skill helps reproduce, isolate, and fix bugs in a repository, then summarize root cause, fix, and verification steps for reliable delivery.

npx playbooks add skill jmerta/codex-skills --skill bug-triage

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.3 KB
---
name: bug-triage
description: Reproduce, isolate, and fix a bug (or failing build/test), then summarize root cause, fix, and verification steps. Use when the user reports a bug, regression, or failing build/test and wants a fix.
---

# 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`.

Overview

This skill reproduces, isolates, and fixes a reported bug or failing test, then delivers a concise summary of root cause, fix, and verification steps. It focuses on creating a reliable repro, implementing a minimal fix, and producing clear verification and risk notes for review and merge.

How this skill works

I first collect missing details (repro steps, environment, logs, frequency) and consult repo guidance. I reproduce the failure locally with the repo’s preferred tools, narrow the failure to a file or function, form and validate a root-cause hypothesis, implement the smallest safe fix, and run the project’s standard checks and manual verification steps.

When to use it

  • User reports a bug without a clear repro and wants a fix
  • A build or test is failing and you want a minimal, reviewed fix
  • You need a root-cause explanation for a regression
  • You want verification steps and risk notes for a PR
  • Triaging flaky tests or intermittent failures

Best practices

  • Ask for exact reproduction steps and full unedited logs when info is missing
  • Prefer the project’s documented commands (bun/npm/pnpm/yarn) and respect repo-specific guidance
  • Reproduce with the simplest, fastest scenario; reduce nondeterminism for flaky failures
  • Localize the failure before changing code; avoid drive-by refactors
  • Implement the minimal change that fixes the root cause and run lint/tests/build before proposing the PR

Example use cases

  • User reports a runtime error in production with a stack trace but no repro—produce local repro and fix
  • CI test started failing after a dependency bump—identify regression, bisect if needed, and patch
  • A flaky test fails intermittently—stabilize by removing nondeterminism or fixing timing assumptions
  • A UI regression report includes screenshots but no steps—recreate the user flow, find the faulty component, and submit a minimal fix

FAQ

What information do you need to start triage?

Exact steps to reproduce (starting state + inputs), expected vs actual behavior, full error text/logs, environment details (OS, Node/Bun, browser, commit hash), frequency, and last known good version.

Which package manager or commands will you use?

I use the repository’s documented commands. If bun.lock exists I prefer bun; if bun is unavailable I’ll ask whether to install bun or use the repo’s alternative (npm/pnpm/yarn).