Bug Reporting Excellence

Name: Bug Reporting Excellence
Author: proffesor-for-testing

proffesor-for-testing/agentic-qe

131 installs
433 repo stars
Updated August 4, 2026
proffesor-for-testing/agentic-qe

Write reproducible, high-signal bug reports with clear steps, environment context, expected vs actual behavior, and evidence for faster triage and fix cycles.

About

Bug-reporting-excellence teaches how to document defects with reproducible steps, environment details, expected vs actual results, and supporting evidence. It shortens triage cycles for SaaS, mobile, and agent products during ship-phase testing.

Templates for reproducible high-signal bug reports
Captures environment, steps, and evidence clearly
Separates expected vs actual behavior precisely
Speeds triage and developer fix turnaround
Elevates agentic QE defect communication standards

Bug Reporting Excellence by the numbers

131 all-time installs (skills.sh)
+4 installs in the week ending Aug 4, 2026 (Skillselion tracking)
Ranked #921 of 2,153 Testing & QA skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/proffesor-for-testing/agentic-qe --skill bug-reporting-excellence

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/proffesor-for-testing/agentic-qe/bug-reporting-excellence.svg)](https://skillselion.com/skills/proffesor-for-testing/agentic-qe/bug-reporting-excellence)

Installs	131
repo stars	★ 433
Last updated	August 4, 2026
Repository	proffesor-for-testing/agentic-qe ↗

What it does

Write reproducible, high-signal bug reports with clear steps, environment context, expected vs actual behavior, and evidence for faster triage and fix cycles.

Files

SKILL.mdMarkdownGitHub ↗

Bug Reporting Excellence

<default_to_action> When reporting bugs: 1. TITLE: [Component] fails [Condition] causing [Impact] 2. DESCRIBE: Expected behavior → Actual behavior → Steps to reproduce 3. INCLUDE: Environment, severity, screenshots/logs, business impact 4. ISOLATE: Narrow down conditions (browser, user, amount thresholds) 5. 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
1. Step one
2. Step two
3. 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
1. Add items totaling $1,050 to cart
2. Proceed to checkout
3. Enter payment: Visa 4532 1234 5678 9010
4. Click "Place Order"
5. Wait 30+ seconds
6. 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

Skill Composition

After finding bug → Start with /test-failure-investigator for root cause
Prevent regression → Use /regression-testing to add test preventing recurrence
Track quality → Feed into /test-metrics-dashboard for trend analysis

Gotchas

Agent omits environment details (OS, browser version, node version) — these are critical for reproduction
"Steps to reproduce" that start with "1. Open the app" are useless — specify exact URL, user role, and state
Agent combines multiple bugs into one report — enforce ONE BUG = ONE REPORT strictly
Screenshots without annotations don't help — always highlight the actual error area
Severity assessment is often wrong — agent marks everything as "critical" or everything as "low"

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentic-qe.dev/schemas/skills/bug-reporting-excellence/output.json",
  "title": "Bug Reporting Excellence Skill Output Schema",
  "description": "Schema for bug-reporting-excellence skill output. High-quality bug reports with reproduction steps and impact assessment.",
  "type": "object",
  "required": ["skillName", "version", "timestamp", "status", "trustTier", "output"],
  "properties": {
    "skillName": {
      "type": "string",
      "const": "bug-reporting-excellence"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "status": {
      "type": "string",
      "enum": ["success", "partial", "failed", "skipped"]
    },
    "trustTier": {
      "type": "integer",
      "const": 3
    },
    "output": {
      "type": "object",
      "required": ["summary", "bugReports", "reportQuality"],
      "properties": {
        "summary": {
          "type": "string",
          "minLength": 20,
          "maxLength": 2000
        },
        "bugReports": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/bugReport"
          },
          "minItems": 1,
          "maxItems": 100
        },
        "reportQuality": {
          "$ref": "#/$defs/reportQuality"
        },
        "severity": {
          "$ref": "#/$defs/severityBreakdown"
        },
        "recommendations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/recommendation"
          },
          "maxItems": 50
        },
        "impactAnalysis": {
          "$ref": "#/$defs/impactAnalysis"
        },
        "triageGuidance": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/triageGuidance"
          }
        },
        "metrics": {
          "$ref": "#/$defs/metrics"
        }
      }
    },
    "metadata": {
      "$ref": "#/$defs/metadata"
    },
    "validation": {
      "$ref": "#/$defs/validationResult"
    },
    "learning": {
      "$ref": "#/$defs/learningData"
    }
  },
  "$defs": {
    "bugReport": {
      "type": "object",
      "required": ["id", "title", "severity", "stepsToReproduce", "expectedBehavior", "actualBehavior"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^BUG-\\d{3,6}$"
        },
        "title": {
          "type": "string",
          "minLength": 15,
          "maxLength": 200,
          "description": "Clear, descriptive bug title"
        },
        "description": {
          "type": "string",
          "maxLength": 3000,
          "description": "Detailed bug description"
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low", "trivial"]
        },
        "priority": {
          "type": "string",
          "enum": ["urgent", "high", "medium", "low"]
        },
        "type": {
          "type": "string",
          "enum": ["functional", "performance", "security", "usability", "compatibility", "data", "regression"]
        },
        "stepsToReproduce": {
          "type": "array",
          "items": { "type": "string" },
          "minItems": 1,
          "maxItems": 20,
          "description": "Clear reproduction steps"
        },
        "expectedBehavior": {
          "type": "string",
          "minLength": 10,
          "maxLength": 1000
        },
        "actualBehavior": {
          "type": "string",
          "minLength": 10,
          "maxLength": 1000
        },
        "environment": {
          "$ref": "#/$defs/environment"
        },
        "attachments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/attachment"
          }
        },
        "reproducibility": {
          "type": "string",
          "enum": ["always", "sometimes", "rarely", "once"]
        },
        "affectedUsers": {
          "type": "string",
          "enum": ["all", "most", "some", "few"]
        },
        "workaround": {
          "type": "string",
          "maxLength": 1000
        },
        "rootCauseHypothesis": {
          "type": "string",
          "maxLength": 1000
        },
        "relatedBugs": {
          "type": "array",
          "items": { "type": "string" }
        },
        "qualityScore": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Bug report quality score"
        }
      }
    },
    "environment": {
      "type": "object",
      "properties": {
        "os": { "type": "string" },
        "osVersion": { "type": "string" },
        "browser": { "type": "string" },
        "browserVersion": { "type": "string" },
        "device": { "type": "string" },
        "appVersion": { "type": "string" },
        "buildNumber": { "type": "string" },
        "environment": { "type": "string", "enum": ["production", "staging", "development", "qa"] },
        "additionalInfo": { "type": "object" }
      }
    },
    "attachment": {
      "type": "object",
      "required": ["type", "description"],
      "properties": {
        "type": { "type": "string", "enum": ["screenshot", "video", "log", "har", "data", "code"] },
        "path": { "type": "string" },
        "description": { "type": "string" },
        "timestamp": { "type": "string", "format": "date-time" }
      }
    },
    "reportQuality": {
      "type": "object",
      "required": ["overallScore", "grade"],
      "properties": {
        "overallScore": { "type": "number", "minimum": 0, "maximum": 100 },
        "grade": { "type": "string", "pattern": "^[A-F][+-]?$" },
        "dimensions": {
          "type": "object",
          "properties": {
            "clarity": { "type": "number", "minimum": 0, "maximum": 100 },
            "completeness": { "type": "number", "minimum": 0, "maximum": 100 },
            "reproducibility": { "type": "number", "minimum": 0, "maximum": 100 },
            "evidence": { "type": "number", "minimum": 0, "maximum": 100 },
            "actionability": { "type": "number", "minimum": 0, "maximum": 100 }
          }
        }
      }
    },
    "severityBreakdown": {
      "type": "object",
      "properties": {
        "critical": { "type": "integer", "minimum": 0 },
        "high": { "type": "integer", "minimum": 0 },
        "medium": { "type": "integer", "minimum": 0 },
        "low": { "type": "integer", "minimum": 0 },
        "trivial": { "type": "integer", "minimum": 0 }
      }
    },
    "impactAnalysis": {
      "type": "object",
      "properties": {
        "businessImpact": { "type": "string", "enum": ["critical", "significant", "moderate", "minor"] },
        "userImpact": { "type": "string", "enum": ["blocking", "major", "minor", "cosmetic"] },
        "affectedFeatures": { "type": "array", "items": { "type": "string" } },
        "affectedUserSegments": { "type": "array", "items": { "type": "string" } },
        "estimatedAffectedUsers": { "type": "integer" }
      }
    },
    "triageGuidance": {
      "type": "object",
      "required": ["bugId", "recommendedPriority"],
      "properties": {
        "bugId": { "type": "string" },
        "recommendedPriority": { "type": "string", "enum": ["urgent", "high", "medium", "low"] },
        "suggestedAssignee": { "type": "string" },
        "suggestedLabels": { "type": "array", "items": { "type": "string" } },
        "rationale": { "type": "string" }
      }
    },
    "recommendation": {
      "type": "object",
      "required": ["id", "title", "priority"],
      "properties": {
        "id": { "type": "string", "pattern": "^REC-\\d{3,6}$" },
        "title": { "type": "string", "maxLength": 200 },
        "description": { "type": "string", "maxLength": 2000 },
        "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
        "category": { "type": "string", "enum": ["process", "documentation", "testing", "tooling"] }
      }
    },
    "metrics": {
      "type": "object",
      "properties": {
        "totalBugs": { "type": "integer", "minimum": 0 },
        "averageQualityScore": { "type": "number", "minimum": 0, "maximum": 100 },
        "bugsWithReproSteps": { "type": "integer", "minimum": 0 },
        "bugsWithEvidence": { "type": "integer", "minimum": 0 },
        "criticalBugs": { "type": "integer", "minimum": 0 }
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "executionTimeMs": { "type": "integer", "minimum": 0 },
        "toolsUsed": { "type": "array", "items": { "type": "string" } },
        "agentId": { "type": "string", "pattern": "^qe-[a-z][a-z0-9-]*$" },
        "sourcePlatform": { "type": "string" }
      }
    },
    "validationResult": {
      "type": "object",
      "properties": {
        "schemaValid": { "type": "boolean" },
        "contentValid": { "type": "boolean" },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
      }
    },
    "learningData": {
      "type": "object",
      "properties": {
        "patternsDetected": { "type": "array", "items": { "type": "string" } },
        "reward": { "type": "number", "minimum": 0, "maximum": 1 }
      }
    }
  }
}

{
  "skillName": "bug-reporting-excellence",
  "skillVersion": "1.0.0",
  "requiredTools": [
    "jq"
  ],
  "optionalTools": [],
  "schemaPath": "schemas/output.json",
  "requiredFields": [
    "skillName",
    "status",
    "output",
    "output.summary",
    "output.bugReports",
    "output.reportQuality"
  ],
  "requiredNonEmptyFields": [],
  "mustContainTerms": [
    "bug",
    "steps"
  ],
  "mustNotContainTerms": [
    "TODO",
    "FIXME"
  ],
  "enumValidations": {
    ".status": [
      "success",
      "partial",
      "failed",
      "skipped"
    ]
  }
}