debugging-network-issues

Installation
SKILL.md

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) 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
macOS Tailscale ⨯ proxy/VPN conflict (Shadowrocket / Clash / Surge): tailscale ping works but SSH/curl/git fails, Connection closed by 198.18.x.x, TUN DNS hijack, ~60s getaddrinfo resolver stall tunnel-doctor
Cloudflare config: ERR_TOO_MANY_REDIRECTS, SSL-mode mismatch, DNS / proxy-status issues behind the orange cloud cloudflare-troubleshooting
Windows App / AVD / W365 RDP connection quality: WebSocket instead of UDP Shortpath, high RTT, STUN/TURN interference windows-remote-desktop-connection-doctor
Client-side proxy / VPN / TUN misrouting: one specific site fails with ERR_CONNECTION_CLOSED or SSL_ERROR_SYSCALL, other sites work, DNS returns fake/TUN IPs, and adding a PROXY rule did not help this skill — read references/case-proxy-tun-cname-override.md first
TLS certificate-verification errors (UNKNOWN_CERTIFICATE_VERIFICATION_ERROR, a cert for the wrong site) or mid-handshake EOFs on every DIRECT-routed/domestic domain at once, while proxied domains work — and any proxy health watchdog still reports green tunnel-doctor (TUN DIRECT split-brain step)
The proxy is reachable and the OS/Tailscale route is healthy, but bulk transfers are slow and changing the active exit/node changes the measured rate tunnel-doctor — proxy node / exit / chain capacity branch
Nothing errors — it is just slow. Every request returns 200, latency and health checks look fine, but transfers crawl, bulk jobs overrun their estimates, or files arrive truncated this skill — go straight to Step 0.7; the error-driven steps have nothing to bite on
Installs
531
GitHub Stars
1.4K
First Seen
Apr 27, 2026
debugging-network-issues — daymade/claude-code-skills