# Mastermind Debug

> Structured six-phase debugging for a hard bug — reproduce, localize, hypothesize, test the hypothesis, fix the root cause, guard against regression. Use when a bug isn't obvious, resists a quick fix, or keeps coming back. Enforces evidence over guessing.

- **Type:** Skill
- **Install:** `agentstack add skill-mehrad-dm-mastermind-mastermind-debug`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mehrad-dm](https://agentstack.voostack.com/s/mehrad-dm)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mehrad-dm](https://github.com/mehrad-dm)
- **Source:** https://github.com/mehrad-dm/mastermind/tree/master/skills/mastermind-debug
- **Website:** https://mastermind.mehrad.me

## Install

```sh
agentstack add skill-mehrad-dm-mastermind-mastermind-debug
```

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

## About

# MasterMind — Debug

Hard bugs are lost by guessing and patching symptoms. This is the disciplined loop that finds the
actual cause. Bug: **$ARGUMENTS**. Grounded in `~/.mastermind/engineering/core/rigor.md` and `~/.mastermind/engineering/core/agent-loop.md`.

The cardinal rule: **understand the mechanism before you change a line.** A fix you can't explain is a
coincidence, not a fix.

## The six phases

1. **Reproduce deterministically.** Find the smallest reliable trigger and a check that goes red on the
   bug (a failing test, a script, a repro URL/steps). No repro → no fix; keep narrowing inputs until it
   fails on demand. This red check is also your definition of "fixed."

2. **Localize.** Bisect the space — git bisect across commits, binary-search the code path, add
   instrumentation/logs at boundaries. Read the *actual* code and the *actual* data/state at the
   failure point; don't theorize from memory. Narrow to the smallest region that still reproduces.

3. **Hypothesize.** List the credible causes (usually 2–4), ranked. State, for the top one, the exact
   mechanism: "X happens because Y is Z at line N." Reason from first principles and the runtime model,
   not from superstition.

4. **Test the hypothesis.** Prove or kill it with a targeted experiment — inspect the value, toggle the
   condition, add an assertion. Confirm the mechanism *before* fixing. If the experiment refutes it, go
   back to (3) with what you learned. Don't shotgun-change multiple things.

5. **Fix the root cause, not the symptom** (`~/.mastermind/engineering/core/rigor.md`). Address why the bad state was possible —
   ideally make it unrepresentable (types, invariants, a reshaped data structure so the edge case
   disappears — `~/.mastermind/engineering/core/mindset.md`). Never suppress an error to green the check.

6. **Verify + guard.** Confirm the red check now passes and nothing else broke (typecheck/lint/tests/
   build). **Add a regression test that would have caught this** — the bug must not be able to return
   silently. Show the evidence.

## After
Run **`mastermind-levelup`** (capture) to record the class of bug and its lesson in the active field's
`lessons.md`, so MasterMind doesn't relearn it. Report: root cause, the fix, and the guard added.

## Source & license

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

- **Author:** [mehrad-dm](https://github.com/mehrad-dm)
- **Source:** [mehrad-dm/mastermind](https://github.com/mehrad-dm/mastermind)
- **License:** MIT
- **Homepage:** https://mastermind.mehrad.me

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-mehrad-dm-mastermind-mastermind-debug
- Seller: https://agentstack.voostack.com/s/mehrad-dm
- 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%.