/bug-review

name: bug-review
role: library
description: Hunts bugs with evidence trails. Use when investigating unexpected behavior or before merging code with potential hidden defects.
alwaysApply: false
category: code-review
tags:
- bugs
- defects
- debugging
- code-quality
- fixes
- verification
tools: []
usage_patterns:
- bug-hunting
- defect-documentation
- fix-preparation
- verification-planning
complexity: intermediate
model_hint: standard
estimated_tokens: 450
progressive_loading: true
dependencies:
- imbue:proof-of-work
- imbue:diff-analysis/modules/risk-assessment-framework
- imbue:review-core
- imbue:structured-output
modules:
- modules/defect-documentation.md
- modules/fix-preparation.md
- modules/language-detection.md

Table of Contents

• [Quick Start](#quick-start)
• [When to Use](#when-to-use)
• [Required TodoWrite Items](#required-todowrite-items)
• [Progressive Loading](#progressive-loading)
• [Workflow](#workflow)
• [Step 1: Detect Languages (`bug-review:language-detected`)](#step-1:-detect-languages-(bug-review:language-detected))
• [Step 2: Plan Reproduction (`bug-review:repro-plan`)](#step-2:-plan-reproduction-(bug-review:repro-plan))
• [Step 3: Document Defects (`bug-review:defects-documented`)](#step-3:-document-defects-(bug-review:defects-documented))
• [Step 4: Prepare Fixes (`bug-review:fixes-prepared`)](#step-4:-prepare-fixes-(bug-review:fixes-prepared))
• [Step 5: Verification Plan (`bug-review:verification-plan`)](#step-5:-verification-plan-(bug-review:verification-plan))
• [Defect Classification (Condensed)](#defect-classification-(condensed))
• [Output Format](#output-format)
• [Summary](#summary)
• [Defects Found](#defects-found)
• [[D1] file.rs:142 - Title](#[d1]-filers:142---title)
• [Proposed Fixes](#proposed-fixes)
• [Fix for D1](#fix-for-d1)
• [Test Updates](#test-updates)
• [Evidence](#evidence)
• [Best Practices](#best-practices)
• [Exit Criteria](#exit-criteria)

Bug Review Workflow

Systematic bug identification and fixing with language-specific expertise.

Quick Start

/bug-review

**Verification:** Run the command with `--help` flag to verify availability.

When To Use

• Reviewing code for potential bugs
• After receiving bug reports
• Before major releases
• During security audits
• Investigating production issues

When NOT To Use

• Test coverage audit - use test-review instead

Required TodoWrite Items

1. `bug-review:language-detected` 2. `bug-review:repro-plan` 3. `bug-review:defects-documented` 4. `bug-review:fixes-prepared` 5. `bug-review:verification-plan` 6. `bug-review:findings-verified`

Progressive Loading

Load additional context as needed:

• **Language Detection**: `@include modules/language-detection.md` - Manifest heuristics, expertise framing, version constraints
• **Defect Documentation**: `@include modules/defect-documentation.md` - Severity classification, root cause analysis, static analyzers
• **Fix Preparation**: `@include modules/fix-preparation.md` - Minimal patches, idiomatic patterns, test coverage

Workflow

Step 1: Detect Languages (`bug-review:language-detected`)

Identify dominant languages using manifest files (Cargo.toml → Rust, package.json → Node, etc.).

State expertise persona appropriate for the language ecosystem.

Note version constraints (MSRV, Python versions, Node engines).

**Progressive**: Load `modules/language-detection.md` for detailed manifest heuristics.

Step 2: Plan Reproduction (`bug-review:repro-plan`)

Identify reproduction methods:

• Unit/integration test suites
• Fuzzing tools
• Manual reproduction commands

Document exact commands:

cargo test -p core
pytest tests/test_api.py
npm test -- pkg

**Verification:** Run `pytest -v tests/test_api.py` to verify.

Capture blockers and propose mocks when dependencies unavailable.

Step 3: Document Defects (`bug-review:defects-documented`)

Review code line-by-line, logging each bug with:

• **File:line reference**: Precise location
• **Severity**: Critical, High, Medium, Low
• **Root cause**: Logic error, API misuse, concurrency, resource leak
• **Impact**: What breaks and how

Run static analyzers (`cargo clippy`, `ruff check`, `golangci-lint`, `eslint`).

Use `imbue:proof-of-work` for reproducible capture.

**Progressive**: Load `modules/defect-documentation.md` for classification details and analyzer commands.

Step 4: Prepare Fixes (`bug-review:fixes-prepared`)

Draft minimal, idiomatic patches using language best practices:

• Guard clauses (Rust: pattern matching, Python: early returns)
• Resource cleanup (Go: defer, Python: context managers)
• Error propagation (Rust: ?, Go: wrapped errors)

Create tests following Red → Green pattern: 1. Write failing test 2. Apply minimal fix 3. Verify test passes

**Progressive**: Load `modules/fix-preparation.md` for language-specific patterns and test strategies.

Step 5: Verification Plan (`bug-review:verification-plan`)

Execute reproduction steps with fixes applied.

Capture evidence:

• Test output logs
• Benchmark comparisons
• Coverage reports

Document remaining risks using `imbue:diff-analysis/modules/risk-assessment-framework`.

Assign owners and deadlines for follow-up items.

Step 6: Verify Findings Are Grounded (`bug-review:findings-verified`)

Every defect must cite a real `file:line` and a verbatim `Anchor`. Write findings to `.review/findings.json` and confirm each citation resolves:

python plugins/imbue/scripts/citation_verifier.py \
  --findings .review/findings.json --repo-root .

Drop or label `UNVERIFIED` any defect the verifier fails (exit `1`); only verified defects enter the report. See `Skill(imbue:review-core)` Step 5 for the protocol and `Skill(imbue:structured-output)` for the schema.

Defect Classification (Condensed)

**Severity**: Critical (crash/data loss) → High (broken features) → Medium (degraded UX) → Low (edge cases)

**Root Causes**: Logic errors | API misuse | Concurrency issues | Resource