observability-first-debugging_skill

Overview

This skill teaches an observability-first debugging methodology that eliminates guessing and speculation. It shows how to add targeted instrumentation to gather the exact data needed to explain a failure. Emphasis is on evidence before hypothesis and observation before solution.

How this skill works

The skill walks through a reproducible protocol: reproduce the symptom, add logging/prints/assertions to reveal inputs, branches, and external responses, then run and inspect the captured output. Based on that evidence you form a testable hypothesis, run minimal experiments, and iterate until the root cause is found. It includes concrete techniques for command-line tools, code, network calls, file operations, and environment issues.

When to use it

• Investigating crashes, non-zero exit codes, or uncaught exceptions
• Troubleshooting failing tests or unexpected return values
• Diagnosing API errors, 4xx/5xx responses, or malformed payloads
• Finding missing files, wrong working directories, or path issues
• Debugging flakey or timing-dependent behavior (race conditions)

Best practices

• Reproduce and document the exact symptom before changing code (copy error messages and steps)
• Add observability first — print inputs, intermediate values, return values, and branch choices
• Make hypotheses only after you have evidence; your hypothesis must explain all observed facts
• Change one thing at a time and verify with instrumentation to know what fixed it
• Prefer simple, direct output (print/log/assert) over complex guessing; capture full request/response data for network issues

Example use cases

• A unit test reports "Expected 3, got undefined": add prints inside the test and target function to see where undefined originates
• API POST returns 400: log URL, headers, payload, status, and response body to find the malformed field
• FileNotFoundError: print cwd, directory listing, absolute path, and existence checks to reveal path mismatch
• Intermittent race condition: add entry/exit logs around suspected sections and timestamp outputs to observe ordering
• Deployment environment bug: log environment vars, PATH, and tool versions to spot configuration differences