Debugging skill: scientific method and checkpoint pattern in Claude Code

Easy bugs can be solved on the first try without thinking too much. They are 90% of all bugs. The remaining 10% - those that keep you awake at night, those that you thought you had fixed and come back, those that seem random but aren't - require a prosecutionThe Skill debugging Of Superpowers There exists to give structure to that minority which devours hours when faced with it instinctively.

Independence Disclaimer: I am not affiliated with Obra nor with Anthropic. What follows is direct experience on the skill. debugging Applied to a handful of medium-to-hard bugs on my brownfield portfolio in about one year.

Why is a scientific loop necessary for difficult bugs

A simple bug is a short causal chain: click the button X, see error Y, the fix is at an obvious point. A difficult bug has at least three characteristics:

1. The cause is far from the symptom (error in module A, but origin in B).
2. Reproducibility is imperfect (it happens 30% of the time under specific conditions).
3. More hypotheses are plausible (at least three causes could explain what you see).

Without a process, the investigation of a difficult bug becomes a series of disorganized attempts: change one thing, reload, see if it's better, change another thing, get confused about which modification had an effect, lose an hour and return to the starting point with the suspicion that maybe the error is elsewhere. This is the most common way to waste a workday afternoon.

The scientific method applied to debugging is obvious (formula hypothesis, head, measurement, refinement), but under pressure it's skipped. The skill debugging Forces the process even when instinct would want to skip steps.

What does the skill do, one cycle at a time

A debugging session with the skill active follows a recurring structure, repeated until the bug is resolved:

1. Current stateWhat do we know, what don't we know, What have we excluded.
2. HypothesisThere is only one explicit rule. "The bug X depends on Y." Nothing can be said to be A or B or C - those are multiple hypotheses and need to be tested separately.
3. Test that verifiesThe minimum experiment that allows for the confirmation or rejection of the hypothesis. Ideally, a deterministic test that reproduces the bug, but sometimes it's a strategic log or a specific cURL request.
4. MeasurementWhat do you expect to see if the hypothesis is correct? What do you expect to see if it's incorrect? Important: This sentence should be written first To perform the test.
5. Execution and resultPerform, record what you have observed Note, compare with the expected measurement.
6. I don't see any Italian text provided. Please provide the text you'd like me to translate, and I'll be happy to assist you.Update current state with what you've learned. Decide next hypothesis.

The cycle closes when you have a test that fails deterministically on the bug and moves on after fixing it. That test becomes a permanent regression test in the CI.

Example illustration: bug in internationalization and language href for the portfolio

Debug session summary (summarized). Observed bug: Google Search Console reports "Alternate page with proper canonical tag" for over 999+ URLs of the multilingual site. Concrete symptom: `/sv/blog/...` is indexed under canonical `/en/blog/...` instead of maintaining its own canonical.

Stato corrente
  - 18 lingue config in CLAUDE.md
  - 7 lingue compilate AOT, 11 lingue runtime
  - Hreflang dichiarato ma GSC rifiuta canonical /sv/

Ciclo 1
  Ipotesi: hreflang malformato nel head HTML
  Test: curl https://federicocalo.dev/sv/blog/X | grep hreflang
  Atteso: 18 entries hreflang con codici corretti
  Risultato: 18 entries corrette
  Checkpoint: hreflang OK -> bug altrove

Ciclo 2
  Ipotesi: content lingua effettiva non corrisponde al locale dichiarato
  Test: curl /sv/blog/X | grep "lang=" | head
  Atteso: lang="sv"
  Risultato: lang="en" (!!)
  Checkpoint: confermato content drift. SSR serve bundle EN sotto path /sv/.

Ciclo 3
  Ipotesi: SSR route mapping /sv/ -> bundle EN se sv non compilato AOT
  Test: ng serve --localize=sv (verifica bundle separato)
  Atteso: bundle sv esiste OR fallback documentato
  Risultato: sv NON compilato AOT, fallback automatico a EN bundle
  Checkpoint: causa confermata. Fix: chrome runtime Transloco per sv +
    altre 10 lingue runtime, gia documentato nel piano i18n 35.

Without the skill I would probably have tried two to three things by chance before arriving at the cause. With the skill, three structured cycles = cause identified in 20 minutes.

The checkpoint pattern as operational memory

The checkpoint pattern is the part of the skill that changed me the most the way I debug. It works like this: after every cycle, the skill produces a block of structured text (the "current state" of the next cycle) that summarizes:

• Hypotheses tested and their outcome (confirmed/ rejected/ inconclusive).
• Verified facts (what was observed as true).
• Excluded hypothesis (what was eliminated from the possible cause set).
• Next hypothesis to test.

The checkpoint is usually 200-400 words. If you interrupt the session (called urgent, end of day, kernel panic), pick up where you left off the next day by reading the checkpoint. Don't ask "how did debugging work yesterday?" - everything is written down.

On my portfolio I use checkpoints even after fixing the bug: stuck in the git commit message as "investigation summary", or saved in docs/memory/ For recurring bugs on components that keep causing me problems. Over the last six months, this practice has allowed me to fix bugs in just 5 minutes that I used to spend two hours diagnosing.

Effective testing strategies in the cycle

The part "test that verifies the hypothesis" is where skill makes the difference between efficient debugging and random attempts. Four practical strategies:

1. Minimal deterministic testReproduce the bug in the smallest possible way. If the bug is present on an API endpoint with ten parameters, isolate it to a script that calls the endpoint with a reduced payload. The smaller the test, the tighter the hypothesis.
2. Binary testDesign the test so that the result is binary: the hypothesis is confirmed or rejected. Avoid tests that produce ambiguous output.
3. Pre-execution measurementWrite first To execute what you expect to see. Without this writing, post-hoc rationalizing every result as "may confirm the hypothesis". This is the most common way to deceive oneself.
4. Trace testAdd strategic logs that survive the test. If the bug reappears in production within a week, the log allows you to start over where you left off.

Anti-pattern: multiple hypotheses in parallel

The natural temptation is to say: "Maybe it's A, maybe it's B, maybe it's C, let's try all three and see what changes." Wrong. If changing three things makes the bug disappear, you don't know which one was the cause. If the bug comes back tomorrow, you still won't know which fix reverted back.

The Skill debugging imposes one hypothesis at a timeCycles more, but each cycle leaves a proven fact. Three single cycles are faster than a "multiple test" that then requires 10,000 additional cycles to disambiguate.

Integration with Test-Driven Development

The Skill debugging It is complementary to tdd-guide:

• Test-Driven Development (TDD) Guide Force RED-GREEN-REFACTOR on business logic new.
• debugging Enters into play on business logic Existing It fails in a non-obvious way.

Integrated pattern: Integrated Pattern: The integrated pattern is a method used to analyze and understand complex data structures by breaking them down into smaller, more manageable components. This approach allows for the identification of patterns and relationships within the data, enabling the extraction of valuable insights and knowledge. XPHX0XPHX XPHX1XPHX: The Integrated Pattern is a powerful tool used in various fields such as computer science, mathematics, and engineering to analyze complex systems and identify patterns. The XPHX0XPHX XPHX1XPHX represents the specific application of this technique in a particular context. Integrated Pattern: The integrated pattern is a fundamental concept in many fields, including computer science, mathematics, and engineering. It provides a framework for analyzing complex data structures and identifying patterns, which can lead to breakthroughs in understanding and solving complex problems.

1. Bug observed in production.
2. Call debuggingFirst cycle: hypotheses on cause.
3. Test that reproduces the bug deterministically (it's the "RED" of the TDD part).
4. Confirmed hypothesis = identified cause.
5. Write the fix that passes the test (it's the "GREEN" of the TDD part).
6. Refactor as needed (RED-GREEN-REFACT COMPLETE).
7. Commit and push, regression testing stays in CI.

The test written during the investigation (step 3) should not be discarded after the fix: becomes a regression test that protects you if someone reintroduces the bug.

When skill is not enough: system bug

There are bugs that alone cannot be solved by skill. Typical cases:

1. Bug that lives outside of codeConfiguration of infrastructure, version drift on dependencies, network issues. The hypothesis must exit the repository and investigate the environment. The skill guides the process, but testing requires external tools (ssh + log inspection, monitoring dashboards, etc.).
2. Intermittent bug that does not reproduce locally.The typical hypothesis is "race condition" or "timing dependent". The skill pushes towards tools of stress testing (concurrent requests, fault injection) that require a non trivial setup.
3. Perception bugThe user reports a behavior that, upon investigation, is an incorrect interpretation of the correct behavior. Here "fix" refers to documentation or UX, not code. The skill, applied strictly, fails to recognize it and makes you search for non-existent causes.

three cases the skill remains useful for organize The investigation, even if the solution comes out of the code.

Typical session: times and costs

On my portfolio, a typical debugging session (medium-complexity bug) has the following parameters: Note: I've preserved the exact format and punctuation of the original text.

• I don't see any Italian text provided. Please share the text you'd like me to translate, and I'll be happy to assist you.3-7 per bug medium, 8-12 per bug hard.
• Duration15-40 minutes for medium, 60-120 minutes for hard.
• Consumed tokens$15,000-$40,000 per month (in/out) for a medium-sized business.
• I'm ready to translate. Please provide the Italian text and I'll output the English translation according to the rules you specified.Bug fixed + test regression + checkpoint summary committed.

Comparison: before adopting the skill, debugging at a medium instinct level was 45-90 minutes per medium bug. Reduction of 50-60% of time, with a bonus: the regression test remains in CI as future protection.

Custom variant: performance-focused debugging

On my portfolio I have a custom variant of the skill, specialized in bugs performance (LCP regressions, INP issues, slow SSR endpoint). Frontmatter illustrative:

---
name: debugging-performance
description: Use when investigating a performance regression (LCP > target,
  INP > 200ms, SSR endpoint slow). Drives a scientific loop focused on
  measurement first (real metrics from Lighthouse / CrUX), then hypothesis
  on cause, then test. Stops when measured metric returns under target.
metadata:
  type: rigid
---

The variant adds two steps to the main body:

1. "Measure first" - First cycle is always measurement of baseline (no assumptions).
2. Compare with target - Each subsequent cycle compares current measurement with explicit SLO target.

Without these two additions, the skill base tended to jump over the "cause hypothesis" without first measuring it well. The fixed variant sets the problem.

What I learned writing this article

The most surprising thing was how obvious the scientific method was to read, and how difficult it was to apply under pressure. I had read books on structured debugging years ago (Andy Hunt + Dave Thomas, the old "Pragmatic Programmer"), but in practice, I continued to skip steps when a bug was urgent.

The skill made a difference not for its content (which I already knew) but for the formTo have a clear procedure written by someone else to whom you must respond ("Have you formulated the single hypothesis? Have you written what you expect to see?") activates discipline better than good personal intention. It's strange to admit but it's so.

Avoided pattern

• Skip checkpoint quicklyThe temptation, after fixing the bug, is to not write the final checkpoint ("I've understood, let's move on"). Error: three months later, the same bug reappears in a slightly different form and you no longer remember the facts verified. Five minutes of checkpoint save you two hours of re-debugging.
• Unifiable Hypothesis"For the problem may be in the framework" is not a testable hypothesis. The skill teaches to rephrase: "If the problem is in the framework, the bug should disappear by downgrading to the previous version. Test: downgrade to 3.4.10 and verify." Now it's testable.

A story worth sharing

Placeholder Section If you have a bug that you've fixed with a scientific method (or one that still bothers you), write to me at federico@federicocalo.devThe history (pseudonymized, with consent) enters the next cluster.

Previous cluster: Brainstorming skill Next cluster: Test-Driven Development enforcement skill →