latestaiagents/bug-reporting

Bug Reporting

Write clear, actionable bug reports that get fixed faster.

When to Use

• Reporting a new bug
• Improving existing bug reports
• Training team on bug reporting
• Setting up bug templates
• Triaging and prioritizing issues

Bug Report Template

## Bug: [Clear, descriptive title]

**ID:** BUG-[number]
**Reporter:** [Name]
**Date:** [Date]

### Severity & Priority
- **Severity:** Critical / High / Medium / Low
- **Priority:** P0 / P1 / P2 / P3

### Environment
- **OS:** [e.g., macOS 14.1, Windows 11]
- **Browser:** [e.g., Chrome 120.0.6099]
- **App Version:** [e.g., 2.3.1]
- **Environment:** [Production / Staging / Dev]
- **Device:** [Desktop / Mobile / Tablet]

### Description
[1-2 sentences describing what's wrong]

### Steps to Reproduce
1. [First step]
2. [Second step]
3. [Third step]
4. [Continue until bug occurs]

### Expected Result
[What should happen]

### Actual Result
[What actually happens]

### Evidence
- Screenshot: [attachment]
- Video: [link]
- Console logs: [attachment]
- Network logs: [attachment]

### Additional Context
- Frequency: [Always / Sometimes / Rarely]
- Workaround: [If any]
- Related issues: [Links]

### Technical Notes (if known)
- Error message: [exact text]
- Stack trace: [if available]
- Related code: [file/function if known]

Example Bug Reports

Good Bug Report

## Bug: Checkout fails with "undefined" error when applying discount code

**ID:** BUG-1234
**Reporter:** Jane Smith
**Date:** 2026-02-05

### Severity & Priority
- **Severity:** High (blocks purchases)
- **Priority:** P1

### Environment
- **OS:** macOS 14.2
- **Browser:** Chrome 121.0.6167.85
- **App Version:** 3.2.0
- **Environment:** Production

### Description
When applying a valid discount code at checkout, the page shows an "undefined" error and prevents order completion.

### Steps to Reproduce
1. Add any item to cart
2. Go to checkout (/checkout)
3. Enter discount code "SAVE20"
4. Click "Apply"
5. Error appears, "Apply" button becomes disabled

### Expected Result
- Discount of 20% applied to order total
- Updated total displayed
- User can proceed to payment

### Actual Result
- Red error message: "Error: undefined"
- Apply button grayed out
- Cannot proceed with checkout
- Must refresh page to continue (without discount)

### Evidence
- Screenshot: [checkout-error.png]
- Console error: `TypeError: Cannot read property 'value' of undefined at applyDiscount (checkout.js:142)`
- Network: POST /api/discounts returns 200 with valid response

### Additional Context
- Frequency: Always (100% reproducible)
- Workaround: Complete checkout without discount code
- Started after deploy on 2026-02-04
- Works correctly on staging environment

### Technical Notes
- Error in checkout.js:142
- Appears to be missing null check on discount response
- Related PR: #1456 (discount feature)

Poor Bug Report (Don't Do This)

## Bug: Checkout broken

Checkout doesn't work. Please fix ASAP.

Attached screenshot.

Severity Guidelines

| Severity | Definition | Examples | |----------|------------|----------| | Critical | System down, data loss, security breach | App crashes on launch, payment processing fails for all users, SQL injection vulnerability | | High | Major feature broken, significant user impact | Cannot complete checkout, search returns wrong results, login fails intermittently | | Medium | Feature partially working, workaround exists | Filter doesn't work on one category, export missing some columns | | Low | Minor issue, cosmetic, edge case | Typo in error message, button alignment off by 2px, rare edge case fails |

Priority Guidelines

| Priority | Definition | Response | |----------|------------|----------| | P0 | Drop everything | Fix immediately, hotfix to prod | | P1 | Current sprint | Fix within 1-2 days | | P2 | Next sprint | Plan for upcoming sprint | | P3 | Backlog | Fix when time permits |

Reproduction Tips

Be Specific

❌ Bad: "Click the button"
✅ Good: "Click the blue 'Submit' button in the bottom-right corner of the form"

❌ Bad: "Enter some data"
✅ Good: "Enter '[email protected]' in the email field"

❌ Bad: "Wait a while"
✅ Good: "Wait approximately 30 seconds until the loading spinner disappears"

Include State

### Preconditions
- Logged in as user: [email protected]
- Shopping cart contains 3 items totaling $150
- User has no saved payment methods
- User's account was created > 30 days ago

Document Environment

# Useful commands for environment info

# Browser version (from console)
navigator.userAgent

# OS info
uname -a  # Linux/Mac
systeminfo  # Windows

# App version
cat package.json | grep version

Evidence Collection

Screenshots

Best practices:
- Capture full screen or relevant area
- Highlight the issue (circle, arrow)
- Include URL bar when relevant
- Show error messages clearly
- Use before/after comparisons

Screen Recordings

Tools:
- macOS: Cmd+Shift+5
- Windows: Win+G (Game Bar)
- Chrome: Ctrl+Shift+R (DevTools)
- Loom, ScreenPal for sharing

Best practices:
- Keep under 60 seconds
- Narrate or add captions
- Show the steps clearly
- Include the error occurring

Console Logs

// Capture console errors
// Open DevTools (F12) > Console tab

// Copy all console output:
// Right-click > Save as... (Chrome)

// Filter errors only:
// Click 'Errors' filter in console

Network Logs

How to capture:
1. Open DevTools > Network tab
2. Enable "Preserve log"
3. Reproduce the issue
4. Right-click > "Save all as HAR"

What to look for:
- Failed requests (red)
- Status codes (4xx, 5xx)
- Response bodies
- Request payloads

Bug Triage Process

## Daily Triage Meeting

### Agenda (15 min)
1. Review new bugs (5 min)
2. Assign owners (3 min)
3. Adjust priorities (3 min)
4. Review blockers (4 min)

### Triage Questions
- Is this a duplicate?
- Is it reproducible?
- What's the user impact?
- Is there a workaround?
- What's the fix complexity?
- Who should own this?

Bug Lifecycle

New → Triaged → In Progress → In Review → Verified → Closed
                    ↓
              Cannot Reproduce
                    ↓
              Need More Info
                    ↓
               Won't Fix
                    ↓
               Duplicate

Best Practices

1. One bug per report - Don't combine multiple issues
2. Search first - Check for duplicates before filing
3. Be objective - Describe facts, not frustrations
4. Include evidence - Screenshots, logs, videos
5. Stay updated - Respond to questions promptly
6. Verify fixes - Confirm the bug is actually fixed
7. Close the loop - Update status when resolved