bug-triage
Use when diagnosing a bug in code. Five steps: understand the symptom, form hypotheses, test each with the smallest experiment, isolate the root cause, then fix with a regression test. For issue-tracker states and roles, use issue-triage.
- License 许可
- MIT
- 所属仓库
- iberi22/skills
- 最近更新
- 2026-10-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- bug-triage
- slug
- bug-triage
- tags
- [ "triage", "debugging", "bug", "diagnosis", "root-cause", "workflow" ]
- goals
- [ "Diagnose bugs systematically, not at random", "Shorten the time from symptom to root cause", "Test hypotheses with the smallest possible experiment", "Document findings to avoid similar bugs" ]
- authors
- [ "mattpocock (original repo)", "Brahyan Belalcazar (structured version)" ]
- context
- { "who": "Any coding agent", "when": "A bug, error, or unexpected behavior is reported", "prerequisites": "Access to the code and system logs" }
- license
- MIT
- version
- 1.0.0
- category
- debugging
- description
- Use when diagnosing a bug in code. Five steps: understand the symptom, form hypotheses, test each with the smallest experiment, isolate the root cause, then fix with a regression test. For issue-tracker states and roles, use issue-triage.
- original_source
- https://github.com/mattpocock/skills
03 SKILL.md 正文
Bug triage — bug diagnosis workflow
This skill sets a systematic 5-step process for diagnosing bugs without changing code at random. Each step produces information that feeds the next.
Principles
- Do not touch code without a hypothesis. If you do not know what you are testing, you are guessing.
- The smallest experiment wins. Narrow the scope until the answer is yes or no.
- Reproduce before diagnosing. If you cannot reproduce it, you cannot confirm the fix.
- Document at each step. A bug unresolved today is useful information tomorrow.
Step 1: Understand the symptom
Before touching code, characterize the problem:
- What is expected vs. what happens?
- Is it consistent or intermittent?
- Which environment? (local, staging, production)
- When did it start? What changed just before?
- Are there stack traces, logs, or error messages?
Deliverable: A 2–3 line paragraph describing the symptom without naming causes.
Step 2: Form hypotheses
Generate 2–4 plausible explanations, ordered by likelihood. Use your knowledge of the system, not vague intuitions.
Format of each hypothesis:
H1: <what is failing> → <why you think so> → <which experiment confirms or rejects it>
Example:
H1: The auth service returns 401 because the token expires earlier than expected.
→ The bug occurs only after 15 min of inactivity.
→ Experiment: log the token TTL at the moment of the 401.
Step 3: Test with the smallest possible experiment
For each hypothesis, design an experiment that is:
- Fast: under 10 minutes of setup.
- Isolated: does not depend on other systems where possible.
- Binary: produces a result that confirms or rejects the hypothesis.
Useful techniques:
| Technique | When to use it |
|---|---|
| Log points | You need variable values at runtime without stopping the flow. |
| Binary search in git | The bug appeared in some recent commit. Use git bisect. |
| Minimal reproduction | Remove dependencies, code, and data until the bug still occurs in the smallest possible setup. |
| Temporary monkey-patch | Force a value or bypass to confirm whether a dependency is the culprit. |
| State diff | Compare system state (DB, cache, config) between a working and a failing environment. |
Rule: If an experiment does not halve the search space, it is too big.
Step 4: Isolate the root cause
When a hypothesis is confirmed, keep digging until you find the root cause, not just the symptom.
Guiding questions:
- Is it a bug in my code or in a dependency?
- Is it a logic, configuration, or data error?
- Why does this input produce this output? Follow the data flow.
- Is an invariant being broken? Where should it have been validated?
Deliverable: One sentence explaining the root cause, linking the defect to the observable effect.
Step 5: Fix + regression test
- Fix the minimum necessary. A large fix is suspicious.
- Verify the fix works. Reproduce the bug with the Step 1 steps; it must disappear.
- Add a regression test. If possible, write a test that fails before the fix and passes after.
- Document briefly. Note in the commit or a doc why it happened and how to avoid it.
Anti-patterns to avoid
- Changing code and seeing what happens. This destroys information.
- Debugging without reproducing first. You lose confirmation of success.
- Assuming the bug is "obvious". The root cause is usually 2–3 levels below the symptom.
- Jumping to a fix without a confirmed hypothesis. You fix the symptom, not the bug.
Quick checklist
- [ ] Symptom clearly described
- [ ] Hypotheses written and ordered
- [ ] Minimal experiment run
- [ ] Root cause identified
- [ ] Fix applied and verified
- [ ] Regression test added
- [ ] Findings documented
04 同仓库更多 Skills
web-design-guidelines
暂无简介
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall. Recovers the page via archives and provenance-checked fallbacks.
studio-coach
暂无简介
src-generator
暂无简介
sqlite-pro
暂无简介
rigor-evaluator
Use when you need a quick heuristic rigor score (10 criteria, 0-2 each) for the features in a .gitcore/features.json file, to decide which features are ready to ship.