Network Issue Debugging
Apply falsification-first, layered isolation to pin down the responsible network layer for connection resets, SSE stalls, and fixed-time drops — instead of stacking assumptions.
"It fails after exactly 60 seconds" and "works sometimes" are bugs that waste hours when you guess. This playbook slows the reflex down and isolates the real layer with evidence.
Who it's for: backend engineers, SREs, network engineers, platform teams
Example
"My SSE stream dies after 130 seconds with RST_STREAM" → A layered experiment plan that isolates the responsible proxy/CDN layer and proves the cause
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add debugging-network-issues# Debugging Network Issues
Evidence-driven investigation methodology for incidents where the obvious cause is probably wrong. Built from a real 5-hour production case (see [references/case-sse-rst-130s.md](references/case-sse-rst-130s.md)) where assumption-stacking wasted hours that a 10-minute layered experiment would have resolved.
Apply this skill when the user reports a network/streaming/protocol symptom and the investigator feels tempted to diagnose from one log line or one circumstantial data point. The skill's job is to slow that reflex down.
## Triage first — is this a known domain?
Before applying the general methodology below, check whether the symptom points at a stack that already has a dedicated skill in this repo. Those carry the domain-specific symptom→cause→fix tables this skill deliberately stays general about — start there, and come back here for methodology if the root cause turns out to be elsewhere.
| If the symptom is… | Start with |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
Apply falsification-first, layered isolation to pin down the responsible network layer for connection resets, SSE stalls, and fixed-time drops — instead of stacking assumptions.
What's Inside
The template covers:
- Triage first — is this a known domain?
- Core principles
- Workflow
- Common cognitive traps
- Anti-patterns — things to explicitly avoid
- Case studies
Quick Start
Step 1: Create a Project Folder
Make a dedicated folder for this workflow and open it in Claude Code.
Step 2: Download the Template
Click Download above to save the template, then drop it into your project as CLAUDE.md (or paste it into your existing one).
Step 3: Start Working
Tell Claude what you need in plain language — it will follow the template's workflow automatically. For example:
My SSE stream dies after 130 seconds with RST_STREAM
Claude reads the template and runs the steps for you.