Fix Bug

!../principles/SKILL_BODY.md

!../tool-gitnexus/SKILL_BODY.md

---

Bug Fix Workflow

Disambiguating fix-bug vs modify-feature

> Use this skill when: the code should do X but does Y — you want to restore correct behavior. > Use modify-feature when: the code does X correctly — you want it to do Z instead (desired behavior changed). > > Quick test: "Did this ever work correctly, or was it always intended to work differently?" > → Yes, it used to work / should work → fix-bug (continue here). > → No, the requirement itself is changing → stop. Tell the user: "This looks like a behavior change rather than a bug fix — the modify-feature workflow is a better fit. You can say something like 'refactor/change how X works' to trigger the right workflow, or tell me to proceed anyway and I'll apply baseline rules only." Do not proceed unless the user explicitly says to proceed. > > Edge case: A feature never implemented but expected is a bug only if it was promised in an interface contract; otherwise stop and direct the user to sextant:add-feature.

Core Principle

When fixing bugs, make surgical modifications to the existing solution — do not start over with a rewrite.

---

Complete Execution Workflow

> Progress tracking: At the start of each step, output an updated progress block so the user always knows where you are. Use this format: > > `` > Bug Fix Progress > ✓ Step 1: Reproduce & Locate — > ✓ Step 2: Impact Assessment — Risk: > → Step 3: Minimal-Change Fix — in progress > ○ Step 4: Boundary Validation > ` > > Replace ○ with → for the current step, and ✓` once complete.

---

Step 1: Reproduce and Locate the Root Cause

Before making any changes, confirm:

• What is the specific manifestation of the bug? (Error message, abnormal behavior, data anomaly)
• What are the trigger conditions? (Specific input, timing, environment)
• Where is the root cause? (Don't fix the symptom — find the source)

Localization techniques:

• Starting from the error manifestation, trace the call chain upward to the earliest point of failure
• Distinguish between "where the bug is exposed" and "where the bug originates" — they are often not the same place
• Check whether implicit state assumptions have been violated (e.g., a variable expected to be non-null is actually null)
• Pay attention to boundary conditions: null values, zero values, overflow, concurrency races, type mismatches

🔗 When GitNexus is available, use context / trace MCP tools for enhanced root-cause tracing.

Step 2: Impact Assessment

After locating the root cause, assess the potential impact of the fix:

• Which callers does this function/method have? Will their behavior change after the fix?
• Does the bug location involve a public interface? Will the fix change the interface contract?
• Is there other code that depends on the bug's behavior? (Sometimes bugs have existed so long that other code has adapted to the erroneous behavior)

🔗 When GitNexus is available, use impact MCP tool to enumerate callers automatically.

─── Bug Impact Assessment ───────────────────────────
Bug location: 
Root cause: 
Number of callers: 
Involves public interface: Yes / No
Possible code depending on buggy behavior: Yes (explanation) / No
Fix impact scope: Internal only / Affects callers / Cross-module
Risk level: Low / Medium / High
─────────────────────────────────────────────────────

When risk level is "High" (involves public interface or cross-module), you MUST inform the user of the impact scope and confirm before fixing.

---

Confirmation Gate (between Step 2 and Step 3)

After completing the Impact Assessment, before writing any code, use the confirmation gate with:

• question: A concise Proposed Fix Plan (see format below)
• options:
• "Yes, apply the fix"
• "No — let's discuss a different approach"

Proposed Fix Plan format:

Root cause   : 
What changes : 
Callers affected : 
Risk         :  — 

Decision rules by risk level:

| Risk | Behavior | |------|----------| | High | Always use the confirmation gate. Do not touch any file until user selects "Yes". | | Medium | Always use the confirmation gate. Do not touch any file until user selects "Yes". | | Low | Use the confirmation gate with an additional option "Yes, and skip confirmations for low-risk fixes in this session". If the user selected that option earlier in the current conversation, proceed directly without using the confirmation gate for subsequent low-risk fixes — this preference is session-scoped only. |

If user selects "No": ask "What direction would you prefer?", incorporate their feedback, update the Proposed Fix Plan, and use the confirmation gate again before proceeding.

---

Step 3: Minimal-Change Fix

Execution discipline:

• Only change the part of code that causes the bug — do not expand the scope of changes
• Maintain style consistency: The fix code is fully consistent with surrounding code style (naming, indentation, comment language)
• Annotate changes: Comments explaining the fix reason, format: # fix:
• No hitchhiking: Don't "optimize" unrelated code while fixing a bug — this introduces new regression risk

✅ Correct fix approach:

def calculate_discount(price, rate):
    # fix: rate = 0 causes division by zero; added boundary check
    if rate "}` to the top-level `flags` array. Do not proceed to the next task while a task is blocked.

Do not write the file without explicit user confirmation. If the user declines, continue without state updates.

---

## Reply Format

**Lightweight task** (single function, `:  —  (:).

or if something needs attention:

⚠️ Fixed ``:  — . Note: .

Medium/large task (cross-file, public interface, or high-risk): full block.

Fix Summary:

| # | Item | Detail | |---|------|--------| | [1] | Conclusion | | | [2] | Changes | | | [3] | Risks / Assumptions | | | [4] | Verification | | | [5] | Needs your input | |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hellotern
• Source: hellotern/Sextant
• License: MIT

Install and usage instructions live in the source repository linked above.