Generating Bug Reports

This skill standardizes bug report creation across all testing agents. Every discovered defect flows through this skill to ensure consistent, actionable, developer-friendly bug reports.

When to Use

• Any agent discovers a defect during testing
• You need to format findings for Jira, GitHub Issues, or similar trackers
• You're compiling a QA report with multiple findings
• You want to ensure reproduction steps are complete and unambiguous

Bug Report Structure

Every bug report MUST include these sections:

Required Fields

{
  "bug_id": "BUG-001",
  "title": "Short, specific summary (what + where)",
  "severity": "critical|high|medium|low|info",
  "type": "functional|visual|performance|security|ux|accessibility",
  "status": "new",
  "discovered_by": "agent-name",
  "discovered_at": "2025-01-15T10:30:00Z",

  "environment": {
    "url": "https://staging.example.com/checkout",
    "browser": "chromium 120",
    "viewport": "1440x900",
    "os": "Linux",
    "build": "staging-v2.3.1"
  },

  "description": "Full description of what's wrong and why it matters",

  "reproduction_steps": [
    "1. Navigate to /checkout",
    "2. Add item to cart",
    "3. Click 'Proceed to Payment'",
    "4. Leave the email field empty",
    "5. Click 'Submit Order'",
    "6. OBSERVE: Order submits successfully without email validation"
  ],

  "expected_behavior": "Form should show validation error on the email field",
  "actual_behavior": "Order submits with no email, confirmation page shows 'undefined'",

  "evidence": {
    "screenshots": ["screenshot-before.png", "screenshot-after.png"],
    "console_log": "TypeError: Cannot read property 'email' of undefined",
    "network_log": "POST /api/orders → 201 (should have been 400)",
    "har_file": "checkout-session.har"
  },

  "impact": "Users can place orders without email, breaking order confirmation flow",
  "suggested_fix": "Add server-side email validation in POST /api/orders endpoint"
}

Optional Fields

{
  "related_bugs": ["BUG-002", "BUG-005"],
  "affected_users": "All users on checkout flow",
  "frequency": "100% reproducible",
  "workaround": "Manually enter email before submitting",
  "regression": true,
  "regression_since": "v2.3.0",
  "jira_labels": ["checkout", "validation", "regression"],
  "assignee_suggestion": "backend-team"
}

Severity Classification

Use this guide consistently across all agents:

Critical — Application is unusable or data is at risk

• Authentication bypass or security vulnerability
• Data loss or corruption
• Application crashes or is completely non-functional
• Financial transaction errors (wrong charges, duplicate payments)

High — Major feature is broken with no workaround

• Core user journey cannot be completed
• Significant visual regression affecting usability
• Performance degradation >5x normal
• API returning incorrect data

Medium — Feature works but with notable issues

• Non-critical UI elements broken
• Error messages missing or unhelpful
• Moderate performance issues (2-5x normal)
• Cross-browser inconsistencies affecting UX

Low — Minor cosmetic or polish issues

• Slight visual misalignment (<5px)
• Minor typos in UI text
• Inconsistent spacing or styling
• Deprecated API warnings in console

Info — Observations, not defects

• Potential improvements
• Code quality observations
• Performance optimization opportunities
• Accessibility suggestions

Writing Good Bug Titles

The title should let a developer understand the issue at a glance:

Pattern: [Area] What happens + Where/When

Good examples:

• "Checkout: Order submits without email validation on payment form"
• "Dashboard: Chart data overlaps legend text at tablet viewport"
• "API: POST /users returns 500 when name exceeds 255 characters"
• "Login: Password field accepts paste but shows empty on Safari"

Bad examples:

• "Bug in checkout" (too vague)
• "Something wrong" (not descriptive)
• "Form doesn't work" (which form? what doesn't work?)

Writing Reproduction Steps

Reproduction steps should be precise enough that any developer can follow them:

1. Start from a known state — "Navigate to /checkout" not "Go to the page"
2. Be specific about inputs — "Enter 'test@example.com'" not "Enter an email"
3. One action per step — Don't combine "Click login and enter credentials"
4. Mark the observation point — "OBSERVE: ..." or "EXPECTED: ... / ACTUAL: ..."
5. Include timing if relevant — "Wait 5 seconds" or "Quickly click 3 times"

Using the Bug Report Generator

python skills/qa-generating-bug-reports/scripts/generate_report.py \
  --template standard \
  --output bugs/BUG-001.json \
  --screenshots screenshot1.png screenshot2.png

Or generate from agent session data:

python skills/qa-generating-bug-reports/scripts/from_session.py \
  --session session-log.json \
  --output bugs/ \
  --agent-name qa-e2e-exploratory-agent

Markdown Report Format

For human-readable reports (e.g., summary documents):

## BUG-001: Checkout order submits without email validation [HIGH]

**Environment:** Chromium 120 / Desktop (1440×900) / staging-v2.3.1
**Discovered:** 2025-01-15 by qa-e2e-exploratory-agent
**Reproducible:** 100%

### Description
When submitting the checkout form with an empty email field, the order
processes successfully. The confirmation page shows "undefined" where
the email should appear.

### Steps to Reproduce
1. Navigate to /checkout
2. Add any item to cart
3. Click 'Proceed to Payment'
4. Leave the email field empty
5. Click 'Submit Order'
6. **OBSERVE:** Order submits, confirmation shows 'undefined' for email

### Expected vs Actual
- **Expected:** Form validation prevents submission, shows error on email field
- **Actual:** Order submits, confirmation page displays "undefined"

### Evidence
- Screenshot: [before-submit.png] [after-submit.png]
- Console: `TypeError: Cannot read property 'email' of undefined`
- Network: `POST /api/orders → 201` (expected 400)

### Impact
All users can place orders without email, breaking confirmation emails
and order tracking.

Deduplication

Before creating a new bug report, check existing reports for duplicates:

1. Same URL + same error type = likely duplicate
2. Same console error message = likely duplicate
3. Same visual region affected = likely duplicate

If a duplicate is found, append the new evidence to the existing report rather than creating a new one. Add a duplicate_of field if merging.