Get the FREE Ultimate OpenClaw Setup Guide →

bug-triage

Scanned
npx machina-cli add skill jmerta/codex-skills/bug-triage --openclaw
Files (1)
SKILL.md
2.3 KB

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.

Source

git clone https://github.com/jmerta/codex-skills/blob/main/bug-triage/SKILL.mdView on GitHub

Overview

Bug triage turns ambiguous reports into a reliable repro, a root-cause explanation, a minimal fix, and clear verification steps. It starts by checking repo guidance and clarifying impact, then collects missing details before reproducing locally. This process speeds up fixes and improves confidence in changes.

How This Skill Works

It follows a repeatable workflow: reproduce locally with the simplest repro, localize the failure to a file or component, and identify the root cause. Then implement a minimal fix and verify with the project’s standard checks and re-run the repro. Use repo hints like rg for code paths and git bisect for regressions when applicable.

When to Use It

  • A user reports a bug, regression, or failing build/test and wants a fix.
  • The report is unclear or lacks exact steps to reproduce.
  • You need to localize the failure to a specific file, function, or config.
  • You suspect a regression and want to pinpoint its origin (potentially with git bisect).
  • You must provide verification steps and a minimal, reviewed fix before merging.

Quick Start

  1. Step 1: Read repo guidance and gather missing info from the reporter.
  2. Step 2: Reproduce locally with the simplest, fastest repro and narrow down where it fails.
  3. Step 3: Identify root cause, implement a minimal fix, and verify with project checks and the repro steps.

Best Practices

  • Read repo guidance (AGENTS.md, CONTRIBUTING.md, README) first.
  • Clarify impact: severity, affected users, regression status.
  • Ask for exact steps, expected vs actual behavior, logs, environment, and last known good version.
  • Reproduce with the simplest repro; reduce nondeterminism in flaky tests.
  • Fix the root cause, not the symptom; verify with lint/tests/build and re-run repro.

Example Use Cases

  • Bug in API endpoint causing 500 on search; reproduction confirms issue; root cause is input validation; minimal fix implemented.
  • Regression after dependency upgrade breaks authentication flow; triage identifies breaking change and patch applied.
  • Flaky CI test suite failure in build step; repro is intermittent; fix stabilizes test and adds seeding.
  • Memory leak in session init after user load; triage reproduces, identifies leak path, fix applied and verified.
  • Unhandled error in data import pipeline after schema change; root cause located, fix added, verification covers end-to-end run.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗