systematic-debugging

Diagnoses bugs through a four-phase root-cause investigation process before proposing fixes.

Updated Mar 3, 2026
One-click install
npx skills add https://github.com/manhthien2005/PM_REVIEW --skill systematic-debugging-manhthien2005
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/manhthien2005/PM_REVIEW/tree/main/tooling/.windsurf-template/shared/skills/systematic-debugging
Command: npx skills add https://github.com/manhthien2005/PM_REVIEW --skill systematic-debugging-manhthien2005

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers often jump straight to patching symptoms when a test fails or a bug appears, leading to wasted hours of guess-and-check fixes that never address the real cause. This Skill enforces a disciplined root-cause-first debugging workflow so fixes actually stick. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and verified implementation with a failing reproduction test. - Multi-Stack Tracing: Concrete guidance for tracing data flow across Flutter/Riverpod, FastAPI/Pydantic, Express/Prisma, Postgres, and FCM boundaries, including cross-repo request_id propagation. - Anti-Thrashing Guardrails: Red-flag detection and a hard stop after three failed fix attempts to force architectural re-evaluation. - Use Case: A FastAPI endpoint returns 422 in production. Instead of guessing, the Skill walks you through checking the Pydantic schema, router signature, and dependency order until the true cause is confirmed, then requires a failing test before the fix. ## Quick Start Use the systematic-debugging skill to investigate why my Prisma query returns empty results before suggesting any fix.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
How do I debug a bug systematically instead of guessing fixes?▼

Follow a four-phase process: investigate the root cause by reading the full error and tracing data flow, compare against working code, test one specific hypothesis with a minimal change, then implement the fix with a failing reproduction test. Never propose fixes before Phase 1 completes.

How to trace bugs across multiple services like Flutter, FastAPI, and Postgres?▼

Add a log or print statement at each component boundary, run once to find where the failure occurs, then focus investigation there. For cross-repo flows, propagate a request_id from the producer through downstream calls and grep each service's logs for that ID.

Why does my FastAPI endpoint return 422 errors?▼

A 422 usually means request validation failed. Check the Pydantic schema first for field name typos, type mismatches, or missing required fields, then verify the router signature and the order of Depends() dependencies.

What should I do when a fix attempt fails repeatedly?▼

Count your fix attempts. After three failed fixes, stop entirely because the architecture itself may be wrong, and discuss with the team before trying a fourth fix. Each failure should send you back to root-cause investigation with new information.

How do I handle flaky tests that pass intermittently?▼

Do not retry flaky tests; find the underlying race condition, shared state, or timing assumption. Common causes include a missing await in Dart or an unawaited mock in Python, so trace asynchronous execution carefully.