typescript-systematic-debugging

Diagnose TypeScript backend failures by narrowing failure surfaces and selecting discriminating diagnostic steps.

1|1|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/GonkaGate/opencode-setup --skill typescript-systematic-debugging-gonkagate
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: typescript-systematic-debugging
Source: https://github.com/GonkaGate/opencode-setup/tree/main/.agents/skills/typescript-systematic-debugging
Command: npx skills add https://github.com/GonkaGate/opencode-setup --skill typescript-systematic-debugging-gonkagate

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Debugging TypeScript backend incidents often devolves into guessing fixes, shotgun changes, or premature root-cause claims. This Skill enforces a disciplined root-cause investigation method that turns vague symptoms into a named failure surface, competing hypotheses, and the single best next diagnostic step. ## Core Features & Use Cases - Failure Surface Classification: Localizes incidents across Fastify lifecycle, Prisma/PostgreSQL, Redis, external HTTP integrations, streaming/workers, reliability, performance, and observability seams. - Hypothesis Discrimination: Maintains 2-4 competing mechanisms with explicit falsification criteria and picks the next probe with the highest discriminating power and lowest blast radius. - Root-Cause Quality Bar: Distinguishes triage plans, leading hypotheses, measurement gaps, and confirmed root causes before any fix direction is suggested. - Use Case: When a production API intermittently returns 503s under load, use this Skill to separate Prisma pool wait from slow SQL, retry amplification, and readiness misconfiguration before changing any timeout or pool setting. ## Quick Start Ask the AI to systematically debug why your Fastify endpoint intermittently times out, naming the failure surface, leading hypotheses, and the single next diagnostic step.

Frequently Asked Questions about typescript-systematic-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug intermittent timeouts in a TypeScript backend?

Start by normalizing the symptom: when it happens, under what load, and in which phase (startup, request path, streaming, shutdown). Then classify the first likely failure surface, build 2-4 competing hypotheses, and pick the one diagnostic step that best separates them before changing anything.

How to tell Prisma pool exhaustion from slow SQL queries?

Prisma error P2024 indicates pool wait saturation, not slow SQL. Compare connection queue wait time against actual query execution time; raising pool_timeout usually worsens tail latency instead of fixing the underlying contention.

Why does my Fastify handler keep running after a timeout?

Fastify's handlerTimeout returns 503 but does not stop work by itself. It aborts request.signal, and cancellation is cooperative, so downstream I/O that ignores the signal continues running in the background.

Does this debugging method work for Redis and streaming issues?

Yes, it covers Redis readiness versus state-protocol bugs, TTL semantics, and script reply shapes, plus streaming concerns like client abort versus server stall, backpressure from ignored write() returning false, and double response ownership.

When should I not claim a root cause for an incident?

Do not claim root cause until the failing surface is named precisely, the mechanism explains timing, the trigger is identified, and the strongest nearby alternative was addressed. Otherwise report a triage plan, leading hypothesis, or measurement gap.