| 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 | ["pensive:shared","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
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
bug-review:language-detectedbug-review:repro-planbug-review:defects-documentedbug-review:fixes-preparedbug-review:verification-planbug-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:
- Write failing test
- Apply minimal fix
- 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 leaks | Validation gaps
Output Format
## Summary
[Brief scope description]
## Defects Found
### [D1] file.rs:142 - Title
- Severity: High
- Anchor: `verbatim source text at file.rs:142`
- Root Cause: Logic error
- Impact: Data corruption possible
- Fix: [description]
## Proposed Fixes
### Fix for D1
[code diff with explanation]
## Test Updates
[new/updated tests with Red → Green verification]
## Evidence
- Commands executed
- Logs and outputs
- External references
Verification: Run pytest -v to verify tests pass.
Best Practices
- Evidence-based: Every finding has file:line reference
- Reproducible: Clear steps to reproduce each bug
- Minimal fixes: Smallest change that fixes the issue
- Test coverage: Every fix has corresponding test
- Risk awareness: Document remaining risks with severity scoring
Exit Criteria
- All defects documented with precise references
- Every defect carries a
file:line + verbatim Anchor, and citation_verifier.py confirmed all citations (exit 0) or unverified defects were dropped or labeled UNVERIFIED
- Fixes prepared with test coverage verified
- Verification plan includes commands and expected outputs
- Remaining risks assessed and owners assigned
