debug

Stars13

Forks2

UpdatedJuly 22, 2026 at 02:20

Use when a bug isn't obvious, resists a quick fix, keeps coming back, or you're about to start guessing — "why is this broken", "this keeps happening", intermittent or flaky failures, a crash you can't explain, behaviour that makes no sense. Not for a typo or an obvious mistake.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

mehrad-dm

mehrad-dm/mastermind

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

2 files

SKILL.md

readonly

name	debug
description	Use when a bug isn't obvious, resists a quick fix, keeps coming back, or you're about to start guessing — "why is this broken", "this keeps happening", intermittent or flaky failures, a crash you can't explain, behaviour that makes no sense. Not for a typo or an obvious mistake.

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." If it still won't reproduce after honest effort: stop — never guess at a fix for a bug you can't reproduce, and never claim it's fixed. Ship instrumentation instead (logging/assertions at the suspect boundaries) so the next occurrence is diagnosable, state explicitly what you ruled out and how, and hand back with that evidence. "I couldn't reproduce it" is the honest answer, and usually a faster route to the real cause than three speculative patches.
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. Budget: three refuted hypotheses. Three misses means the framing is wrong, not the ranking — stop generating candidates and widen the search: challenge an assumption you never verified, distrust the reported symptom, or return to (2) and bisect harder (commits, environment, data) until the region shrinks.
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 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.

More from this repository

same repository

init

mehrad-dm/mastermind

Use on the first substantive work in a project MasterMind isn't set up for yet, when the user says "init", "initialize", "set up MasterMind", "onboard", "get me ready", or when no field pack matches the project's detected stack.

2026-07-2413

levelup

mehrad-dm/mastermind

Use after a correction or review finding worth remembering, when standards may have drifted from the live ecosystem, when switching MasterMind to a new domain or stack, or when the user says "remember this", "learn from that", "level up", "update your knowledge".

2026-07-2413

build

mehrad-dm/mastermind

Use when implementing any non-trivial feature, change, or fix — "build me X", "add this feature", "implement this", "make this work", "can you create". Covers new functionality, meaningful changes to existing code, and anything where quality matters. Not for a one-line diff — just do that.

2026-07-2213

explain

mehrad-dm/mastermind

Use when an internal package, module, or shared component has little or no usage documentation and people (or future AI sessions) keep using it wrong — "document this", "write docs for our library", onboarding someone onto an internal API, or handing a package to another team.

2026-07-2213

handoff

mehrad-dm/mastermind

Use when work needs to survive losing context — before a /clear on a long task, when pausing something unfinished, when handing over to a teammate or the next session, or when the context window is filling up on multi-day work.

2026-07-2213

help

mehrad-dm/mastermind

Use when the user asks what MasterMind can do or how to drive it — "help", "what can you do", "how do I use this", "what commands are there", "list your skills", "what are my options" — or when they seem unsure how to get started.

2026-07-2213

name	debug
description	Use when a bug isn't obvious, resists a quick fix, keeps coming back, or you're about to start guessing — "why is this broken", "this keeps happening", intermittent or flaky failures, a crash you can't explain, behaviour that makes no sense. Not for a typo or an obvious mistake.

MasterMind — Debug

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." If it still won't reproduce after honest effort: stop — never guess at a fix for a bug you can't reproduce, and never claim it's fixed. Ship instrumentation instead (logging/assertions at the suspect boundaries) so the next occurrence is diagnosable, state explicitly what you ruled out and how, and hand back with that evidence. "I couldn't reproduce it" is the honest answer, and usually a faster route to the real cause than three speculative patches.
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. Budget: three refuted hypotheses. Three misses means the framing is wrong, not the ranking — stop generating candidates and widen the search: challenge an assumption you never verified, distrust the reported symptom, or return to (2) and bisect harder (commits, environment, data) until the region shrinks.
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 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.