Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-bug-report
saas-bug-report
UnverifiedStructured bug report from a description, or analyze code for potential bugs. Reproduction steps, severity.
Running this workflow on this client
Run shell commands from the project root. On Windows, use Git Bash for the bash commands if bash resolves to an unavailable WSL distribution. Shared studio files are under .claude/; run the local Studio installer for this project if those files are missing. Read .claude/docs/config-resolution.md and apply its defaults when configuration cannot be resolved. Use this client's tools for reads, edits, and structured questions. If structured questions are unavailable, ask in chat and wait when a decision requires approval. Use the client's delegation feature with the role brief in .claude/agents/ when available. Otherwise perform the specialist checks in sequence and disclose that they were done in one session. If a workflow requires independent sign-off, report it as pending until an independent reviewer can provide it. Treat Task* steps as local workflow tracking using the client's equivalent when available. Report missing tools and unexecuted checks explicitly.
Run bash .claude/hooks/yaml-helper.sh resolve_config --keys locale,automation and use its output below.
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
Interaction Localization Rule: When
locale: pt-BR(or user speaks Portuguese), ALL questions (AskUserQuestion/ask_question), confirmation prompts, and selectable options MUST be translated and presented in Brazilian Portuguese (PT-BR). Any English question text or options in this skill are illustrative examples — NEVER display English questions or options to a Portuguese developer. Internal reasoning, code synthesis, tests, and documentation files MUST remain in English.
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 bugsverify [BUG-ID]→ Verify Mode: confirm a reported fix actually resolved the bugclose [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
-
Parse the description for key information: what broke, when, how to reproduce it, and what the expected behavior is.
-
Search the codebase for related files using Grep/Glob to add context (affected system, likely files).
-
Draft the bug report:
# Bug Report
## Summary
**Title**: [Concise, descriptive title]
**ID**: BUG-[NNNN]
**Severity**: [S1-Critical / S2-High / S3-Medium / S4-Low]
**Priority**: [P1-Fix this sprint / P2-Fix soon / P3-Backlog / P4-Won't fix]
**Status**: Open
**Reported**: [Date]
**Reporter**: [the reporter's name as the user gives it, else `—`; never an email address or account ID taken from the session]
## Classification
- **Category**: [Core Business Workflow / UI / Audio / Visual / Performance / Crash / Network]
- **System**: [Which product system is affected — when the bug spans systems, the one whose code must change; the others go under Related systems]
- **Frequency**: [Always / Often (>50%) / Sometimes (10-50%) / Rare (<10%)]
- **Regression**: [Yes/No/Unknown -- was this working before?]
## Environment
- **Build**: [Version or commit hash]
- **Platform**: [OS, hardware if relevant]
- **Route/View**: [Where in the application]
- **App State**: [Relevant state -- user session, route, active workspace tier, etc.]
## Reproduction Steps
**Preconditions**: [Required state before starting]
1. [Exact step 1]
2. [Exact step 2]
3. [Exact step 3]
**Expected Result**: [What should happen]
**Actual Result**: [What actually happens]
## Technical Context
- **Likely affected files**: [List of files based on codebase search]
- **Related systems**: [What other systems might be involved]
- **Possible root cause**: [If identifiable from the description]
## Evidence
- **Logs**: [Relevant log output if available]
- **Visual**: [Description of visual evidence]
## Related Issues
- [Links to related bugs or design documents]
## Notes
[Any additional context or observations]
The Severity and Priority labels use /saas-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/saas-bug-triage/SKILL.md too.
Phase 2B: Analyze Mode
-
Read the target file(s) specified in the argument.
-
Identify potential bugs: null references, off-by-one errors, race conditions, unhandled edge cases, resource leaks, incorrect state transitions.
-
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.
- 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.
- Run the related test — if the bug's system has a test file in the stack's test root (
tests/unit/ortests/integration/—.claude/docs/directory-structure.md), run it via Bash withcommands.testfromproject.yaml, narrowed to the affected suite where the runner allows, and report pass/fail.commands.testunset → no test ran: name the unset key and go on to step 3. - Check for regression — grep the codebase for any new occurrence of the pattern that caused the bug.
- Manual verification — when no related test ran (none covers the bug — the usual case where
qa.levelwaives tests —commands.testis unset, or the run did not complete), or the bug's Category is Visual or UI, whose look no automated test checks, ask viaAskUserQuestion: "Did you test the reproduction steps in [bug file] on a deployment/build with the fix? Which environment?" —[No longer occurs]/[Still occurs]/[Not tested yet]. Record the answer and the environment as the user gives them; a changed code path is never taken as their answer. Run as a subagent?qa-leadpreloads this skill, and a subagent has noAskUserQuestion. 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.testunset, a run that did not complete, a Visual or UI bug), and say that playing the reproduction steps settles it — run/saas-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 /saas-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 /saas-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:
## Closure Record
**Closed**: [date]
**Resolution**: Fixed — [one-line description of what was changed]
**Fix commit / PR**: [if known]
**Verified by**: [the verify record's `**Verified by**:` line — the test that ran and passed, or "[user], manual, build [X]"]
**Closed by**: [user]
**Regression test**: [test file path, or "Manual verification" when verify recorded a manual play]
**Status**: Closed
Then update the top-level **Status**: field to **Status**: Closed.
After closing, check production/qa/saas-bug-triage-*.md — if the bug appears in an open triage report, note: "Bug [ID] is referenced in the triage report. Run /saas-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
/saas-bug-triageto prioritize alongside existing open bugs - If S1 or S2: run
/saas-hotfix [BUG-ID]for emergency fix workflow
After fixing the bug (developer confirms fix is in):
- Run
/saas-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
/saas-bug-report verify [BUG-ID]again and answer its question
After verify returns VERIFIED FIXED:
- Run
/saas-bug-report close [BUG-ID]— write the closure record and update status - Run
/saas-bug-triageto refresh the open bug count and remove it from the active list
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |