# QA Bug Reporting > Bug report format and documentation for failed validations. Use when validation fails and status must be set to needs_fixes. Use when this capability is needed. - Skill: `tomevault-io/qa-bug-reporting` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/qa-bug-reporting` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/qa-bug-reporting/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/qa-bug-reporting --- # Bug Reporting Skill > "A good bug report is half the fix – be specific, be reproducible." ## When to Use This Skill Use when validation fails and `status` must be set to `needs_fixes`. ## Quick Start ```markdown ## Bug Report: {{TASK_ID}} **Severity**: Critical / High / Medium / Low **Found in**: Automated tests / Code review / Console inspection ### Summary Brief one-line description of the issue. ### Steps to Reproduce 1. Step one 2. Step two 3. Step three ### Expected Behavior What should happen. ### Actual Behavior What actually happens. ### Evidence - Console errors: {{error text}} - Screenshot: {{path}} ``` ## Bug Report Template ```markdown # Bug Report: {{TASK_ID}} - {{BRIEF_TITLE}} **Reported**: {{ISO_TIMESTAMP}} **Reporter**: QA Agent **Severity**: {{Critical | High | Medium | Low}} **Category**: {{Build | TypeScript | Runtime | Visual | Performance}} --- ## Summary {{One or two sentences describing the issue}} ## Environment - **OS**: {{Windows / macOS / Linux}} - **Node Version**: {{v20.x.x}} - **Context**: {{Development server / Production / Browser console}} ## Steps to Reproduce 1. {{First step}} 2. {{Second step}} 3. {{Third step}} 4. {{...}} ## Expected Behavior {{What should happen when following the steps}} ## Actual Behavior {{What actually happens instead}} ## Console Errors \`\`\` {{Paste console errors here}} \`\`\` ## Screenshots {{Include paths to screenshots or describe what was captured}} ## Additional Context {{Any other relevant information: - Related code files - Recent changes that might have caused this - Workarounds attempted - Similar issues seen before}} ## Acceptance Criteria Status | Criterion | Status | Notes | | --------------- | ----------------- | --------- | | {{Criterion 1}} | ✅ Pass / ❌ Fail | {{notes}} | | {{Criterion 2}} | ✅ Pass / ❌ Fail | {{notes}} | | {{Criterion 3}} | ✅ Pass / ❌ Fail | {{notes}} | --- ## For Developer **Files likely involved**: - {{file1.ts}} - {{file2.tsx}} **Suggested investigation**: - {{Suggestion 1}} - {{Suggestion 2}} ``` ## Severity Levels | Severity | Definition | Example | | ------------ | ------------------------------------------ | ------------------------------ | | **Critical** | App crashes, data loss, blocks all testing | Build fails, app won't load | | **High** | Major feature broken, no workaround | Player controls don't work | | **Medium** | Feature partially works, has workaround | Physics jittery but functional | | **Low** | Minor issue, cosmetic, edge case | Slight visual glitch on resize | ## Category Types | Category | Description | Automated Check | | --------------- | ---------------------- | --------------------- | | **Build** | Build or bundle fails | `npm run build` | | **TypeScript** | Type errors | `npm run type-check` | | **Lint** | Code style issues | `npm run lint` | | **Test** | Unit test failure | `npm run test` | | **Runtime** | Error during execution | Console inspection | | **Visual** | Incorrect appearance | Visual inspection | | **Performance** | FPS drops, lag, memory | Performance profiling | ## Anti-Patterns ❌ **DON'T:** - Report bugs without reproduction steps - Use vague descriptions ("it doesn't work") - Omit error messages - Skip severity classification - Blame the developer in the report - **Report code issues without thorough code review** - ALWAYS verify actual code flow before concluding there's a bug - **Confuse valid async patterns with "bypasses"** - async functions with multiple calls may appear suspicious but can be correct - **Escalate without investigating** - trace the code flow from entry point to execution before reporting ✅ **DO:** - Include exact steps to reproduce - Copy full error messages - Attach screenshots - Specify environment details - Suggest where to investigate - **Perform thorough code review before reporting** - trace actual code execution flow - **Verify suspected "bypasses" by testing the actual behavior** - if you suspect code skips connection, verify by running the app - **Include observed vs. expected behavior** - be specific about what you saw that was wrong, not just code that looked suspicious - **Code review BEFORE escalating** - read the actual implementation files and understand the flow before filing a bug report ## Code Review Before Bug Reporting **CRITICAL: Before reporting a code-related bug, you MUST:** 1. **Read the actual implementation files** - Don't guess what code does based on a quick glance 2. **Trace the execution flow** - Follow the code from entry point to the suspected issue 3. **Verify the actual behavior** - Run the app and observe what actually happens 4. **Compare expected vs. actual** - Be specific about what should happen vs. what does happen ### Example: Common Pitfall A report claimed "code appears to skip connection" but tracing actual flow showed proper initialization: - `initializeConnection` PROPERLY calls `networkManager.connect()` and `joinRoom()` - Server logs showed "listening" and client connected successfully - Root cause was a different issue (CORS configuration, not the suspected code) ## Bug Report Message When reporting a bug, send a `bug_report` message to PM with full bug details: ````json { "id": "msg-pm-{timestamp}-001", "from": "qa", "to": "pm", "type": "bug_report", "priority": "high", "payload": { "taskId": "{taskId}", "bugs": [{ "file": "src/file.ts", "line": 42, "issue": "Type error: Type 'string' is not assignable...", "severity": "critical", "summary": "Build fails with TypeScript error", "steps": ["Run npm run build", "Observe error"], "expected": "Build succeeds", "actual": "TS2322 error" }] }, "timestamp": "{ISO_TIMESTAMP}" } ```` **⚠️ IMPORTANT:** QA does NOT update prd.json directly. PM syncs bug information from bug_report message. **Note:** Commit format templates for failed validations are in `qa-workflow` skill. --- ## Checklist Before submitting bug report: - [ ] **Code review performed** - Read and traced the actual implementation files - [ ] **Actual behavior verified** - Ran the app and observed what actually happens - [ ] Summary is clear and specific - [ ] Reproduction steps are complete - [ ] Expected vs actual clearly stated - [ ] Console errors included - [ ] Screenshots attached (if visual) - [ ] Severity assigned - [ ] Category assigned - [ ] Environment specified - [ ] bug_report message sent to PM ## References - [../../agents/qa/AGENT.md](../../AGENT.md) — Full QA instructions - [../qa-validation-workflow/SKILL.md](../qa-validation-workflow/SKILL.md) — Full workflow --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/feliperyba) — claim your Tome and manage your conversions.