Bug Review

Table of Contents

• Quick Start
• When to Use
• Required TodoWrite Items
• Progressive Loading
• Workflow
• Step 1: Detect Languages (`bug-review:language-detected`))
• Step 2: Plan Reproduction (`bug-review:repro-plan`))
• Step 3: Document Defects (`bug-review:defects-documented`))
• Step 4: Prepare Fixes (`bug-review:fixes-prepared`))
• Step 5: Verification Plan (`bug-review:verification-plan`))
• Defect Classification (Condensed))
• Output Format
• Summary
• Defects Found
• [[D1] file.rs:142 - Title](#[d1]-filers:142---title)
• Proposed Fixes
• Fix for D1
• Test Updates
• Evidence
• Best Practices
• 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 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

Defect Documentation

Systematic defect identification with precise file references and severity classification.

File/Line References

Every defect must include:

• File path: Absolute or relative from project root
• Line number: Exact location of issue
• Function/method: Containing scope
• Code snippet: 3-5 lines of context

Example:

src/parser/tokenizer.rs:142 in `parse_string()`

Severity Classification

Root Cause Categories

Logic Errors

• Incorrect conditions (off-by-one, wrong operator)
• Null/None handling gaps
• Missing validation
• Boundary condition failures

API Misuse

• Wrong parameter types/order
• Deprecated method usage
• Incorrect error handling
• Lifetime/ownership violations (Rust)

Concurrency Issues

• Race conditions
• Deadlocks
• Data races
• Improper synchronization
• Channel misuse (Go)

Resource Leaks

• Memory leaks
• File handle leaks
• Connection pool exhaustion
• Lock not released

Validation Gaps

• Missing input validation
• Insufficient boundary checks
• Type coercion errors
• Injection vulnerabilities

Static Analyzer Commands

Run language-specific linters:

Rust

cargo clippy --all-targets --all-features

Python

ruff check .
mypy src/

Go

golangci-lint run
staticcheck ./...

JavaScript/TypeScript

eslint .
tsc --noEmit

Java

./gradlew check
spotbugs

Documentation Format

### [D1] file.rs:142 - Null pointer dereference

- **Severity**: Critical
- **Root Cause**: Logic error - missing null check
- **Impact**: Crash on malformed input
- **Evidence**: Line 142 dereferences `config.value` without validation
- **Context**:

let value = config.value.unwrap(); // PANIC if None

Cross-References

When relevant, link to:

• CVE databases for security issues
• Language RFCs or proposals
• Standard library documentation
• Known issue trackers

Fix Preparation

Create minimal, idiomatic patches with detailed test coverage.

Minimal Patch Patterns

Apply smallest change that fixes the issue:

Guard Clause (prevent invalid state)

// Before: crash on None
let value = config.value.unwrap();

// After: guard clause
let Some(value) = config.value else {
    return Err(Error::MissingConfig);
};

Validation (check inputs)

# Before: no validation
def process(count: int):
    return items[:count]

# After: boundary check
def process(count: int):
    if count < 0 or count > len(items):
        raise ValueError(f"Invalid count: {count}")
    return items[:count]

Resource Cleanup (prevent leaks)

// Before: file handle leak
file, err := os.Open(path)
data, _ := io.ReadAll(file)

// After: defer cleanup
file, err := os.Open(path)
if err != nil {
    return err
}
defer file.Close()
data, err := io.ReadAll(file)

Idiomatic Fixes by Language

Rust

• Use ? operator for error propagation
• Prefer pattern matching over unwrap()
• Use Option::ok_or() for conversions
• Apply ownership transfer instead of cloning

// Idiomatic error handling
fn load_config() -> Result<Config, Error> {
    let path = env::var("CONFIG_PATH")
        .map_err(|_| Error::MissingEnv)?;
    let contents = fs::read_to_string(&path)?;
    toml::from_str(&contents)
        .map_err(Error::Parse)
}

Python

• Use context managers for resources
• Apply type hints for clarity
• Use specific exception types
• Prefer pathlib over string paths

# Idiomatic resource handling
from pathlib import Path
from contextlib import contextmanager

def load_config(path: Path) -> dict:
    if not path.exists():
        raise FileNotFoundError(f"Config not found: {path}")
    with path.open() as f:
        return json.load(f)

Go

• Check errors immediately
• Use defer for cleanup
• Apply early returns
• Wrap errors with context

// Idiomatic error handling
func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("reading config: %w", err)
    }

    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return nil, fmt.Errorf("parsing config: %w", err)
    }

    return &cfg, nil
}

TypeScript

• Use strict null checks
• Apply discriminated unions
• Prefer async/await over promises
• Use type guards for narrowing

// Idiomatic null handling
function processValue(value: string | null): Result {
    if (value === null) {
        throw new Error("Value required");
    }
    // TypeScript knows value is string here
    return { data: value.toLowerCase() };
}

Test Coverage Requirements

Every fix must include tests following Red → Green pattern:

1. Red: Write Failing Test

#[test]
fn test_config_missing_value() {
    let config = Config { value: None };
    // This should fail before fix
    assert!(process_config(&config).is_err());
}

2. Green: Apply Fix

Implement the minimal change to pass the test.

3. Verify: Run Test Suite

cargo test
pytest -v
go test ./...
npm test

Test Categories

Unit Tests: Test individual functions in isolation

def test_boundary_validation():
    with pytest.raises(ValueError):
        process(count=-1)

Integration Tests: Test component interactions

#[test]
fn test_config_loading_integration() {
    let cfg = load_config("test.toml").unwrap();
    assert_eq!(cfg.value, Some(42));
}

Regression Tests: Prevent bug recurrence

func TestNoPanicOnNilValue(t *testing.T) {
    // Regression test for issue #123
    result, err := Process(nil)
    require.Error(t, err)
    assert.Nil(t, result)
}

Explanation Requirements

For each fix, document: 1. What changed: Specific code modifications 2. Why it works: Mechanism that prevents the bug 3. Best practice: Link to language idioms or patterns 4. Trade-offs: Performance, complexity, or maintainability impact

Language Detection and Expertise Framing

Identify project languages and establish appropriate expertise context.

Manifest Heuristics

Use manifest files to detect primary languages:

Version Constraints

Extract and note version requirements:

Rust: Check MSRV (Minimum Supported Rust Version)

[package]
rust-version = "1.70.0"

Python: Check required version

[project]
requires-python = ">=3.8"

Node: Check engine constraints

"engines": {
  "node": ">=18.0.0"
}

Go: Check minimum version

go 1.21

Expertise Persona

Frame appropriate expertise based on detected languages:

Rust: "Staff engineer specializing in Rust systems programming with expertise in ownership, lifetimes, and async runtimes"

Python: "Senior Python developer with expertise in type systems, async patterns, and performance optimization"

Go: "Go engineer with deep understanding of concurrency, channels, and idiomatic error handling"

TypeScript: "TypeScript expert focused on type safety, React patterns, and async workflows"

State this persona explicitly to establish review context and credibility.