# Bug

> Investigates and resolves bugs using structured diagnosis. Categorizes by system, traces root cause, proposes minimal fix, and suggests prevention. Use when debugging issues or investigating unexpected behavior.

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

## Install

```sh
agentstack add skill-pvnarp-agent-skills-bug
```

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

## About

# Bug Investigation

Don't guess. Trace systematically from symptom to root cause.

## Step 1: Characterize

Before touching code, establish the facts.

```
SYMPTOM:      [what's happening vs what should happen]
REPRODUCIBLE: [always / sometimes / once - steps to reproduce]
ENVIRONMENT:  [OS, runtime, build type, deploy target]
FIRST SEEN:   [when - correlate with recent deploys/changes]
IMPACT:       [who's affected, how badly, workaround exists?]
```

**If it's intermittent**, suspect: race conditions, resource exhaustion, timing-dependent logic, external service flakiness, or uninitialized state.

## Step 2: Categorize

Identify the bug's domain to narrow the search space:

| Category | Symptoms | Where to Look |
|----------|----------|---------------|
| **Input/Validation** | Wrong results from user actions, rejected valid input | Event handlers, validators, parsers, type coercion |
| **Logic/State** | Wrong computations, impossible states, inconsistent data | Business logic, state machines, conditionals, data flow |
| **Data** | Missing, corrupt, or stale data | Persistence layer, serialization, migrations, cache |
| **Network** | Timeouts, malformed payloads, intermittent failures | HTTP clients, retry logic, error handling, payload schemas |
| **Concurrency** | Intermittent corruption, deadlocks, lost updates | Shared state, locking, async/await, transaction isolation |
| **Lifecycle** | Crashes on start/stop, leaks, state loss across restarts | Init/cleanup order, resource management, persistence |
| **Integration** | External service misbehavior, version mismatches | API contracts, SDK versions, config, auth |

## Step 3: Isolate

Narrow the search:

1. **Binary search in time**: `git bisect` to find the commit that introduced it.
2. **Binary search in space**: Comment out / bypass components until the bug disappears. The last thing you re-enabled is the culprit.
3. **Minimal reproduction**: Strip away everything unrelated. Can you trigger it in a test? In a REPL?
4. **Read the error, really read it**: Stack traces, error codes, log messages. The answer is often in the output - read it carefully before jumping to hypotheses.

## Step 4: Trace Root Cause

Follow the data flow from trigger to symptom:

```
User action → [handler] → [service] → [data layer] → [external system]
                                           ↑
                                    Bug is HERE (root cause)
                                           ↓
                              Symptom appears downstream
```

**Common root causes:**
- Off-by-one in boundary logic
- Null/undefined where a value was assumed present
- Type coercion producing unexpected results
- Stale closure capturing old state
- Missing `await` / uncaught promise rejection
- Transaction not isolated (dirty read)
- Initialization order dependency
- Integer overflow / floating point precision

## Step 5: Fix

**Fix the root cause, not the symptom.**

- Minimal change - touch only what's necessary
- Verify the fix doesn't break related behavior (run full test suite)
- If the fix is non-obvious, add a comment explaining WHY (the commit message explains WHAT, the comment explains WHY)

## Step 6: Prevent

After fixing, harden against recurrence:

1. **Add a regression test** that fails without the fix and passes with it
2. **Check for similar bugs** - if this off-by-one exists here, does it exist in analogous code?
3. **Add a guard** - assertion, type constraint, or validation that would catch this class of bug earlier
4. **Improve observability** - would better logging or metrics have caught this sooner?

## Output

```
BUG: [concise description]
CATEGORY: [input / logic / data / network / concurrency / lifecycle / integration]
ROOT CAUSE: [what's actually wrong and why it produces the symptom]
FIX: [specific code change - file:line, what to change]
REGRESSION TEST: [test that catches this]
SIMILAR RISKS: [other places in the codebase with the same pattern]
PREVENTION: [guard, validation, or process change to prevent recurrence]
```

## Source & license

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

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