Bug Report Writer

Turn bug findings into a report anyone (dev, PO, QA) can read once and act on. The skill organizes and writes — it doesn't investigate or fill in blanks. The report comes first; opening a ticket is an optional last step.

What to read: references/report-template.md always; references/severity-guide.md unless the team gave severity; references/labels.md only when the report isn't in English. The rest only when needed: examples.md if unsure about format, input-checklist.md if the user wants a fill-in template, tracker-integration.md if a tracker tool is connected.

Not a bug report?

If invoked for something else (flaky-test investigation, fixing code, test cases, a sprint report, a JQL query), say in one line what this skill does, then help with what was asked. If a real bug turns up, offer to write it up at the end.

Language

Look for .qa-skills.yaml in the project root, then ~/.qa-skills.yaml. language is for what you say to the user; report_language (default: language) is for the report. An explicit request overrides the file — one that targets only the report ("escreve o bug em inglês") changes only the report; any other ("responde em espanhol", "escreve tudo em inglês") changes both. Otherwise use the language of the user's message. Don't mention a missing file. Evidence (logs, payloads, on-screen text) is never translated.

Source fidelity

Every invented detail costs a developer time: a step the tester never did sends them down the wrong path, a guessed version makes them reproduce on the wrong setup, an assumed impact skews priority. Honest gaps beat plausible fiction.

• Sources: what the user wrote; files they gave (logs, payloads, HAR, test code, CI output); what is visible in screenshots you can see (say "the screenshot shows…").
• Yours, always labeled: the title (built from sourced facts), severity/priority marked (suggested) when the team didn't set them, wording and structure.
• Never add: steps not described (not even "log in first"), preconditions, test data, environment/version/platform (browser, OS, device, DB, broker…), IDs, endpoints, status codes, messages, requirement numbers, what "correct" is, impact, frequency, root cause, scope on other platforms.

A field with no source gets ⚠️ NOT PROVIDED and goes into Missing information.

1. Triage

Give the user something useful in this reply — don't interrogate them first.

• A. Bug with a sourced expected behavior — requirement, story, spec, previous behavior, a failing assertion, or the user saying what should happen ("deveria salvar", "pretty sure it should show up there" → "according to the tester"). Write the full report now, with gaps marked.
• B. Unclear whether it's a bug — the user is unsure and gives no expected behavior. Don't decide what's correct: ask up to 5 short questions and offer a [SUSPECTED] report for the PO.
• C. Several problems — one report each, triaged separately, plus a summary table.

2. Write the report

Follow the template in the report language. Mandatory sections (Where, Steps, Actual, Expected, Environment, Evidence) stay even if they only hold ⚠️ NOT PROVIDED; drop empty optional ones.

• Title — [Module] - What happens + Where + Condition, < ~120 chars, behavior not cause. ✅ [PIX] - App Android não solicita MFA em transferência de R$ 5.000,00 ❌ Erro no PIX
• Where (interface) — what a dev looks for first. The skill is interface-agnostic: describe the interface where the bug manifests, in that interface's own terms — UI (screen path Menu > Extrato > Filtro, URL), REST/SOAP/GraphQL API (method + endpoint, status, response received), database (instance/schema, table, query or procedure, ORA-/SQL error), queue/topic (name, message ID, consumer, DLQ), batch/job (name, run ID, log), integration, CLI, etc. Fill only what applies to the bug's interface; never add fields from another interface (no "Screen: NOT PROVIDED" for an API/DB/queue bug). Anything else the user mentioned (e.g. the screen that triggered an API call) goes in as context, not as a gap. Mark as missing only what that interface needs (e.g. response body for an API, message payload for a queue).
• Steps — one action each, exactly what the user did, data in code. Partial flow → partial steps. No extras the user didn't do — setup ("log in"), "observe/verify the result", "open the downloaded file": what was observed belongs in Actual result, not in a step. From a failed test: steps from the test code, actual result from the assertion/error.
• Actual / Expected — exact messages; expected cites its source as given ("conforme RN2", "segundo o testador").
• Reproducibility — as the source states it ("1 failed, retries: 2/2 failed"); don't recompute.
• Technical data / Evidence — payloads and logs once, in fenced blocks, trimmed but unaltered; Evidence lists attachments without re-pasting them.
• Description — 2–4 sentences of what the user reported; impact only if they said it. Their hypotheses go in Additional notes, labeled.
• Severity — team's values, or the guide's, (suggested) with a one-line justification from known facts. No "could be higher if…": if an unknown would change it, put it in Missing information.
• Sensitive data — mask passwords, tokens, Authorization, API keys, cookies, card numbers, CPF/SSN and real customers' data, inside logs too. Test data stays. Masking is the only allowed change to evidence.
• Missing information — ordered by what a dev needs to reproduce: where (path/URL or endpoint + response) → environment/version → steps/test data → evidence → reproducibility.

3. Check

Read it as a skeptical developer: every sentence must trace back to the input. Anything that doesn't is an invention — remove it or mark it ⚠️ NOT PROVIDED. No secrets, one bug per report.

4. Deliver

Send the report, then one short closing line: ask for the first 1–2 items of Missing information — already in priority order, so if "where" is missing, that's what you ask for (don't re-list the rest) and offer to save it as bug-reports/BUG-<YYYY-MM-DD>-<slug>.md (one file per bug). If no tracker tool is connected, add that connecting its MCP lets you open the ticket. With a tracker connected, follow tracker-integration.md and only create the ticket after explicit confirmation — and not while mandatory fields are ⚠️ NOT PROVIDED, unless the user insists.

Markdown by default; offer Jira wiki markup (h3., {code:json}) for Jira's legacy editor.