web-observability

# Web Observability Plugin

Teaches Claude how to instrument web apps correctly — what to measure, what context to attach, and what mistakes to avoid.

## The Problem

Most web teams instrument poorly:

- **Too little** — Can't debug production issues
- **Too much** — Noise, cost, performance impact
- **Wrong context** — Errors without enough data to act on

This plugin teaches Claude to capture both **user intent** (what they tried to do) and **system state** (browser conditions, errors, performance) so you can answer *"Why did this fail, and for whom?"*

## Installation

```bash
claude plugin marketplace add caleb-davis-plugins/web-observability
claude plugin install web-observability
```

## Usage

### Commands

```
/instrument
/audit src/features/checkout
```

### Natural Prompts

```
"How should I instrument this checkout flow?"
"What's wrong with my Core Web Vitals?"
"Set up session replay with Sentry"
"Review this code for observability anti-patterns"
"Track this user journey from signup to first purchase"
```

## Commands

| Command | Description |
|---------|-------------|
| `/instrument` | Generate prioritized instrumentation plan for React, Vue, Angular, Svelte, etc. |
| `/audit [path]` | Scan existing code for instrumentation gaps and anti-patterns |

## Agents

### codebase-analyzer

Explores web codebases to understand architecture and identify instrumentation opportunities.

**Focus Areas:**
- Framework and meta-framework detection (React, Next.js, Vue, Nuxt, etc.)
- Existing telemetry SDK inventory
- Routing, state management, data fetching patterns
- Key user flows and entry points

**Output:**
- Framework summary with version
- Architecture pattern identification
- Existing SDK coverage assessment
- Gap analysis with priority ranking

### instrumentation-reviewer

Reviews code changes for observability issues before they ship.

**Focus Areas:**
- Anti-patterns (PII leaks, high cardinality, blocking main thread)
- Missing context (no user ID, no route, no session)
- Naming consistency
- Vendor best practices

**Output:**
- Issues by severity with file:line references
- Specific fixes with code examples
- Vendor guideline references

## Skills

11 skills that activate automatically based on context:

| Skill | Trigger |
|-------|---------|
| `instrumentation-planning` | "What should I measure?" |
| `core-web-vitals` | "LCP is slow", "Fix CLS" |
| `error-tracking` | "Set up error boundaries" |
| `source-map-setup` | "Configure source maps" |
| `route-transition-tracking` | "Track page navigation" |
| `api-tracing` | "Trace API requests" |
| `session-replay` | "Set up session replay" |
| `user-journey-tracking` | "Track user funnels" |
| `hydration-performance` | "SSR hydration is slow" |
| `bundle-performance` | "JavaScript is blocking" |
| `synthetic-monitoring` | "Set up Lighthouse CI" |

## Frameworks Supported

| Framework | Guide |
|-----------|-------|
| React | `references/frameworks/react.md` |
| Next.js | `references/frameworks/nextjs.md` |
| Vue 3 | `references/frameworks/vue.md` |
| Nuxt 3 | `references/frameworks/nuxt.md` |
| Angular | `references/frameworks/angular.md` |
| Svelte | `references/frameworks/svelte.md` |
| SvelteKit | `references/frameworks/sveltekit.md` |
| Remix | `references/frameworks/remix.md` |
| Astro | `references/frameworks/astro.md` |

## Platforms Supported

| Platform | Guide |
|----------|-------|
| Sentry | `references/platforms/sentry.md` |
| Datadog RUM | `references/platforms/datadog.md` |
| New Relic | `references/platforms/newrelic.md` |
| LogRocket | `references/platforms/logrocket.md` |
| FullStory | `references/platforms/fullstory.md` |
| PostHog | `references/platforms/posthog.md` |
| Vercel Analytics | `references/platforms/vercel-analytics.md` |
| OpenTelemetry | `references/platforms/opentelemetry.md` |

## When to Use

**Use this plugin for:**
- Adding observability to a new or existing web app
- Setting up error tracking, performance monitoring, or session replay
- Improving Core Web Vitals (LCP, INP, CLS)
- Choosing between vendors (Sentry, Datadog, LogRocket, etc.)
- Reviewing instrumentation code for anti-patterns

**Don't use for:**
- Mobile app observability (use `mobile-observability` plugin)
- Backend/server observability
- General logging questions unrelated to web frontend

## Architecture: Context Engineering

This plugin follows Anthropic's best practices for token-efficient context loading:

### JIT Reference Loading

References are loaded only when needed, not upfront:

| Tier | When to Load | Files |
|------|--------------|-------|
| Never | Skills are self-contained | - |
| On detection | Framework/SDK unclear | `references/framework-detection.md`, `references/telemetry-detection.md` |
| On flagging | Reporting anti-patterns | `references/anti-patterns.md` |
| On implementation | Generating code | `references/frameworks/*.md`, `references/platforms/*.md` |
| On code generation | Specific templates | `templates/*.ts` |

### Single Source of Truth

| Concern | Canonical File |
|---------|---------------|
| Anti-patterns | `references/anti-patterns.md` |
| Framework detection | `references/framework-detection.md` |
| Telemetry detection | `references/telemetry-detection.md` |

### Slim Definitions

| Component | Target Lines | Focus |
|-----------|-------------|-------|
| Agent | 60-100 | Behavior, not data |
| Skill | 50-70 | Principles, reference templates |
| Command | 60-70 | Orchestration only |
| Hook | 1 prompt | Short, reference docs |

## Directory Structure

```
web-observability/
├── commands/       # /instrument, /audit (thin orchestrators)
├── agents/         # codebase-analyzer, instrumentation-reviewer
├── skills/         # 11 instrumentation skills (principles only)
├── hooks/          # Single consolidated anti-pattern hook
├── templates/      # Production-ready code templates
└── references/     # JIT-loaded guides (frameworks, platforms, patterns)
```

## Philosophy

1. **Start with Core Web Vitals** — LCP, INP, CLS are Google's ranking factors
2. **Context over volume** — One error with full context beats 100 without
3. **User intent + system state** — Link what users tried to do with browser conditions
4. **Avoid anti-patterns early** — PII leaks and high cardinality are expensive to fix later
5. **Don't block the main thread** — Telemetry that hurts INP defeats the purpose

## Author

[Caleb Davis](https://github.com/calube)

## License

MIT — see [LICENSE](LICENSE)