tomevault-io Bug Fix Workflow
A systematic workflow for implementing bug fixes.
Phase 1: Understand the Bug
Issue/Error Analysis
GitHub Issue: Fetch details from issue number
- Check reproduction steps, expected vs actual behavior
- Review labels, milestones, linked PRs
Error Message: Parse the stack trace
- Identify error type (panic, Result::Err, compile error)
- Locate occurrence point (file:line)
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 handlingsrc/core/: Domain models (schema, migration)src/db/: Database adapters, SQL generation
Phase 3: Diagnose Root Cause
Root Cause Analysis
- Form hypothesis: "This bug might be caused by X"
- Verify hypothesis: Read code, confirm with tests
- Identify cause: Create minimal reproduction case
Debugging Techniques
# 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)
# 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 fixesfix/<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:
// 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:
// Before: Missing boundary condition
if items.len() > 0 { ... }
// After: Handle empty case
if !items.is_empty() { ... }
Phase 6: Write Tests
Add Regression Tests
- Write a test that reproduces the bug first (Red)
- Confirm the test fails
- Implement the fix (Green)
- Confirm the test passes
Test Location
- Unit tests:
#[cfg(test)]module in the same file - Integration tests:
src/cli/tests/directory
Test Naming Convention
#[test]
fn test_<feature>_<condition>_<expected_result>() {
// e.g., test_parse_array_type_with_mixed_case_preserves_casing
}
Phase 7: Verify
Local Verification
# 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:
Push the fix branch
git push -u origin <branch-name>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:
- Fetch issue details with
gh issue view <number> - Include
Fixes #<number>in commit message after fix - 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 — claim your Tome and manage your conversions.