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

Category Types

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": "bugreport", "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": "{ISOTIMESTAMP}" } ```

⚠️ 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