/observability-audit

name: observability-audit
description: Audit code for observability gaps — debug logs left in, errors caught without being logged, missing context on log entries, untracked slow operations. Uses the app's existing observability tooling exclusively.

Observability Audit

Code that works locally but is impossible to debug in production. This skill finds and fixes observability gaps using whatever tools the app already has.

Step 0: Research existing observability tooling

Before anything else, explore the codebase to understand what's already in use:

• Error tracking: Sentry, Bugsnag, Rollbar, or similar?
• Logging: structured logger (Pino, Winston, Bunyan), cloud provider SDK, custom wrapper?
• APM / metrics: Datadog, New Relic, OpenTelemetry?
• Analytics: PostHog, Segment, Amplitude?
• Any custom `logger` or `telemetry` utilities?

Read how they're configured and how they're used in existing code. All fixes must use these — never introduce a new observability dependency or pattern.

What to look for

**Debug artifacts left in production code:**

• `console.log`, `console.debug`, `console.info` that aren't part of the established logging pattern
• Temporary logging added during debugging and never removed
• Commented-out log statements

**Errors that disappear:**

• `catch(e)` that propagates or re-throws without logging first — the error reaches the user but leaves no trace for debugging
• Errors logged with no context: `logger.error(e)` alone, with no info about what operation failed, what inputs were involved, or what the user was doing
• Errors tracked to the error tracker but without relevant metadata (user ID, request ID, relevant state)

**Missing context on log entries:**

• Logs that say what happened but not enough to reproduce it (no entity IDs, no relevant parameters)
• No correlation/request ID on logs in request-handling code
• Log entries that can't be connected to a specific user or session when that would be needed for debugging

**Untracked slow or critical operations:**

• External API calls with no timing logged on failure or when slow
• Database queries with no observability when they're critical path
• Background jobs or queues with no start/complete/fail tracking

Process

1. Research existing tooling (Step 0) — do not skip this 2. Identify the scope from the user's request 3. Find every instance of the anti-patterns above 4. Fix using the existing tooling and patterns 5. Remove debug artifacts, add context to thin logs, add tracking where missing 6. Report changes

Fix principles

• Every caught error should be logged with enough context to reproduce the problem
• Use the existing logger/tracker — never introduce a second one
• Debug `console.log` goes away entirely — no conversion to structured log, just deleted
• Log context should include: what operation, what failed, relevant IDs (user, entity, request)
• Don't add logging to every function — focus on boundaries (external calls, queue handlers, critical paths)

Reference files

• `references/observability-patterns.md` — Detection patterns, bad/fix examples for debug artifacts, missing logging, missing context, untracked operations. Read before starting the audit.

Report

Summarize by file: what was removed, what was added or improved, what context was missing and is now included.