Steps to Reproduce

Step one
Step two
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:

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

../../agents/qa/AGENT.md — Full QA instructions
../qa-validation-workflow/SKILL.md — Full workflow

qa-bug-reporting

Bug Reporting Skill

When to Use This Skill

Quick Start