Bug triage
Establish scope
- Read repository instructions and inspect the current branch, status, and relevant diff.
- Determine whether the user asked only for diagnosis or also authorized a fix.
- Inspect available errors, logs, tests, and code before asking for missing details.
- Record expected behavior, actual behavior, environment, frequency, and last known good state when they affect the investigation.
Reproduce and isolate
- Use the smallest reliable reproduction. Preserve the original failure output.
- If the failure is intermittent, control time, randomness, concurrency, data, and retries one variable at a time.
- Trace the failing path end to end. Search every caller of the function or component before editing it.
- Form a falsifiable hypothesis and run the narrowest check that can confirm or reject it.
- Use history or
git bisect only when a regression boundary will materially shorten the search.
Separate these outcomes explicitly:
- confirmed product regression;
- pre-existing or baseline failure;
- environment, credentials, service, or dependency failure;
- insufficient evidence to reproduce.
Fix when authorized
- Add or adapt the smallest regression check that fails for the confirmed cause.
- Fix the shared root cause rather than guarding one visible caller.
- Avoid unrelated refactors, dependency upgrades, formatting churn, and broad exception handling.
- Re-run the reproduction, focused regression check, and the smallest relevant project checks.
Use the package manager, wrapper, and commands already selected by the repository. Infer them from repository instructions, manifests, lockfiles, and scripts; do not substitute another tool just because it is installed locally.
Report
Include:
- Observed: exact symptom and affected scope.
- Root cause: confirmed explanation, or the leading hypothesis clearly labeled.
- Change: files and behavior changed, or
diagnosis only.
- Verification: commands and results, including baseline failures.
- Remaining risk: untested paths, flaky behavior, or external blockers.
Use references/bug-report-template.md only when the user needs a reusable intake form.
1---2name: bug-triage3description: Use when the user reports a bug, regression, runtime error, failing build, or broken test and wants reproduction, diagnosis, root-cause analysis, or an authorized fix. Isolates the shared cause and verifies the smallest relevant change.4---56# Bug triage78## Establish scope9101. Read repository instructions and inspect the current branch, status, and relevant diff.112. Determine whether the user asked only for diagnosis or also authorized a fix.123. Inspect available errors, logs, tests, and code before asking for missing details.134. Record expected behavior, actual behavior, environment, frequency, and last known good state when they affect the investigation.1415## Reproduce and isolate16171. Use the smallest reliable reproduction. Preserve the original failure output.182. If the failure is intermittent, control time, randomness, concurrency, data, and retries one variable at a time.193. Trace the failing path end to end. Search every caller of the function or component before editing it.204. Form a falsifiable hypothesis and run the narrowest check that can confirm or reject it.215. Use history or `git bisect` only when a regression boundary will materially shorten the search.2223Separate these outcomes explicitly:2425- confirmed product regression;26- pre-existing or baseline failure;27- environment, credentials, service, or dependency failure;28- insufficient evidence to reproduce.2930## Fix when authorized31321. Add or adapt the smallest regression check that fails for the confirmed cause.332. Fix the shared root cause rather than guarding one visible caller.343. Avoid unrelated refactors, dependency upgrades, formatting churn, and broad exception handling.354. Re-run the reproduction, focused regression check, and the smallest relevant project checks.3637Use the package manager, wrapper, and commands already selected by the repository. Infer them from repository instructions, manifests, lockfiles, and scripts; do not substitute another tool just because it is installed locally.3839## Report4041Include:4243- **Observed:** exact symptom and affected scope.44- **Root cause:** confirmed explanation, or the leading hypothesis clearly labeled.45- **Change:** files and behavior changed, or `diagnosis only`.46- **Verification:** commands and results, including baseline failures.47- **Remaining risk:** untested paths, flaky behavior, or external blockers.4849Use `references/bug-report-template.md` only when the user needs a reusable intake form.
jMerta