# Fix Bug

> Implement bug fixes for Rust code. Use when improvements, issues, GitHub Issue links, or error messages are provided. Triggers on keywords like "fix", "bug", "issue", "error", "broken". Use when this capability is needed.

- Skill: `tomevault-io/fix-bug-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/fix-bug-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/fix-bug-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/fix-bug-4

---


# Bug Fix Workflow

A systematic workflow for implementing bug fixes.

## Phase 1: Understand the Bug

### Issue/Error Analysis
1. **GitHub Issue**: Fetch details from issue number
   - Check reproduction steps, expected vs actual behavior
   - Review labels, milestones, linked PRs

2. **Error Message**: Parse the stack trace
   - Identify error type (panic, Result::Err, compile error)
   - Locate occurrence point (file:line)

3. **Description Only**: Gather additional information
   - Confirm reproduction steps
   - Check environment (OS, Rust version, DB type)

## Phase 2: Explore the Code

### Find Related Code
```
Exploration order:
1. File where error occurs
2. Callers (upstream)
3. Related test files
4. Related code in the same module
```

### Project Structure
- `src/cli/`: CLI command handling
- `src/core/`: Domain models (schema, migration)
- `src/db/`: Database adapters, SQL generation

## Phase 3: Diagnose Root Cause

### Root Cause Analysis
1. **Form hypothesis**: "This bug might be caused by X"
2. **Verify hypothesis**: Read code, confirm with tests
3. **Identify cause**: Create minimal reproduction case

### Debugging Techniques
```bash
# Run with stack trace
RUST_BACKTRACE=1 cargo run -- <command>

# Run specific test
cargo test <test_name> -- --nocapture

# Inspect variable values (temporary)
dbg!(variable);
```

## Phase 4: Create Fix Branch

### Branch Creation (Before Making Changes)
```bash
# Create and switch to fix branch
git checkout -b fix/<issue-number>-<short-description>

# Example
git checkout -b fix/10-sqlite-nested-transaction
```

### Branch Naming Convention
- `fix/<issue-number>-<short-description>` - For issue-based fixes
- `fix/<short-description>` - For fixes without issue number

## Phase 5: Implement the Fix

### Coding Conventions
- **Error handling**: No `unwrap()`/`expect()`, propagate with `?`
- **Ownership**: Prefer borrowing over unnecessary `.clone()`
- **Naming**: snake_case (functions), PascalCase (types)

### Fix Scope
- Minimal changes to solve the problem
- Avoid unrelated refactoring
- Consider API breaking changes carefully

### Fix Patterns

**Panic Fix**:
```rust
// Before: Potential panic
let value = map.get(key).unwrap();

// After: Proper error handling
let value = map.get(key)
    .ok_or_else(|| anyhow::anyhow!("Key not found: {}", key))?;
```

**Logic Error Fix**:
```rust
// Before: Missing boundary condition
if items.len() > 0 { ... }

// After: Handle empty case
if !items.is_empty() { ... }
```

## Phase 6: Write Tests

### Add Regression Tests
1. **Write a test that reproduces the bug first** (Red)
2. **Confirm the test fails**
3. **Implement the fix** (Green)
4. **Confirm the test passes**

### Test Location
- Unit tests: `#[cfg(test)]` module in the same file
- Integration tests: `src/cli/tests/` directory

### Test Naming Convention
```rust
#[test]
fn test_<feature>_<condition>_<expected_result>() {
    // e.g., test_parse_array_type_with_mixed_case_preserves_casing
}
```

## Phase 7: Verify

### Local Verification
```bash
# Format
cargo fmt

# Lint
cargo clippy -- -D warnings

# Run all tests
cargo test

# Run specific test file
cargo test --test <test_file_name>
```

### Pre-Commit Checklist
- [ ] Bug is fixed and verified
- [ ] Regression test is added
- [ ] All existing tests pass
- [ ] No errors from `cargo fmt` / `cargo clippy`
- [ ] Commit message is appropriate

## Commit Message Format

```
fix(<scope>): <summary>

<body - optional>

Fixes #<issue-number>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```

**Scope examples**: cli, core, db, schema, migration, sql, test

## Phase 8: Create Pull Request

### Push Branch and Create PR via MCP

After verification passes, create a pull request using GitHub MCP tools:

1. **Push the fix branch**
   ```bash
   git push -u origin <branch-name>
   ```

2. **Create PR using MCP** (`mcp__github__create_pull_request`)

### PR Content

Read the PR template from `.github/pull_request_template.md` and fill in the sections accordingly:
- **Summary**: Brief description of the fix
- **Related Issue**: `Fixes #<issue-number>`
- **Type of Change**: Check "Bug fix"
- **Test Plan**: Check items based on what was tested
- **Checklist**: Check completed items

### MCP Tool Parameters
```
owner: Lazialize
repo: stratum
title: fix(<scope>): <summary>
head: <fix-branch-name>
base: main
body: <PR content from template>
```

## GitHub Issue Integration

When issue number is provided:
1. Fetch issue details with `gh issue view <number>`
2. Include `Fixes #<number>` in commit message after fix
3. Link to issue when creating PR

## Escape Hatches

Stop and confirm with user in these cases:
- Breaking API changes required
- Multiple fix approaches possible
- Cannot identify root cause
- Security-related issues

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/lazialize) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->