// Use when a test is failing, when a bug is reported, when behavior is unexpected or intermittent, when a build or integration step fails, or when a flaky test keeps resurfacing. Especially when "the fix seems obvious", when multiple previous fixes haven't stuck, or when under time pressure to ship.
| name | debugging |
| description | Use when a test is failing, when a bug is reported, when behavior is unexpected or intermittent, when a build or integration step fails, or when a flaky test keeps resurfacing. Especially when "the fix seems obvious", when multiple previous fixes haven't stuck, or when under time pressure to ship. |
Debugging in gambit is investigation, not fixing. You reproduce the bug, gather evidence, trace to the true root cause, and write a test that proves you understand it. Then you hand that understanding to gambit:brainstorming, which designs the fix as an epic and runs it through the normal build pipeline.
Random fixes waste time and create new bugs. A fix for a symptom you don't understand is a guess wearing a confidence costume.
Core principle: Find the root cause with evidence before any fix is designed.
Iron Law: No fix designed without root-cause evidence AND a failing test that reproduces the bug. Think the fix is obvious? Prove it with evidence first. No exceptions.
Announce at start: "I'm using gambit:debugging to find the root cause."
MEDIUM FREEDOM — Follow the investigation sequence; adapt the techniques to the bug in front of you. Non-negotiable: evidence before hypothesis, a failing test before handoff, fix the source not the symptom.
| Step | Action | STOP If |
|---|---|---|
| 1 | Reproduce & gather evidence | Can't reproduce consistently |
| 2 | Investigate root cause | Still guessing (no evidence) |
| 3 | Write failing test that captures the bug | Test passes (doesn't catch it) |
| 4 | Hand root cause to brainstorming | 3+ hypotheses already failed → question architecture |
Terminal: root cause + failing test → gambit:brainstorming designs and executes the fix. This skill does NOT fix, classify, or close — it understands, then hands off.
Don't use for: new features (gambit:brainstorming), refactoring (gambit:refactoring)
BEFORE forming any theory:
git log --oneline -10 and git diff HEAD~5..HEAD -- path/to/affected/codeMulti-component path? When the failing path crosses 3+ boundaries (CI → build → signing; handler → service → cache → DB), you can't reason out which component is broken from the error alone — instrument every boundary, run once, then investigate the layer the evidence points at. See references/root-cause-tracing.md.
Evidence before hypothesis. Use tools, not guessing.
WebSearch for error messages; dispatch an Explore agent for codebase investigation (how is this called? what data flows here? what changed?)Match the bug shape to a technique:
| Bug shape | Technique |
|---|---|
| Flaky / timing-dependent test | references/condition-based-waiting.md |
| "Which test pollutes shared state?" | references/find-polluter.sh |
| Deep-stack bug, unclear origin | references/root-cause-tracing.md |
Write the smallest test that reproduces the bug. Run it — it MUST fail.
A failing test is how you prove you found the real bug instead of a plausible story. If it passes immediately, you don't understand the bug yet — return to step 2.
def test_rejects_empty_email():
# Reproduces the reported bug: empty email slips through registration
_, err = create_user(User(email=""))
assert err is not None, "expected validation error for empty email"
This test is the artifact you hand to brainstorming — it pins down exactly what "fixed" means.
You now hold the two things a good fix needs: the root cause (with evidence) and a failing test that captures it. That's the seed of the fix epic.
Default (almost always) — invoke gambit:brainstorming:
Skill skill="gambit:brainstorming"
Tell it the investigation is done so it designs the fix rather than re-investigating. Feed it:
Brainstorming turns this into an epic and routes it through executing-plans → review like any other work — that's where the fix gets written, verified, and reviewed.
Fast path (one-liners only): if the root cause is a genuine one-line change and the failing test fully guards it, just make the change and verify (test passes + full suite green). Don't spin up an epic for a typo. Anything larger than a one-liner → brainstorming.
If 3+ hypotheses or fixes have already failed: STOP. Each fix revealing a new problem elsewhere, or fixes that need "massive refactoring," means your root-cause model is wrong or the architecture is. Question fundamentals with the user before handing a shaky diagnosis to brainstorming.
All mean: STOP. Return to steps 1–2.
| Excuse | Reality |
|---|---|
| "Issue is simple, don't need to investigate" | Simple issues have root causes too |
| "Emergency, no time to investigate" | Systematic is FASTER than thrashing |
| "Just try this fix first, then investigate" | First fix sets the pattern. Do it right. |
| "I'll write the test after I confirm the fix" | Untested fixes don't stick |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem |
| "Obviously X is the cause" | "Obvious" causes are often wrong. Get evidence. |
Can't check these? Return to the process.
This skill calls:
Explore / general-purpose agents for codebase investigationWebSearch for error-message researchgambit:brainstorming (terminal — designs and executes the fix from the root cause)Called by:
gambit:parallel-agents (investigates each isolated failure)Workflow:
Bug → reproduce → evidence → root cause → failing test → gambit:brainstorming → (epic → executing-plans → review)
Use when user has a new feature idea, rough concept, or unexplored approach. Include when planning before code, breaking a design into tasks, creating an implementation plan, laying out tasks and dependencies, exploring architectural options, or requirements are vague. User phrases like "I want to build X", "should we do this", "let's think through Y", "explore approaches", "break this into tasks", "make an implementation plan". Do NOT use for executing existing plans, fixing bugs, refactoring, or when requirements and an epic already exist.
Use when an epic Task exists and subtasks are ready to implement, when resuming work after a previous checkpoint, when iteratively building a feature, or when implementation has revealed unexpected work that needs a new task. User phrases like "continue the plan", "next task", "resume where we left off", "pick up the epic".
Use after all tasks in an epic complete, after refactoring verifies, or before merging to main. Triggers when independent validation is needed that code meets requirements, has no security gaps, passes quality standards, and has no performance regressions. User phrases like "review this", "is this ready to merge", "validate the implementation".
Use when a task plan has just been created and needs review before execution, when brainstorming just handed off, when unsure whether a junior could execute without questions, or when you see placeholder text, vague success criteria, or missing edge cases. User phrases like "review these tasks", "are these ready?", "before we start", "catch any gaps". Do NOT use when implementation is already in progress or for creating plans from scratch.
Use when bugs keep slipping through despite high test coverage, when suspecting tests are giving false confidence, before a major refactor that will depend on the existing test suite, or when coverage metrics don't match incident rates. User phrases like "do these tests actually catch bugs?", "is this suite any good?", "why didn't the tests catch this?".
Use at the start of every session before any response or action. Also invoke whenever uncertain which gambit skill applies, when about to implement / debug / refactor / test / plan / brainstorm, or when a user request could match any gambit skill even at 1% probability.