01 / Summary

What this skill teaches your AI coding agent

Systematic Debugging enforces an unbending finite-state machine over autonomous coding agents. The Iron Law dictates that zero production code modifications are permitted until a reproduction test isolates the underlying defect. The protocol transitions linearly through four discrete states: Root-Cause Investigation via stack trace and data flow inspection, Pattern Analysis comparing working baseline paths against failing executions, Single-Variable Hypothesis formulation, and Verified Remediation. The agent cannot skip states or apply speculative adjustments without violating the operational invariant.

✦ DIRECT ANSWERCITABLE DEFINITION

Systematic Debugging is an open-source engineering skill licensed under MIT that enforces a mandatory 4-phase root-cause isolation protocol before allowing code edits.

✓ Use it if

You need strict, reproducible guardrails enforcing software engineering discipline across agent interactions.

✕ Skip it if

You are building quick disposable prototypes where architectural consistency and test verification are unnecessary.

02 / When It Triggers

Activation boundaries & prompt triggers

Autonomous Activation TriggerToken Tax: ~380 tk

Prompts that fire this skill:

💬 "User prompts: "Fix this flaky CI failure in the payment webhook""
💬 "Test passes locally but fails with exit code 137 in Docker"
💬 "Intermittent connection pool timeout under concurrent load"

Hard Negative Invariants (Agent Guardrails):

⛔ Construct a minimal, reproducible test case before modifying any application source code.
⛔ Formulate a verifiable root-cause hypothesis and confirm it with diagnostic probes.
⛔ Never implement speculative patches forward without proving the failure mechanism.

03 / Installation

Inject into Claude.ai, Claude Code, or Cursor

Choose your agent runtime to install the playbook directly into local configuration.

.cursor/rules/systematic-debugging.mdc

MARKDOWN25 lines

1---
2description: Rigorous 4-phase investigation protocol forcing autonomous agents to isolate root causes and formulate hypotheses before touching production code.
3globs: *
4alwaysApply: false
5---
6
7# Systematic Debugging Protocol
8
9CRITICAL: You are strictly forbidden from modifying production code or proposing speculative fixes upon encountering a bug, test failure, or unexpected behavior.
10
11Follow this mandatory 4-phase protocol:
121. ROOT CAUSE INVESTIGATION:
13   - Read the complete error log, stack trace, and exact line numbers.
14   - Isolate the failing component and trace the exact data flow that led to corrupted state.
15   - Review recent git commits or diffs to identify what changed.
162. PATTERN ANALYSIS:
17   - Compare the broken path against working paths in the codebase.
18   - Document all discrepancies in arguments, environment, or timing.
193. SINGLE-VARIABLE HYPOTHESIS:
20   - Formulate exactly ONE hypothesis: "X is failing because Y".
21   - Execute a minimal test to confirm or refute. If refuted, return to Phase 1.
224. VERIFIED REMEDIATION:
23   - Write a minimal failing automated test that reproduces the bug.
24   - Implement the root-cause fix (symptom patches are forbidden).
25   - Run the full test suite to guarantee zero regressions.

04 / What's Inside

Interactive file tree manifest & playbook viewer

Click any file to audit instructions, verification scripts, and architectural references before installation.

SKILL.md

---
name: systematic-debugging
description: "Rigorous 4-phase investigation protocol forcing autonomous agents to isolate root causes and formulate hypotheses before touching production code."
version: 1.0.0
license: MIT
compatibility: [claude-3-5-sonnet, cursor, windsurf, cline]
---

# Systematic Debugging Protocol

Systematic Debugging enforces an unbending finite-state machine over autonomous coding agents. The Iron Law dictates that zero production code modifications are permitted until a reproduction test isolates the underlying defect. The protocol transitions linearly through four discrete states: Root-Cause Investigation via stack trace and data flow inspection, Pattern Analysis comparing working baseline paths against failing executions, Single-Variable Hypothesis formulation, and Verified Remediation. The agent cannot skip states or apply speculative adjustments without violating the operational invariant.

## Core Guardrails
- ⛔ Construct a minimal, reproducible test case before modifying any application source code.
- ⛔ Formulate a verifiable root-cause hypothesis and confirm it with diagnostic probes.
- ⛔ Never implement speculative patches forward without proving the failure mechanism.

## Autonomous Activation Triggers
When user prompts:
- "User prompts: "Fix this flaky CI failure in the payment webhook""
- "Test passes locally but fails with exit code 137 in Docker"
- "Intermittent connection pool timeout under concurrent load"

05 / Before & After

Verified behavioral proof of work

Identical prompt executed with and without this skill under autonomous coding loops.

✦ BEHAVIORAL PROOF OF WORK

Investigate intermittent 500 error on checkout webhook

Token Footprint1,410 tokens90% Token Savings

Files Mutated1 file

Execution VerdictDeterministic Pass

Guarded Agent Loop:

Phase 1: Minimal reproduction test written (fails with expected 401). Phase 2: Root cause isolated to missing Redis lock TTL. Phase 3: Surgical 2-line patch. Phase 4: Green verification pass.

git diff --stat (1 file, minimal patch)

1diff --git a/src/services/webhookLock.ts b/src/services/webhookLock.ts
2@@ -14,2 +14,2 @@
3- await redis.set(lockKey, "1", "EX", 10);
4+ await redis.set(lockKey, "1", "PX", 5000, "NX");

06 / Security & Script Audit

Execution safety and file access boundaries

⚠ Code Execution Audit Warning

Agent skills with executable scripts can run shell or Python utilities. Always audit scripts before execution.

Scope: Bound to active workspace branch.
Network Calls: Zero outbound network calls.
AST Syntax Gate: Pre-flight verification blocks breaking mutations.

07 / Troubleshooting

Operational triage & resolution runbook

✦ OPERATIONAL RUNBOOKField Triage

⚠Skill not triggering during user conversational prompt▼

Probable Root Cause:

Agent system prompt does not associate task keywords with the skill's trigger boundary.

Recommended Fix:

Reference the skill name explicitly in your prompt (e.g., "Follow the rules in systematic-debugging to perform this refactoring").

⚠Conflicting rules with root project instructions▼

Probable Root Cause:

Global instructions (.cursorrules or CLAUDE.md) contradict the skill's invariants.

Recommended Fix:

Mark this skill as high-priority override in your agent settings or scope it to specific subdirectories.

⚠Context window saturation warning▼

Probable Root Cause:

Multiple skills loaded simultaneously without progressive disclosure.

Recommended Fix:

Keep always-on skills under 1,000 tokens total (~380 tokens consumed by this playbook).

08 / Decision Rubric

Skill vs. MCP Server vs. Plain System Prompt

Primitive	Best Used When	Token Cost	Execution Risk
Agent Skill (`SKILL.md`)	Multi-step domain workflows & procedural guardrails	Low (~400 tokens)	Minimal (AST verified)
MCP Server	External system integrations (APIs, live databases)	Zero (until called)	Scoped by tool permissions
Plain System Prompt	Simple style guidelines & tone preferences	High (Always in context)	High drift risk