| name | qa-bug-reporting |
| description | Bug report format and documentation for failed validations. Use when validation fails and status must be set to needs_fixes. |
| category | 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
## 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
# 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:
- Read the actual implementation files - Don't guess what code does based on a quick glance
- Trace the execution flow - Follow the code from entry point to the suspected issue
- Verify the actual behavior - Run the app and observe what actually happens
- 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:
{
"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:
References
