Skills

fix-bug

Installation
SKILL.md

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

# 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 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:

// 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

  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

#[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:

  1. Push the fix branch

    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
Related skills

More from diegosouzapw/awesome-omni-skill

Installs
5
Repository
diegosouzapw/aw…ni-skill
GitHub Stars
30
First Seen
Mar 17, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn