bug-report-processor skill
Automates bug report processing and systematic debugging using a structured Detective Methodology to track the entire resolution lifecycle.
- GitHub stars
- 5
- Files
- 12
- Last commit
- Jan 26, 2026
- License
- MIT
- Allowed tools
- 8
What does the bug-report-processor skill do?
bug-report-processor automates bug report processing and systematic debugging using a structured Detective Methodology to track the entire resolution lifecycle.
Summary generated from the skill's SKILL.md.
About the bug-report-processor skill
Transforming markdown bug reports into structured debugging workflows is what this skill enables for developers. It automates the transition from raw ticket data exported from systems like GitHub, Linear, or Bugzilla into organized JSON state files. By using a specific Detective Methodology, the tool ensures that every issue moves through mandatory phases including reproduction, investigation, root cause analysis, and regression testing.
An agent should load this skill when a user provides a markdown file containing error logs, stack traces, or reproduction steps. The system utilizes Python, the uv package manager, and tesseract-ocr to extract information from text and screenshots. It can also integrate with selenium or playwright to automate UI reproduction. The process produces detailed state files in a local directory that track the entire lifecycle of a bug from its initial report to final closure after successful regression tests.
What an agent can do with it
- 1Parse exported bug reportsConvert markdown files from various ticketing systems into structured JSON data for tracking.
- 2Analyze error logs and stack tracesExtract and interpret error patterns from Python, JavaScript, Java, or C# stack traces.
- 3Automate the debugging lifecycleFollow a strict sequence of phases to ensure bugs are properly diagnosed and verified.
- 4Perform OCR on error screenshotsRead text from error message images to assist in the investigation process.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the bug-report-processor skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the bug-report-processor skill in Claude Code
~/.claude/skills/bug-report-processor/SKILL.md
$ npx degit bowen31337/bug-report-agent-skills ~/.claude/skills/bug-report-processorInstall the bug-report-processor skill in Claude Code (project)
.claude/skills/bug-report-processor/SKILL.md
$ npx degit bowen31337/bug-report-agent-skills .claude/skills/bug-report-processorInstall the bug-report-processor skill in Codex
~/.agents/skills/bug-report-processor/SKILL.md
$ npx degit bowen31337/bug-report-agent-skills ~/.agents/skills/bug-report-processorInstall the bug-report-processor skill in Gemini CLI
~/.gemini/skills/bug-report-processor/SKILL.md
$ npx degit bowen31337/bug-report-agent-skills ~/.gemini/skills/bug-report-processorInstall the bug-report-processor skill in Claude.ai
npx degit bowen31337/bug-report-agent-skills bug-report-processor && zip -r bug-report-processor.zip bug-report-processor # claude.ai → Customize → Skills → + → Create skill → Upload a skill → bug-report-processor.zip
SKILL.md
View on GitHubBug 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
.mdfile 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
| Phase | Entry Requirement | Exit Requirement |
|---|---|---|
| reproduce | Bug report parsed | Bug reproduced OR marked needs-info |
| investigate | Bug reproduced | Hypotheses documented |
| diagnose | Investigation complete | Root cause identified |
| fix | Root cause documented | Fix implemented |
| verify | Fix implemented | Original bug no longer occurs |
| regression_test | Fix verified | All related tests pass |
| closed | Regression tests pass | Resolution 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
| Level | Criteria | Response Time |
|---|---|---|
| critical | System crash, data loss, security vulnerability | Immediate |
| high | Major feature broken, significant user impact | < 4 hours |
| medium | Feature degraded, workaround exists | < 24 hours |
| low | Minor issue, cosmetic | Next sprint |
| trivial | Typo, minor UI polish | Backlog |
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:
| Language | Error Pattern | Example |
|---|---|---|
| Python | Traceback (most recent call last): |
File "app.py", line 10, in main |
| JavaScript | Error: or TypeError: |
at functionName (file.js:10:5) |
| Java | Exception in thread |
at 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 reportsparse_markdown.py- Markdown parser with format detectionparse_stack_trace.py- Multi-language stack trace analyzerscreenshot_ocr.py- OCR text extraction from screenshotsstate_manager.py- JSON state file CRUD operationsreproduce_bug.py- Automated reproduction attemptsverify_fix.py- Fix verification runnerregression_tester.py- Regression test executordetective_engine.py- Workflow orchestratorseverity_analyzer.py- Severity/priority assessment
references/
BUG_STRUCTURE.md- Expected markdown formats for each ticket systemJSON_SCHEMA.md- Complete state file schema documentationDETECTIVE_METHOD.md- Detective Methodology guideSTACK_TRACE_FORMATS.md- Supported stack trace formatsSEVERITY_GUIDE.md- Severity classification criteria
config/
field_mappings.yaml- Default field name mappingsgithub.yaml- GitHub Issues format configurationlinear.yaml- Linear format configurationbugzilla.yaml- Bugzilla format configurationcustom.yaml.template- Template for custom formats
assets/
templates/bug_state_template.json- Initial state file templatetemplates/investigation_template.md- Investigation notes templateexamples/- Sample bug reports in various formats
Files in this skill
12bug-report-processor skill questions
How do I install the bug-report-processor skill in Claude Code?
Run npx degit bowen31337/bug-report-agent-skills ~/.claude/skills/bug-report-processor. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the bug-report-processor skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What ticket systems can this skill process?
It can process markdown bug reports exported from various systems including Linear, GitHub Issues, and Bugzilla.
What is the Detective Methodology workflow?
The workflow follows a strict sequence: Bug Queue, Reproduce, Investigate, Diagnose, Fix, Verify, Regression Test, and Close.
Which programming languages' stack traces are supported?
The tool supports parsing stack traces for Python, JavaScript, Java, and C#.