debug-root-cause

Topics in the source

• Debug: Root Cause First
• 1. Reproduce
• 2. Read the error properly
• 3. Hypothesize, then prove
• 4. Fix at the root
• 5. Prevent regression
• 6. Report

The most common debugging failure is patching the symptom. This skill forces a reproduce → hypothesize → prove → fix loop. Get the exact failing command (test, script, request). Run it yourself and capture the full output. If it doesn't reproduce, stop and gather info: environment, versions (node -v, python --version, lockfile), input data, env vars. Don't fix what you can't see. Make the reproduction as small and fast as possible (a single test, pytest path::testname -x, npx vitest run file -t "name"). Read the whole stack trace. The first frame in the user's own code (not nodemodules / site-packages) is usually where to look. Read the actual code at those lines, plus callers. Common decoders: Cannot read properties of undefined (reading 'x') / AttributeError: 'NoneType' → something upstream returned nothing; find where the value came from. ERRMODULENOTFOUND, ModuleNotFoundError → path, ESM/CJS mismatch, virtualenv not active, missing dependency. UnhandledPromiseRejection, RuntimeWarning: coroutine was never awaited → missing await. Works locally, fails in CI → env vars, timezone, file ordering, node/python version, test isolation. Flaky → shared state between tests, time, randomn

This is an excerpt. Refer to the complete source and its current requirements.