# Fix Bug

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-hellotern-sextant-fix-bug`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hellotern](https://agentstack.voostack.com/s/hellotern)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hellotern](https://github.com/hellotern)
- **Source:** https://github.com/hellotern/Sextant/tree/main/skills/fix-bug

## Install

```sh
agentstack add skill-hellotern-sextant-fix-bug
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

!../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:**
```python
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](https://github.com/hellotern)
- **Source:** [hellotern/Sextant](https://github.com/hellotern/Sextant)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hellotern-sextant-fix-bug
- Seller: https://agentstack.voostack.com/s/hellotern
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.