Fix Observability

/fix-observability

Fix the highest priority observability gap.

What This Does

1. Invoke /check-observability to audit monitoring
2. Identify highest priority gap
3. Fix that one issue
4. Verify the fix
5. 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:

1. P0: No error tracking, no health endpoint
2. P1: Sentry config, structured logging, alerting
3. P2: Analytics, console cleanup
4. 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):

1. Install dependency:

pnpm add posthog-js

2. Create analytics module from template:

   • Source: ~/.claude/skills/observability/references/posthog-patterns.md
   • Target: lib/analytics/posthog.ts

3. Create PostHogProvider:

   • Target: components/providers/PostHogProvider.tsx
   • If Clerk detected, include user identification integration

4. Update app/layout.tsx:

   • Wrap children with <PostHogProvider>
   • Place inside existing providers (ClerkProvider, ConvexClientProvider)

5. Add env vars to .env.example:

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

6. 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.

Related

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