/fix-observability Skill

/fix-observability

Fix the highest priority observability gap.

What This Does

Invoke /check-observability to audit monitoring
Identify highest priority gap
Fix that one issue
Verify the fix
Report what was done

This is a fixer. It fixes one issue at a time. Run again for next issue. Use /observability for full setup.

Process

1. Run Primitive

Invoke /check-observability skill to get prioritized findings.

2. Fix Priority Order

Fix in this order:

P0: No error tracking, no health endpoint
P1: Sentry config, structured logging, alerting
P2: Analytics, console cleanup
P3: Performance monitoring

3. Execute Fix

No error tracking (P0):

pnpm add @sentry/nextjs
npx @sentry/wizard@latest -i nextjs

Or manual setup:

~/.claude/skills/sentry-observability/scripts/init_sentry.sh

No health endpoint (P0): Create app/api/health/route.ts:

export async function GET() {
  const checks = {
    status: 'ok',
    timestamp: new Date().toISOString(),
    // Add service checks as needed
  };
  return Response.json(checks);
}

Sentry misconfigured (P1): Add to .env.local:

NEXT_PUBLIC_SENTRY_DSN=your-dsn
SENTRY_AUTH_TOKEN=your-token
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

No structured logging (P1):

pnpm add pino

Create lib/logger.ts:

import pino from 'pino';

export const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
});

No alerting (P1): Create alert via Sentry CLI or scripts:

~/.claude/skills/sentry-observability/scripts/create_alert.sh --name "New Errors" --type issue

No PostHog analytics (P1):

Install dependency:

pnpm add posthog-js

Create analytics module from template:
- Source: ~/.claude/skills/observability/references/posthog-patterns.md
- Target: lib/analytics/posthog.ts
Create PostHogProvider:
- Target: components/providers/PostHogProvider.tsx
- If Clerk detected, include user identification integration
Update app/layout.tsx:
- Wrap children with <PostHogProvider>
- Place inside existing providers (ClerkProvider, ConvexClientProvider)
Add env vars to .env.example:

# PostHog [REQUIRED] - Product analytics
NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Verify setup:

pnpm dev
# Open browser, check PostHog debug mode shows events
# Check PostHog dashboard for incoming events

PostHog installed but not configured (P2): Add to .env.local:

NEXT_PUBLIC_POSTHOG_KEY=phc_xxx  # From PostHog project settings
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

4. Verify

After fix:

# Sentry works
~/.claude/skills/sentry-observability/scripts/verify_setup.sh

# Health endpoint works
curl -s http://localhost:3000/api/health | jq

5. Report

Fixed: [P0] No error tracking

Installed: @sentry/nextjs
Configured: sentry.client.config.ts, sentry.server.config.ts
Added: SENTRY_DSN to .env.local

Verified: Sentry SDK initialized

Next highest priority: [P0] No health endpoint
Run /fix-observability again to continue.

Branching

Before making changes:

git checkout -b infra/observability-$(date +%Y%m%d)

Single-Issue Focus

This skill fixes one issue at a time. Benefits:

Test each monitoring component independently
Easy to troubleshoot if something fails
Clear audit trail

Run /fix-observability repeatedly to work through the backlog.

/check-observability - The primitive (audit only)
/log-observability-issues - Create issues without fixing
/observability - Full observability setup
/triage - Production incident response

Agent Skills: /fix-observability

Install this agent skill to your local

Skill Files