Debug

!../principles/SKILL_BODY.md

!../tool-gitnexus/SKILL_BODY.md

Debugging Workflow

Disambiguation Gate

Before starting: Can you point to a specific function or line and say "the bug is here"? → Yes → Stop. Use sextant:fix-bug — the location is known, that skill handles the fix. → No → Continue here. This skill is for "symptom known, location unknown."

Core Principle

Debug by bisection, not inspection. Form a hypothesis about which boundary separates correct from incorrect behavior, then eliminate layers until only the root cause remains.

Complete Execution Workflow

Step 1: Capture the Symptom

Before forming any hypothesis, establish a precise symptom record:

• Error message (exact text, stack trace if available)
• Reproduction steps (what sequence of actions triggers it?)
• Frequency (always / intermittent / environment-specific)
• Regression (did this ever work? What changed recently?)

─── Symptom Record ──────────────────────────────────
Error / unexpected output: <exact message or behavior>
Trigger steps:             <reproducible sequence>
Frequency:                 Always / Intermittent (~X%) / Specific environment only
Regression:                Yes (last known good: <commit/date>) / No / Unknown
─────────────────────────────────────────────────────

Step 2: Identify Paradigm + Select Isolation Strategy

Identify which architecture paradigm applies (per §6.0), then use the corresponding isolation strategy:

🔗 When GitNexus is available, use context / trace MCP tools to map the call chain automatically.

Step 3: Form and Validate Hypotheses

Bisection protocol: Find the boundary between "working correctly" and "already wrong."

1. Identify the layer / module where the symptom surfaces — this is the observation point
2. Ask: "Is the input to this layer already wrong, or does this layer corrupt correct input?"
3. Move the observation point inward (toward the source) until you find the first layer that produces incorrect output
4. That boundary is your root cause hypothesis

For intermittent bugs (concurrency / async):

• Add sequence numbers or timestamps to logs before the symptom point
• Identify the shared state that changes between passing and failing runs
• Hypothesis format: "Thread A reads X before Thread B writes the updated value"

For environment-specific bugs:

• List all environmental differences (OS, config, versions, data state)
• Eliminate variables one by one until the failing condition is isolated

─── Hypothesis Log ──────────────────────────────────
Hypothesis 1: <the bug is in X because Y>
  Test:   <what to check / add / isolate>
  Result: ✅ Confirmed / ❌ Eliminated / ⏳ Pending

Hypothesis 2: ...
─────────────────────────────────────────────────────

Hypothesis limit gate — trigger when 3+ hypotheses have been eliminated without confirming root cause:

Stop the bisection loop. Do not generate more hypotheses. Instead, choose one of the following escalation paths:

1. Request more context — ask the user for: a minimal reproduction case, relevant logs or stack traces at the failure point, or the last known-good commit/state
2. Suggest git bisect — if the bug is a regression with an unknown introduction point, git bisect identifies the exact commit; ask the user to run it and share the result
3. Add structured logging — propose specific log statements at the current observation point boundary; ask the user to re-run and share the output before resuming bisection
4. Widen the symptom map — if only one symptom was captured, ask whether the bug manifests differently under other conditions (different inputs, environments, users)

─── Escalation Decision ─────────────────────────────
Hypotheses eliminated: N
Root cause: ⏳ not yet confirmed
Escalation chosen: <context request / git bisect / structured logging / symptom widening>
Information needed from user: <specific artifact or action>
─────────────────────────────────────────────────────

Step 4: Confirm Root Cause → Hand Off to Fix

When you can answer all three:

1. Which function / line produces the incorrect output?
2. Under what exact input or state does the failure occur?
3. Why does that code produce incorrect output (logic error, missing guard, race condition, wrong assumption)?

→ Root cause is confirmed. Hand off: switch to sextant:fix-bug.

Provide the fix-bug workflow with pre-filled context:

• Root cause location (file + function)
• Trigger conditions
• Impact scope already identified (skip fix-bug Step 2 if already covered here)

Forbidden Actions

• Do not apply a workaround (try/except swallowing, hardcoded fallback value) before the root cause is confirmed — this hides the bug
• Do not generate a list of all possible causes without narrowing — work by elimination, not enumeration
• Do not start fixing while the location is still uncertain — confirm first, then hand off to sextant:fix-bug

Reply Format

Debug Summary: