Creates a structured bug report from a description, or analyzes code to identify potential bugs. Ensures every bug report has full reproduction steps, severity assessment, and context.

! bash "${CLAUDE SKILL DIR}/../../hooks/yaml helper.sh" resolve config keys automation Automation mode : Resolve modes.automation ( project.local.yaml → project.yaml → default collaborative ). Every AskUserQuestion call and every file write follows .claude/docs/automation modes.md (collaborative asks always · guided major only · autonomous logs and proceeds; automation always ask categories always prompt). Bug Report Drafts only. This skill writes reports to production/qa/bugs/ . When the cause is in the engine, a plugin or another vendor's code, add a draft for their tracker under Notes and stop there: never file, open or comment on an issue or pull request in their repository. The user submits it. Phase 1: Parse Arguments Determine the mode from the argument: No keyword → Description Mode : generate a structured bug report from the provided description analyze [path] → Analyze Mode : read the target file(s) and identify potential bugs verify [BUG ID] → Verify Mode : confirm a reported fix actually resolved the bug close [BUG ID] → Close Mode : mark a verified bug as closed with resolution record If no argument is provided, ask the user for a bug description before proceeding. Phase 2A: Description Mode 1. Parse the description for key information: what broke, when, how to reproduce it, and what the expected behavior is. 2. Search the codebase for related files using Grep/Glob to add context (affected system, likely files). 3. Draft the bug report : The Severity and Priority labels use /bug triage 's S and P numbers and names, which it parses out of this file. P4 Won't fix is its P4 — Won't fix / Deferred (an accepted risk), not a wishlist. If you change either ladder, change .claude/skills/bug triage/SKILL.md too. Phase 2B: Analyze Mode 1. Read the target file(s) specified in the argument. 2. Identify potential bugs : null references, off by one errors, race conditions, unhandled edge cases, resource leaks, incorrect state transitions. 3. For each potential bug , generate a bug report using the template above, with the likely trigger scenario and recommended fix filled in. Phase 2C: Verify Mode Find the bug file by its number , here and in close mode: Glob production/qa/bugs/BUG .md and take the file whose number matches [BUG ID] , whatever its zero padding — an older three digit file with a slug is found by its number too. If none matches, stop: "No bug [BUG ID] in production/qa/bugs/ ." Verdict: BLOCKED — no such bug. Read that file. Extract the reproduction steps and expected result. 1. Re run reproduction steps — use Grep/Glob to check whether the root cause code path still exists as described. If the fix removed or changed it, note the change. 2. Run the related test — if the bug's system has a test file in the engine's test root ( tests/ Godot, Assets/Tests/ Unity, Source/<Module /Private/Tests/ Unreal — .claude/docs/directory structure.md ), run it via Bash with commands.test from project.yaml , narrowed to the affected suite where the runner allows — never a runner line written from memory, which drops the flags the engine needs (gdUnit4 hangs without remote debug tcp://127.0.0.1:0 ) — and report pass/fail. commands.test unset → no test ran: name the unset key and go on to step 3. 3. Check for regression — grep the codebase for any new occurrence of the pattern that caused the bug. 4. Manual verification — when no related test ran (none covers the bug — the usual case where qa.level waives tests — commands.test is unset, or the run did not complete), or the bug's Category is Visual or UI, whose look no automated test checks, ask via AskUserQuestion : "Did you play the reproduction steps in [bug file] on a build with the fix? Which build?" — [No longer occurs] / [Still occurs] / [Not played yet] . Record the answer and the build as the user gives them; a changed code path is never taken as their answer. Run as a subagent? qa lead preloads this skill, and a subagent has no AskUserQuestion . End your reply with the question and its three options as a short list, and give no verdict yet: whoever called you asks the user, and the verdict waits for the answer. Produce a verification verdict: VERIFIED FIXED — the bug is gone by every check that applies: any related test ran and passed, and, where step 4 asked, the user answered [No longer occurs] for a named build. With no test run, that play alone is the verification — a manual one, recorded as such: [user], manual, build [X] . A changed code path on its own is never a pass STILL PRESENT — a related test fails on the bug's case, or the user answered [Still occurs] ; the fix did not resolve the issue CANNOT VERIFY — step 4 was answered [Not played yet] : name what is missing or could not run (no related test, commands.test unset, a run that did not complete, a Visual or UI bug), and say that playing the reproduction steps settles it — run /bug report verify [BUG ID] again once played Ask: "May I update production/qa/bugs/[bug file] to set Status: Verified Fixed / Still Present / Cannot Verify?" — naming the file found above, whatever its padding or slug. With the Status, write a Verified by : line under it: [test file(s)] — ran and passed , or [user], manual, build [X] for a manual verification. If STILL PRESENT: reopen the bug, set Status back to Open, and suggest re running /hotfix [BUG ID] . Phase 2D: Close Mode Read the bug file, found by its number as in verify mode. Confirm Status is Verified Fixed before closing. If status is anything else, stop: "Bug [ID] must be Verified Fixed before it can be closed. Run /bug report verify [BUG ID] first." Show the closure record below and the Status change, then ask: "May I update production/qa/bugs/[bug file] to mark it Closed?" Nothing is written before a yes; on no, stop — the bug stays Verified Fixed. On yes, append the closure record to the bug file: Then update the top level Status : field to Status : Closed . After closing, check production/qa/bug triage .md — if the bug appears in an open triage report, note: "Bug [ID] is referenced in the triage report. Run /bug triage to refresh the open bug count." Phase 3: Save Report Present the completed bug report(s) to the user. Allocate the ID before asking: Glob production/qa/bugs/BUG .md , take the highest number and add 1, zero padded to four digits ( BUG 0001 when there are none). Several reports in one run (analyze mode) take consecutive IDs from there, one each — never the same ID twice. Ask: "May I write this to production/qa/bugs/BUG [NNNN].md ?" For several reports, ask once and name every file: "May I write these to production/qa/bugs/BUG [NNNN].md , production/qa/bugs/BUG [NNNN+1].md , …?" If yes, write the file, creating the directory if needed. Verdict: COMPLETE — bug report filed. If no, stop here. Verdict: BLOCKED — user declined write. Phase 4: Next Steps After saving, suggest based on mode: After filing (Description/Analyze mode): Run /bug triage to prioritize alongside existing open bugs If S1 or S2: run /hotfix [BUG ID] for emergency fix workflow After fixing the bug (developer confirms fix is in): Run /bug report verify [BUG ID] — confirm the fix actually works before closing Never mark a bug closed without verification — a fix that doesn't verify is still Open After verify returns CANNOT VERIFY: Play the reproduction steps on a build with the fix, then run /bug report verify [BUG ID] again and answer its question After verify returns VERIFIED FIXED: Run /bug report close [BUG ID] — write the closure record and update status Run /bug triage to refresh the open bug count and remove it from the active list

bug-report