Skip to content
Skills Library
Programming · Analysis

debugging-protocol

/debugging-protocol

Systematic 4-phase debugging: (1) understand the failure by reading the complete error and reproducing it, (2) find working examples to compare against, (3) test one hypothesis at a time with a single change, (4) fix the root cause and verify with tests. Includes the Three Strikes Rule (escalate after 3 failed fix attempts) and the Iron Law (no fixes without investigation). Activate when tests fail unexpectedly, errors occur, behavior is wrong, something that worked before is now broken, or a user reports a bug. Triggers on: "debug", "why is this failing", "test failure", "unexpected error", "

Licence
CC0-1.0
Last repository change
05.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.07.2026, without references to retired models or APIs.

Licence

CC0-1.0, otwarta.

What it does and when to use it

Systematic 4-phase debugging: (1) understand the failure by reading the complete error and reproducing it, (2) find working examples to compare against, (3) test one hypothesis at a time with a single change, (4) fix the root cause and verify with tests. Includes the Three Strikes Rule (escalate after 3 failed fix attempts) and the Iron Law (no fixes without investigation). Activate when tests fail unexpectedly, errors occur, behavior is wrong, something that worked before is now broken, or a user reports a bug. Triggers on: "debug", "why is this failing", "test failure", "unexpected error", "

Triggers from the description

debugwhy is this failingtest failureunexpected error
Original author description

Systematic 4-phase debugging: (1) understand the failure by reading the complete error and reproducing it, (2) find working examples to compare against, (3) test one hypothesis at a time with a single change, (4) fix the root cause and verify with tests. Includes the Three Strikes Rule (escalate after 3 failed fix attempts) and the Iron Law (no fixes without investigation). Activate when tests fail unexpectedly, errors occur, behavior is wrong, something that worked before is now broken, or a user reports a bug. Triggers on: "debug", "why is this failing", "test failure", "unexpected error", "

How it works

  1. Purpose
  2. Practices
  3. Enforcement Note
  4. Constraints
  5. Verification
  6. Dependencies
Original SKILL.md headings · 167 lines, 1,023 words
SKILL.md preview
---
name: debugging-protocol
description: >-
  Systematic 4-phase debugging: (1) understand the failure by reading the
  complete error and reproducing it, (2) find working examples to compare
  against, (3) test one hypothesis at a time with a single change, (4) fix
  the root cause and verify with tests. Includes the Three Strikes Rule
  (escalate after 3 failed fix attempts) and the Iron Law (no fixes without
  investigation). Activate when tests fail unexpectedly, errors occur,
  behavior is wrong, something that worked before is now broken, or a user
  reports a bug. Triggers on: "debug", "why is this failing", "test failure",
  "unexpected error", "bug", "broken", "investigate this error", "fix this
  bug", "tests are failing", "weird behavior", "something broke", "track
  down this issue". Also activates when multiple bugs need systematic
  investigation (one at a time, not batch-fixed). NOT for: writing new tests
  from scratch (use tdd), or general code review (use code-review).
license: CC0-1.0
compatibility: Designed for any coding agent (Claude Code, Codex, Cursor, OpenCode, etc.)
metadata:
  author: jwilger
  version: "1.2.0"
  requires: []
  context: [source-files, test-files, git-history]
  phase: build
  standalone: true
effort: high
---

# Debugging Protocol

**Value:** Feedback -- systematic investigation produces understanding.
Understanding produces correct fixes. Correct fixes prevent recurrence.
Skipping investigation produces symptom fixes that hide bugs.

## Purpose

Teaches a disciplined 4-phase debugging process that enforces root cause
analysis before any fix attempt. Prevents the most common debugging failure
mode: jumping to a fix without understanding why the problem exists.

## Practices

### The Iron Law: No Fixes Without Investigation

Never change code to fix a bug until you have completed root cause
investigation. When you see an error and immediately know the fix, that is
exactly when you are most likely to be wrong. Investigate first.

**Do:**
- Read the complete error message and stack trace before doing anything else
- Reproduce the bug consistently before investigating
- Understand WHY something is broken, not just WHAT is broken

**Do not:**
- Add a null check because you see a null pointer error (symptom fix)
- Try "a few things" to see what sticks (random debugging)
- Skip investigation because "this is an easy one"

### Phase 1: Understand the Failure

Gather facts. Do not interpret yet.

1. Read the full error message -- every line, not just the first
2. Identify the exact file and line where the failure occurs
3. Reproduce the failure consistently (if it does not reproduce, that is
   important information)
4. Check recent changes: `git log --oneline -10` and `git diff`
5. Note the data flow: where does the bad value come from?

**Output:** A clear statement of what is happening, where, and since when.

### Phase 2: Find Working Examples

Compare broken against working. The difference is the bug.

1. Find similar code that works correctly
2. Compare setup, inputs, state, and configuration
3. Identify what differs between the working and failing case
4. Check dependencies: did a library update? Did an environment change?

**Output:** A specific difference between working and failing cases.

### Phase 3: Test One Hypothesis

Form a single, explicit hypothesis. Test it with one change. Learn from the
result.

1. State the hypothesis: "I believe the bug is caused by [X] because [evidence]"
2. Make ONE change to test it
3. Observe the result
4. If the hypothesis is wrong, UNDO the change completely
5. Form a new hypothesis incorporating what you learned

**Do not** change multiple things at once. If you change the import, the type,
and the logic simultaneously, you cannot know which change mattered.

**Output:** Confirmed or refuted hypothesis with evidence.

### Phase 4: Fix and Verify

Fix with confidence because you understand the root cause.

1. Write a failing test that reproduces the bug (if one does not already exist)
2. Implement the fix targeting the root cause identified in Phase 3
3. Verify: the new test passes, all existing tests still pass
4. Confirm you fixed the cause, not the symptom

**Output:** A fix backed by a test, with all tests green.

### Escalation: Three Strikes Rule

If three fix attempts fail, stop. The problem is not what you think it is.

After the third failure:

1. Stop attempting fixes entirely
2. Document what you tried and why each attempt failed
3. Question your assumptions: wrong abstraction? Wrong domain model? Wrong
   problem entirely?
4. Seek a broader perspective -- architecture review, domain expert, or
   escalate to the user

Three failed fixes almost always signal a design problem, not a code problem.
More code fixes will not help.

**Example:**
```
Attempt 1: Add caching (hypothesis: slow queries) -> Still slow
Attempt 2: Add index (hypothesis: missing index) -> Still slow
Attempt 3: Eager loading (hypothesis: N+1) -> Still slow
STOP. Profile the system.
Result: 90% of time in external API call. Not a database problem at all.
```

## Enforcement Note

- **Standalone mode**: Advisory. The Iron Law is self-enforced.
- **Pipeline mode**: Gating. Debugging evidence is required before fix
  commits pass the TDD gate.

**Hard constraints:**
- Iron Law (investigate before fix): `[H]`
- Three Strikes escalation: `[RP]`

## Constraints

- **Iron Law**: The temptation to skip investigation is strongest when the
  fix seems obvious. That is exactly when investigation is most valuable --
  because "obvious" fixes that are wrong waste more time than investigation
  would have cost. If you're reasoning about why THIS bug is the exception
  that doesn't need investigation, you're violating the Iron Law.
- **Three Strikes**: After three failed hypotheses, the problem is not what
  you think it is. "Stop" means stop fixing and return to investigation. It
  does not mean stop working entirely. Re-examine your assumptions, widen
  your investigation, look at adjacent systems. If you still can't identify
  the root cause, escalate.
- **Undo failed hypotheses**: "Undo completely" means the codebase returns
  to exactly the state before the hypothesis was tested. Not "mostly undone
  with a few improvements kept." Not "undone in the main file but I left the
  debug logging." Every change from the failed hypothesis is reverted.

## Verification

After debugging guided by this skill, verify:

- [ ] Completed Phase 1 investigation before any code changes
- [ ] Read the complete error message (not just the first line)
- [ ] Reproduced the bug consistently
- [ ] Found a working example to compare against
- [ ] Stated an explicit hypothesis before each fix attempt
- [ ] Made only one change per hypothesis test
- [ ] Undid failed hypotheses before trying new ones
- [ ] Wrote or confirmed a failing test before implementing the fix
- [ ] Verified all tests pass after the fix
- [ ] Did not exceed three fix attempts without escalating

If any criterion is not met, revisit the relevant phase.

## Dependencies

This skill works standalone with no required dependencies. It integrates with:

- **tdd:** When a test fails unexpectedly during TDD, this skill guides
  investigation before modifying code
- **user-input-protocol:** When debugging reaches an ambiguous decision point,
  pause and ask the user rather than guessing
- **domain-modeling:** If three fixes fail, the root cause may be a domain
  modeling problem -- escalate to domain review

Missing a dependency? Install with:
```
npx skills add jwilger/agent-skills --skill tdd
```

Versions

RepositoryScoreLicence
This page · jwilger/agent-skills100CC0-1.0
irahardianto/awesome-agv100MIT

Database snapshot: 13.11.2026 · package version 24dd89b0b1cd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100investigate
    Systematic debugging with root cause investigation. Four phases: investigate, analyze, hypothesize, implement. Iron Law: no fixes without root cause. Use when asked to "debug this", "fix this bug", "why is this broken", "investigate this error", or "root cause analysis".…
  • 100investigate
    Systematic debugging with root cause investigation. Four phases: investigate, analyze, hypothesize, implement. Iron Law: no fixes without root cause. Use when asked to "debug this", "fix this bug", "why is this broken", "investigate this error", or "root cause analysis".…
  • 95investigate
    Systematic debugging with root cause investigation. Four phases: investigate, analyze, hypothesize, implement. Iron Law: no fixes without root cause. Use when asked to "debug this", "fix this bug", "why is this broken", "investigate this error", or "root cause analysis".…
  • 100systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior. 4-phase root cause investigation — NO fixes without understanding the problem first.
  • 100systematic-debugging
    Use when encountering any bug, error, crash, failing or flaky test, build failure, unexpected behavior, or production incident, before proposing any fix — finds the root cause through evidence (reproduce, trace, compare, hypothesize, test one change at a time) instead of…
  • 100systematic-debugging
    Four-phase root-cause debugging—reproduce, compare patterns, hypothesize, fix with tests. Use when errors are unclear, fixes failed twice, or symptoms keep returning. Triggers: "root cause", "debug systematically", "why is this broken", "still failing".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.