observabilitylisted

> Source: [addyosmani/agent-skills - skills/observability-and-instrumentation](https://github.com/addyosmani/agent-skills/tree/main/skills/observability-and-instrumentation), adapted. # Observability Instrumentation is written alongside the feature, the same way tests are. A feature that ships without telemetry turns its first bug into archaeology instead of a query. Not for diagnosing a failure happening right now: that is `/debug`. This skill is what makes `/debug` fast next time. ## Process **why-no-hook:** skill workflow guidance; each step requires understanding the surrounding context (repo, task shape, prior state). ### 1. Write the on-call questions first Telemetry without a question is noise. Before adding any instrumentation, write down 2-4 questions an on-call engineer will ask about this feature. ```text FEATURE: checkout payment retry QUESTIONS ON-CALL WILL ASK: 1. What fraction of payments succeed on first attempt vs after retry? 2. When a payment fails permanently, why? (provider error? timeout? validation?) 3. Is the payment provider slower than usual? ``` Every signal below must help answer one of these questions. If you cannot name the questions, you are not ready to instrument: you will log everything and learn nothing. ### 2. Pick the signal per question Metrics tell you **that** something is wrong. Traces tell you **where**. Logs tell you **why**. | Signal | Answers | Cost profile | | --- | --- | --- | | Structured log | "What happened in this