Skip to content

bowen31337/bug-report-agent-skills

bug-report-processor

Verified

Processes bug reports from markdown files exported from any ticket system (Linear, GitHub Issues, Bugzilla, etc.), extracts reproduction steps, error logs, and environment details. Manages debugging workflow through Detective Methodology including reproduction, investigation, root cause analysis, fix verification, and regression testing. Use when handling bug reports, debugging issues, or tracking bug resolution.

Bug Report Processor

Overview

This skill automates bug report processing and systematic debugging through the Detective Methodology. It transforms markdown bug reports into structured JSON state files that track the entire resolution lifecycle.

Core capabilities:

  • Parse bug reports from any ticket system (Linear, GitHub, Bugzilla, etc.)
  • Extract and analyze stack traces (Python, JavaScript, Java, C#)
  • OCR screenshots for error messages
  • Track investigation notes and root cause analysis
  • Automate reproduction verification
  • Execute regression tests before closure

Activation Triggers

Activate this skill when:

  • User says "process bug report", "analyze error log", "reproduce this bug"
  • User says "investigate issue", "debug problem", "start detective workflow"
  • User provides a .md file containing bug report structure
  • User mentions stack traces or error logs needing analysis

Detective Methodology

The core workflow enforces systematic bug resolution. Phases cannot be skipped.

Bug Queue (by severity) → Reproduce → Investigate → Diagnose → Fix → Verify → Regression Test → Close

Phase Requirements

PhaseEntry RequirementExit Requirement
reproduceBug report parsedBug reproduced OR marked needs-info
investigateBug reproducedHypotheses documented
diagnoseInvestigation completeRoot cause identified
fixRoot cause documentedFix implemented
verifyFix implementedOriginal bug no longer occurs
regression_testFix verifiedAll related tests pass
closedRegression tests passResolution documented

Quick Start

Process a New Bug Report

uv run scripts/process_bug.py path/to/bug-report.md

This parses the bug report, extracts all structured data, and creates a JSON state file at .bug-states/<bug-id>.json in your current project directory.

Check Bug Status

uv run scripts/process_bug.py --status <bug-id>

Start Detective Workflow

uv run scripts/detective_engine.py --directory ./bugs

Processes bugs in severity order (critical → high → medium → low).

CLI Commands

# Process bug report (auto-detect format)
uv run scripts/process_bug.py <bug.md>
uv run scripts/process_bug.py <bug.md> --format github

# Update investigation
uv run scripts/state_manager.py <bug-id> --note "Found null pointer in form handler"
uv run scripts/state_manager.py <bug-id> --hypothesis "Form ID mismatch after v2.1 deploy"
uv run scripts/state_manager.py <bug-id> --root-cause "Commit abc123 changed form ID"

# Reproduction and verification
uv run scripts/reproduce_bug.py <bug-id>
uv run scripts/verify_fix.py <bug-id>

# Regression testing
uv run scripts/regression_tester.py <bug-id>

# Severity analysis
uv run scripts/severity_analyzer.py <bug.md>

# Detective mode (auto-progression)
uv run scripts/detective_engine.py --directory ./bugs --auto

Bug Report Formats

The skill supports multiple ticket system formats. Format is auto-detected or can be specified with --format.

GitHub Issues Format

# Bug: Title here

**Labels**: bug, priority
**Assignee**: @developer

## Description
What's happening

## Steps to Reproduce
1. Step one
2. Step two

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: Windows 11
- Browser: Chrome 120

## Error Logs

Stack trace here

Linear Format

# BUG-123 - Title

**Status**: In Progress
**Priority**: Urgent

## Problem
Description

## Reproduction Steps
1. Step one
2. Step two

## Stack Trace
```js
Error here

Custom formats can be configured via `config/custom.yaml`.

## JSON State Schema

Each bug generates a state file tracking all workflow data:

```json
{
  "bug_id": "BUG-456",
  "title": "Login button not responding",
  "type": "bug",
  "severity": "high",
  "priority": "urgent",
  "status": "investigating",
  "reproduction": {
    "steps": ["Step 1", "Step 2"],
    "status": "reproduced",
    "evidence": {}
  },
  "error_analysis": {
    "error_type": "TypeError",
    "stack_trace": [],
    "likely_cause": ""
  },
  "investigation": {
    "hypothesis": [],
    "root_cause": null,
    "notes": []
  },
  "fix": {
    "status": "pending",
    "commits": [],
    "verification": {}
  },
  "regression_testing": {
    "status": "pending",
    "test_suites": []
  },
  "detective_state": {
    "current_phase": "investigating",
    "phases_completed": ["reproduce"]
  }
}

See references/JSON_SCHEMA.md for complete schema documentation.

Severity Classification

LevelCriteriaResponse Time
criticalSystem crash, data loss, security vulnerabilityImmediate
highMajor feature broken, significant user impact< 4 hours
mediumFeature degraded, workaround exists< 24 hours
lowMinor issue, cosmeticNext sprint
trivialTypo, minor UI polishBacklog

The severity analyzer (scripts/severity_analyzer.py) automatically classifies based on:

  • Error type (crash, exception, validation)
  • Impact keywords (data loss, security, cannot, broken)
  • Affected user count
  • Regression flag

Stack Trace Support

Supported languages for stack trace parsing:

LanguageError PatternExample
PythonTraceback (most recent call last):File "app.py", line 10, in main
JavaScriptError: or TypeError:at functionName (file.js:10:5)
JavaException in threadat com.example.Class.method(File.java:10)
C#Unhandled Exception:at Namespace.Class.Method() in File.cs:line 10

Resources

scripts/

Core Python modules for bug processing:

  • process_bug.py - Main entry point, parses bug reports
  • parse_markdown.py - Markdown parser with format detection
  • parse_stack_trace.py - Multi-language stack trace analyzer
  • screenshot_ocr.py - OCR text extraction from screenshots
  • state_manager.py - JSON state file CRUD operations
  • reproduce_bug.py - Automated reproduction attempts
  • verify_fix.py - Fix verification runner
  • regression_tester.py - Regression test executor
  • detective_engine.py - Workflow orchestrator
  • severity_analyzer.py - Severity/priority assessment

references/

  • BUG_STRUCTURE.md - Expected markdown formats for each ticket system
  • JSON_SCHEMA.md - Complete state file schema documentation
  • DETECTIVE_METHOD.md - Detective Methodology guide
  • STACK_TRACE_FORMATS.md - Supported stack trace formats
  • SEVERITY_GUIDE.md - Severity classification criteria

config/

  • field_mappings.yaml - Default field name mappings
  • github.yaml - GitHub Issues format configuration
  • linear.yaml - Linear format configuration
  • bugzilla.yaml - Bugzilla format configuration
  • custom.yaml.template - Template for custom formats

assets/

  • templates/bug_state_template.json - Initial state file template
  • templates/investigation_template.md - Investigation notes template
  • examples/ - Sample bug reports in various formats
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall