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)

Write defects to .review/findings.json, run the citation verifier (Skill(imbue:review-core) Step 5), and drop or label UNVERIFIED any the verifier rejects.

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

1. Evidence-based: Every finding has file:line reference
2. Reproducible: Clear steps to reproduce each bug
3. Minimal fixes: Smallest change that fixes the issue
4. Test coverage: Every fix has corresponding test
5. 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