bug-reporting-excellence

Bug Reporting Excellence

<default_to_action> When reporting bugs:

TITLE: [Component] fails [Condition] causing [Impact]
DESCRIBE: Expected behavior → Actual behavior → Steps to reproduce
INCLUDE: Environment, severity, screenshots/logs, business impact
ISOLATE: Narrow down conditions (browser, user, amount thresholds)
ONE BUG = ONE REPORT (don't combine issues)

Bug Report Formula:

[Component] Issue Title

Severity: Critical/High/Medium/Low Environment: Production/Staging/Dev

Expected Behavior

What should happen

Actual Behavior

What actually happens (with error messages)

Steps to Reproduce

Step one
Step two
Observe issue

Impact

How this affects users/business

Critical Success Factors:

Reproducible steps (100%)
Environment info (100%)
Business impact stated (90%)
Screenshots or logs (80%) </default_to_action>

Quick Reference Card

Severity Levels

Level Definition Examples

Critical System down, data loss, security DB deleted, payments broken, credentials exposed

High Major feature broken, many users Can't checkout, search broken, dashboard fails

Medium Partial break, workaround exists Filter broken (refresh works), slow export

Low Cosmetic, rare edge case Button wraps on mobile, tooltip wrong color

Title Formula

❌ Bad: "Checkout broken" ✅ Good: "Payment fails with Visa cards when order total > $1000"

Pattern: [Component] fails [Condition] causing [Impact]

Essential Information

Environment Details

Browser: Chrome 120.0.6099.109 (Windows) OS: Windows 11 Pro URL: https://example.com/checkout Date/Time: 2025-10-17 14:23 UTC User: test@example.com (ID: 12345) Request ID: abc-123-def-456

Supporting Evidence

Error Messages:

{ "error": "Payment service unavailable", "code": "GATEWAY_TIMEOUT", "requestId": "abc-123-def-456" }

Console Logs:

[ERROR] PaymentGateway: Connection timeout after 30000ms at PaymentGateway.charge (gateway.js:145)

Example: Excellent Bug Report

[Checkout] Payment processing times out for orders > $1000

Severity: High Environment: Production Affected Users: ~15% of premium purchases

Expected Behavior

Payment completes within 5 seconds regardless of amount.

Actual Behavior

For orders above $1000, payment gateway times out after 30 seconds. User sees "Payment failed" error. Order not created.

Steps to Reproduce

Add items totaling $1,050 to cart
Proceed to checkout
Enter payment: Visa 4532 1234 5678 9010
Click "Place Order"
Wait 30+ seconds
Observe timeout error

Environment

Browser: Chrome 120 (Windows 11)
User: test@example.com
Request ID: abc-123-def-456

Evidence

Console error: PaymentGateway timeout: 30000ms exceeded Network: /api/checkout: 30.14s (timeout)

Impact

Lost revenue: ~$15K/week from failed orders
23 support tickets this week
Affects 15% of orders over $1000

Additional Context

Started after Oct 15 deployment (v2.3.0) Possibly related to PR #456 (fraud check)

Anti-Patterns

❌ Bad Problem ✅ Good

"Checkout is broken" What doesn't work? "Payment button doesn't respond when clicked"

"I saw an error" No reproduction steps Full steps with conditions

"Page loads slowly" No specifics "Dashboard takes 12s to load (should be <3s)"

Multiple bugs in one Can't track separately One report per bug

Agent Integration

// Automated bug triage const triage = await Task("Triage Bug", { title: 'Payment fails for orders > $1000', description: bugDescription, steps: reproductionSteps }, "qe-quality-analyzer");

// Returns: { severity, priority, component, suggestedAssignee, relatedIssues }

// Duplicate detection const dupeCheck = await Task("Check Duplicates", { bugReport: newBug, similarityThreshold: 0.85 }, "qe-quality-analyzer");

// Bug report enhancement const enhanced = await Task("Enhance Report", { originalReport: userSubmittedBug, addMissingInfo: true, identifyRootCause: true }, "qe-production-intelligence");

Agent Coordination Hints

Memory Namespace

aqe/bug-reports/ ├── triaged/* - Bug triage results ├── duplicates/* - Duplicate detection ├── patterns/* - Recurring bug patterns └── root-cause/* - Root cause analyses

Fleet Coordination

const bugFleet = await FleetManager.coordinate({ strategy: 'bug-investigation', agents: [ 'qe-quality-analyzer', // Triage and categorize 'qe-flaky-test-hunter', // Check if test-related 'qe-production-intelligence' // Check production logs ], topology: 'parallel' });

Related Skills

technical-writing - Clear bug documentation
exploratory-testing-advanced - Finding bugs
sherlock-review - Root cause investigation

Remember

Your bug report is the starting point for someone else's work. Make it complete (all info needed), clear (anyone can follow), concise (no noise), and actionable (developer knows next step).

Good bug reports = Faster fixes = Better product = Happier users