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:

Paradigm	Isolation Direction	Isolation Technique
Backend layered	Entry → Logic → Data (inward)	Add logging at each layer boundary; find the first layer that returns incorrect data
Frontend component tree	Page → Feature → Atom (downward)	Props injection test: pass hardcoded data directly to component, bypass store
CLI / Script	Entry → Command handler → Core logic (inward)	Print intermediate values at each function boundary
Functional (FP)	I/O boundary → Pure core (inward)	Test pure functions in isolation; side effects confined to boundaries
Concurrent / Async	Reconstruct timing diagram; locate shared state	Add timestamps/sequence numbers to logs; inspect lock points on shared state
Event-driven	Trace event publish → handler chain	Log each consumed event; verify handler receives correct payload