Menu
Debugging Protocol
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.
Based on SOC occupation classification
Generate and curate Claude-oriented bash-policy project rules. Use to run bash-policy export/report, review .bash-policy-candidates.yaml from Claude settings, update .bash-policy.yaml, normalize command-shape identities, or validate bash-policy configuration.
Assess whether an input document is ready for a specific §BRAND_NAME_TITLE§ MAS entry point. Use when a user asks whether a goal, functional spec, detailed spec, technical spec, PRD, story bundle, architecture plan, or other source document is solid enough to run through §BRAND_BINARY_NAME§ with `--entry-point general-objective`, `functional-spec`, `detailed-spec`, or `technical-spec`; when deciding which entry point fits a document; or before `§BRAND_BINARY_NAME§ init --spec`.
Coordinate Pairing-mode doer/reviewer sessions through a Markdown blackboard. Use when the user invokes /adversarial-pairing with role and blackboard-path arguments or asks multiple pairing agents to coordinate plan review, implementation, staged code review, and follow-up review rounds without §BRAND_NAME_TITLE§ multi-agent mode.
Define component boundaries, interfaces, and structural decisions for a change
Summarize artifacts produced by §BRAND_BINARY_NAME§ agents for human checkpoint review
Pre-commit Clean Code refactoring
| name | debugging |
| description | Debugging Protocol |
Debugging optimizes for certainty, not speed. Speed is a byproduct of certainty. Debugging always starts by ruling out trivial causes. If not sufficient, there are two different paths to pursue: Fast Path and Normal Path.
First check the no brainers:
If any of these is the cause → fix directly, no protocol needed.
Note: Regular tasks have their own FAST PATH (Rule 4).
Eligible when ALL true:
Constraint: No refactor, no cleanup, no opportunistic improvements. Fix the bug and stop.
Format:
Mode: Debug (Fast)
Bug: [one-line: location + cause]
Fix: [one-line change]
Verify: [test/command] → [expected outcome]
Proceed (P)?
The above verification should be successful for the bug to be considered fixed.
Escalation: If fix fails on first attempt → undo the fix, then escalate to normal path. No second tries in fast mode. If new information contradicts the initial hypothesis → abandon Fast Path immediately. Don't bend the hypothesis to fit.
Before qualification, ground the report:
If critical context is missing, ask before proceeding.
When debugging detected, ask: "Debugging in [collaboration mode] because [reason]. Override?"
Defaults: Syntax/type → Autonomous. Logic → User Duck. Architectural → Pairing.
Escalation: 2 failed Autonomous → User Duck. 3 stalled iterations → Stop & Document (see Structured Failure Report).
Convergence Goal: A reproducible trigger + a traced failure path. Iterate until both are stable.
Failure Path: Trace trigger → state → symptom with concrete identifiers (values, line numbers, states).
Reproducibility: Capture in failing test (ideal — this becomes the regression test) or documented manual steps (acceptable). Reduce to minimal case before analysis — fewer lines reveal more. If sporadic: narrow conditions or instrument. Do not propose fixes for untriggerable bugs.
Counterfactual Check: What similar inputs/states do NOT trigger the bug?
Temporal Bug Patterns: If timing-related, identify the category:
Instrumentation for temporal bugs:
These bugs may resist minimal reproduction — document the timing conditions even if not fully deterministic.
Qualification Summary:
Bug Profile: [regression|novel] [deterministic|flaky] [reproducible|sporadic] [tested|untested]
Optional: [technical|logical] [observable|opaque] [localized|distributed] [stateless|stateful]
If regression: consider git bisect (known-good SHA, fast test command; moves HEAD — approval required).
Signal: [symptom] vs [expected] — Observability: [stacktrace|logs|metrics|user report|silent]
Impact: [data loss | security exposure | user-visible | silent corruption | degraded performance | cosmetic]
Reproduction: [steps] — Feedback loop: [fast <10s | slow | manual]
Failure Path: [traced path, observed vs inferred]
Missing Evidence: [none | logs: ... | access: ... | repro: ... | spec: ... | metrics: ... | permissions: ...]
User context needed? [N / Y: specific question]
Proceed to analysis? (Y/N)
Before narrowing, establish a reference point:
If no analogue exists, note explicitly — you're debugging novel code without a known-good reference.
Skip this phase when: the bug is in isolated logic with no comparable pattern, or the failure path already points to a clear contract violation.
Debugging is a narrowing search, not guess-and-check.
Observability check: Before narrowing, ensure you can observe the relevant state transitions. If not, add instrumentation (logging, tracing, metrics) before forming hypotheses. Debugging blind wastes cycles.
Loop until atomic:
Analysis Summary: Before Root Cause Identification, summarize the narrowing chain.
Where → Why: Pull the string until you reach an actionable flaw — something that should have been different and can be corrected.
Before proposing fix: what evidence would prove this root cause wrong?
Root Cause Gate:
Category: [wrong assumption | missing guard | violated contract | design gap | external dependency | timing/race | data corruption | observability gap | other: ...]
Root Cause: [one-line actionable flaw]
Chain: [root cause] → [symptoms] → [impacts]
Falsifiable by: [evidence that would prove this wrong]
Confidence: [high: would bet on it | medium: best hypothesis | low: educated guess]
Proceed to Resolution (P)?
TECH_DEBT.md, schedule follow-upPost-Resolution Reflection:
Stop-on-Repeat: Same fix twice → explain why it will work this time.
Struggle Report (3 stalled attempts):
Attempted: [approach] — failed because [reason]
Dead Ends: [do not revisit]
Evidence Gathered: [what we now know that we didn't before]
Remaining Hypotheses: [untested]
Blockers: [what prevents progress]
Next Steps: [escalation or alternative]