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.
Install
$ agentstack add skill-mehrad-dm-mastermind-mastermind-debug ✓ scanned · ✓ verified, works with Claude Code, Cursor, and more.
Security review
✓ PassedNo issues found. Passed automated security review. · v0.1.0 How review works →
- ✓ Prompt-injection patterns
- ✓ Secret / credential exfiltration
- ✓ Dangerous shell & filesystem operations
- ✓ Untrusted network calls
- ✓ Known-malicious package signatures
What it can access
- ✓ Network access No
- ✓ Filesystem access No
- ✓ Shell / process execution No
- ✓ Environment & secrets No
- ✓ Dynamic code execution No
From automated source analysis of v0.1.0. “Used” means the capability is present in the source — more access means more to trust, not that it’s unsafe.
Verified badge
Passed review? Show it. Paste this badge into your README, it links to the public security report.
Links to your public security report.[](https://agentstack.voostack.com/security/report/skill-mehrad-dm-mastermind-mastermind-debug) Reliability & compatibility
Declared compatibility
Compatibility is declared by the source manifest. End-to-end runtime verification is coming, see below.
We're building live execution health for every listing: tool-call success rate, median latency, uptime, and last-checked timestamps, measured, not self-reported. It isn't live yet, so we don't show numbers we can't stand behind.
How agent discovery & health will work →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
- 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."
- 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.
- 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.
- 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.
- 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.
- 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
- Source: mehrad-dm/mastermind
- License: MIT
- Homepage: https://mastermind.mehrad.me
Install and usage instructions live in the source repository linked above.
Reviews
No reviews yet, be the first.
Write a review
Versions
- v0.1.0 Imported from the upstream source.