# Bug Fix

> Investigate, reproduce, and safely fix a bug with regression protection. Composes context, diagnosis, architecture, code quality, and testing guardrails into a reproduce-first repair workflow. Use when the user says 'fix this bug', 'debug this', 'investigate this failure', 'patch this regression', 'repair this issue', or 'why is this broken'.

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

## Install

```sh
agentstack add skill-techygarg-lattice-bug-fix
```

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

## About

# Bug Fix

## Required Skills

Load these skills based on bug scope (see Steps 2 and 5 for when):

1. `framework:knowledge-priming` -- (always)
2. `framework:context-anchoring` -- (always)
3. `framework:learning-harvest` -- (always)
4. `framework:collaborative-judgment` -- (always)
5. `framework:clean-code` -- (always)
6. `framework:test-quality` -- (always)
7. `framework:architecture` -- (conditional)
8. `framework:domain-driven-design` -- (conditional)
9. `framework:secure-coding` -- (conditional)

## Workflow

### Step 1: Establish Bug Context

Start from failure, not proposed fix.

- Gather **observed behavior**, **expected behavior**, **reproduction path**, any evidence: failing test, error message, stack trace, log excerpt, request payload, recent change.
- Use `framework:learning-harvest` Load behavior. Focus hint: "bug investigation — focus: reliability, quality signals".
- Use `framework:context-anchoring` Document Discovery to check for existing context doc for affected feature/module.
  - **If found** → Load it (context-anchoring Load behavior). Honor logged decisions + constraints as active commitments while diagnosing.
  - **If not found** → Proceed from bug report + current code. Don't block diagnosis on missing context.

End this step, summarize bug one sentence:

> "Observed X, expected Y, reproducible via Z."

**STOP:** If can't state bug clearly yet, gather more evidence before proposing code changes.

### Step 2: Reproduce and Localize

**Primary discipline**: don't present fix for bug you haven't reproduced.

Reproduce failure using strongest evidence available, this order:

1. **Existing failing automated test** -- best case; use as regression guard
2. **New failing automated test** -- preferred when no test exists yet
3. **Executable reproduction path** -- command, request sequence, deterministic manual flow when automation not yet possible

Localize issue before editing:

- **Which layer likely source?** Use layer definitions from `framework:architecture` to identify which architectural layer defect originates in
- **Production bug or test bug?** Sometimes code correct, test/fixture wrong
- **Failure symptom or root cause?** Crashing line often downstream of real defect
- **Bug cross trust boundary?** If yes, plan load `framework:secure-coding`
- **Involve domain invariants or aggregate behavior?** If yes, plan load `framework:domain-driven-design`
- **Likely fix touch multiple layers or dependency flow?** If yes, plan load `framework:architecture`

If multiple plausible root causes remain, use `framework:collaborative-judgment` to present leading hypotheses + what evidence would distinguish.

Before writing regression test, state root cause hypothesis explicitly, use `framework:collaborative-judgment` to surface:

> "Bug caused by [X]. When [C holds], correct outcome should be [P].
>  Confirm this by writing test that red before fix, green after."

If user identifies flaw in hypothesis, revise before writing tests.

End step with explicit bug contract:

> **C (bug condition):** [exact input/state triggering bug]
> **P (fix postcondition):** [what correct behavior looks like when C holds]
> **Preserved:** [what must remain identical for all inputs outside C]

**STOP:** If can't state all three, keep localizing before writing tests.

**Optional persistence check**: Now that bug reproduced + localized, decide whether persist investigation:

- If investigation complex, involves multiple hypotheses, likely span multiple sessions, ask if user wants persist diagnosis + repair decisions
- If relevant context doc exists → plan enrich in Step 7
- If none exists + user wants persistence → propose creating one, confirm doc name per `framework:context-anchoring`, use as source of truth
- If user doesn't want persistence or bug narrow + local → continue non-persistent mode. Repair workflow still applies; decisions remain in-session

### Step 3: Add Regression Protection First

**Phase A — Bug-Condition Tests (must start RED)**

- Write smallest failing test that fires when C holds
- Prefer lowest-level test reproducing real failure without losing signal
- Name test for broken behavior, not implementation detail
- Assert correct expected outcome (postcondition P), not just absence of failure
- Apply `framework:test-quality` inline
- Run against unfixed code, confirm RED
  - If green before fix, bug condition hypothesis wrong — stop, re-localize

**Stopping rule**:

- **STOP:** If can't create stable failing automated test, explain why before making code changes.
- Record closest executable reproduction you have.
- Don't present speculative fix as "complete" without automated reproducer unless user explicitly accepts limitation.
- If bug can't be tested directly due to tight coupling/deep integration, introduce minimum structural seam needed to make testable (method extraction, parameter injection, interface boundary). Not refactor — prerequisite for regression protection. Apply `framework:clean-code` inline, keep seam minimal.

**Phase B — Preservation Baseline (must stay GREEN)**

- Identify existing tests covering behavior outside C
- If important adjacent behavior has no test coverage, add at most 2-3 targeted characterization tests
- Confirm all preservation baseline tests green before applying fix
- These tests must remain green through every change in Step 5 — any flip to red means fix has side effects; stop, narrow scope

### Step 4: Choose the Minimal Safe Fix

Separate **repair strategy** from code change itself.

Before editing, decide:

- What **root cause**?
- What **smallest safe change** correcting it?
- What layer **right repair location**?
- Does issue require **local patch** or **small structural correction**?

Default to smallest safe fix restoring correct behavior **without architectural backsliding**.

Guardrails:

- Apply `framework:architecture` layering rules when choosing repair location — don't patch in outer layer when rule belongs inward
- Don't widen task into unrelated cleanup
- Don't delete/weaken failing test just to make suite green
- If real fix requires contract/design change beyond narrow repair, stop, discuss scope explicitly
- Don't add guard clauses, null checks, defensive handling for inputs outside C — code path for correct inputs must be byte-for-byte identical before + after fix.

If multiple valid repair strategies with meaningful trade-offs, present using `framework:collaborative-judgment` before proceeding.

### Step 5: Implement the Fix

Always apply:

- `framework:clean-code` -- keep delta focused, readable, easy to reason about
- `framework:test-quality` -- maintain regression test + any nearby supporting tests

Conditionally apply based on localized root cause:

- **If fix changes layer responsibilities, dependency direction, architectural flow** → Apply `framework:architecture`
- **If fix changes domain behavior, invariants, aggregate boundaries, value objects** → Apply `framework:domain-driven-design`
- **If fix touches input validation, authorization, queries, external boundaries, sensitive data** → Apply `framework:secure-coding`

After implementing fix, before presenting:

1. Re-run regression test, confirm now green
2. Run applicable atom self-validation checklists against changed code
3. Run applicable anti-pattern scans
4. Fix any violations before presenting result

### Step 6: Verify Non-Regression

Verify repair three levels:

1. **Fix proof** -- regression test that was red before fix now green. Asserts correct outcome, not just absence of original failure.
2. **Preservation proof** -- tests covering behavior adjacent to bug still pass. If preservation baseline tests added in Step 3, must remain green. Any flip from green to red means fix has side effects — stop, narrow scope before continuing.
3. **Structural confidence** -- fix didn't introduce wrong-layer workaround, dependency violation, weakened security posture

When reporting completion, explicit about verification scope:

- What was re-run
- What now passes
- What not verified + why

If fix narrow + confidence high, say so briefly. If verification partial, say so clearly.

### Step 7: Capture Root Cause and Close the Loop

Use `framework:context-anchoring` Enrich behavior to preserve important parts of repair:

- Bug summary: observed vs expected behavior
- Root cause: what actually failed + where
- Repair decision: why this fix chosen over alternatives
- Protection added: regression test or executable reproducer now guarding behavior
- Key files changed: path + purpose

If no context doc exists + fix exposed non-trivial design/domain lesson, suggest creating one.

Use `framework:learning-harvest` Harvest behavior. Session context: "bug investigation — root cause diagnosis and repair". Synthesize and propose cross-cutting patterns from this session — root cause categories, failure modes likely to recur elsewhere, boundary condition gaps. User confirms what enters the document.

After fix complete, recommend `/review` when change:

- touches multiple layers
- changes security-sensitive code
- changes domain behavior
- introduces non-trivial structural correction

## Source & license

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

- **Author:** [techygarg](https://github.com/techygarg)
- **Source:** [techygarg/lattice](https://github.com/techygarg/lattice)
- **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-techygarg-lattice-bug-fix
- Seller: https://agentstack.voostack.com/s/techygarg
- 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%.