# Debugging

> >-

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

## Install

```sh
agentstack add skill-iliaal-whetstone-debugging
```

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

## About

# Debugging

## The Iron Law

Never propose a fix without first identifying the root cause. "Quick fix now, investigate later" is forbidden — it creates harder bugs.

## Process

**1. Reproduce** — make the bug consistent. If intermittent, run N times under stress or simulate poor conditions (slow network, low memory) until it triggers reliably.

**2. Investigate** — trace backward through the call chain from the symptom. Add diagnostic logging at each component boundary. Compare working vs broken state using a differential table (environment, version, data, timing — what changed?).

**3. Hypothesize and test** — one change at a time. If a hypothesis is wrong, fully revert before testing the next. Use `git bisect` to find regressions efficiently.

**4. Fix and verify** — create a failing test FIRST, then fix. Run the test. Confirm the original reproduction case passes. No completion claims without fresh verification evidence.

## Three-Fix Threshold

After 3 failed fix attempts, STOP. The problem is likely architectural, not a surface bug. Step back and question assumptions about how the system works. Read the actual code path end-to-end instead of spot-checking.

## Escalation: Competing Hypotheses

When the cause is unclear across multiple components, use Analysis of Competing Hypotheses:
- Generate hypotheses across failure modes: logic error, data issue, state problem, integration failure, resource exhaustion, environment
- Investigate each with evidence: Direct (strong), Correlational (medium), Testimonial (weak)
- Cite evidence with `file:line` references
- Rank by confidence. If multiple hypotheses are equally supported, suspect compound causes.

## Intermittent Issues

- Track with correlation IDs across distributed components
- Race conditions: look for shared mutable state, check-then-act patterns, missing locks
- Resource exhaustion: monitor memory growth, connection pool depletion, file descriptor leaks
- Timing-dependent: replace arbitrary `sleep()` with condition-based polling — wait for the actual state, not a duration

## Defense-in-Depth Validation

After fixing, validate at every layer — not just where the bug appeared:
- **Entry**: does invalid input get caught?
- **Business logic**: does the fix handle edge cases?
- **Environment**: does it work across configurations?
- **Instrumentation**: add logging to detect recurrence

## Bug Triage

When multiple bugs exist, prioritize by:
- **Severity** (data loss > crash > wrong output > cosmetic) separately from **Priority** (blocking release > customer-facing > internal)
- Reproducibility: always > sometimes > once. "Sometimes" bugs need instrumentation before fixing.
- Quick wins: if a fix is < 5 minutes and unblocks others, do it first

## Common Patterns

- **Null/undefined access** — trace where the value was expected to be set, check all code paths
- **Off-by-one** — check `<` vs `<=`, array length vs last index, loop boundaries
- **Async ordering** — missing `await`, unhandled promise rejection, callback firing before setup completes
- **Type coercion** — `==` vs `===`, string-to-number conversion, truthy/falsy edge cases
- **Timezone** — always store UTC, convert at display. Check DST transitions.

## Anti-Patterns

- Shotgun debugging (random changes without hypothesis) — revert and think instead
- Multiple simultaneous changes — isolate each change or you can't learn what worked
- Fixing the symptom not the cause — the same bug will resurface differently
- Ignoring intermittent failures ("works on my machine") — instrument and reproduce under load instead

## Source & license

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

- **Author:** [iliaal](https://github.com/iliaal)
- **Source:** [iliaal/whetstone](https://github.com/iliaal/whetstone)
- **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-iliaal-whetstone-debugging
- Seller: https://agentstack.voostack.com/s/iliaal
- 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%.