bug-investigation

Bug Investigation

A bug report says what broke. How much it costs, where it lives, and whether this failure has happened before are all outside it — and the third is usually the cheapest of the three to find, because someone has already paid for the answer. This skill produces one cited brief: a severity with the reasoning that produced it, a ranked suspected area with the evidence pointing there, and the past failures that resemble this one together with what actually fixed them. It is triage, not repair — the diagnosis and every line of the fix stay with the developer.

Underneath, memory-search owns the search ladder and the relevance gate, graph-traversal owns relationship walking when a summary names an incident without stating it, and memory-capture owns any durable write; all three ship with the gutt-pro plugin (this plugin depends on it) — without them, follow the rules below and note the gap in one line. Jira access comes from whatever Atlassian tooling the session surfaces; find it in your tool list — names and prefixes vary per install.

Hard rules (non-negotiable — read first)

1. Jira is read-only here — never write a severity into it. No priority or severity fields, no component or label edits, no status transitions, no assignment. The one permitted write is a comment the user explicitly asked for, posted only after they approve the exact text in this session. Treat it as final — approval is the gate, not an undo; a truly needed correction re-approves the text and targets the existing comment if the tool allows, rather than posting a second one. Write markdown and set the tool's content-format parameter to markdown when it exposes one.
2. Severity carries the rubric it was scored against. Read the scale the team actually uses off the ticket, its siblings, and anything memory records about severity conventions; if none is visible, ask, or state the default you applied — user impact × blast radius × whether a workaround exists — and say it is a default. Never emit a bare label: a severity without its rubric and its two or three deciding observations is an opinion wearing a badge.
3. The suspected area is a ranked hypothesis, and it says what would refute it. One to three candidates, most likely first, each with the evidence that points there and the single cheapest check that would rule it out. A hypothesis nothing could falsify is a guess — label it one.
4. Every finding cited. A past failure names its source: an incident, lesson, or episode (id, date), a ticket key with its resolution, or a comment with author and date. Uncitable material does not enter the brief. Absence is the exception by nature — it names what was looked for, not a source.
5. "No similar failure found" carries its scope. State the phrasings searched and the JQL angles tried, so absence is a checkable claim rather than a shrug. This matters most on the bugs that really are new: the brief has to be trustworthy when it says so.
6. A resemblance is not a root cause. A past failure that looks like this one is a lead with a citation, never the diagnosis. Report what the earlier fix was and what would confirm the same cause holds here; do not assert the cause, and never present a past fix as this bug's fix.
7. Org scope is checked at the output, not the request. Pass explicit group_ids naming the org group on reads — take the name from results already in the session or ask; never guess one, a guessed group id is a fabricated identifier. Treat scope as server-decided: before any finding enters the offered comment, confirm that item's own scope is the org group; personal-scope findings stay in the in-session brief, marked as personal. The same filter applies before any finding enters a comment the user asked to have posted. Bare tool names, probed with ToolSearch before concluding one is missing. No memory writes — a durable root-cause lesson goes through memory-capture and its trust-tier gate.