| name | observability-baseline |
| description | Scaffold-time observability so a shipped product is not blind in prod from day one — error capture (Sentry), request-id structured logging, and /healthz + /readyz endpoints. stack-baseline pins Sentry but nothing wires it; this is the wiring. Loaded by app-scaffolder (bake into the scaffold), infra-provisioner (prod env + probes), and consumed by l3-support (traces) and devops (deploy gate). |
| when_to_use | Apply when:
- app-scaffolder is generating a new product (any archetype that runs as a service)
- infra-provisioner is setting prod env vars + health probes
- l3-support needs traces/logs to triage an incident
Do NOT apply to:
- pure library / cli archetypes with no running service
- static marketing sites with no backend
|
| effort | medium |
| allowed-tools | Read, Write, Edit, Grep, Glob |
| paths | ["src/**","app/**","docs/infra/**"] |
observability-baseline
stack-baseline names Sentry and wires it nowhere — so every shipped product's first
prod incident is invisible, and l3-support triages blind. This skill makes three
things exist at scaffold time. Defaults baked in; no founder question.
1. Error capture (Sentry)
instrumentation.ts (Next.js) / SDK init at process start; DSN from SENTRY_DSN
env (never hardcoded).- CI uploads source maps on release so stack traces are readable (release = git sha).
- Capture unhandled rejections + a global error boundary on the client.
2. Request-id structured logging
- A logger that emits JSON (not
console.log prose) with a per-request
request_id (generate at the edge, propagate via header/async-local-storage).
- Levels: error / warn / info / debug — diagnostics go to stderr, never mixed
into user-facing stdout. (Same discipline as the CLI logging gap, DEEPEN d94.)
- One log line per request with: request_id, method, path, status, latency_ms.
3. Health endpoints
GET /healthz — liveness (process up). GET /readyz — readiness (deps reachable:
db, cache). Cheap, unauthenticated, no PII.- These are what infra-provisioner probes and what a load balancer checks.
Wiring (a skill is shelfware unless a consumer loads it)
| Consumer | What it does with this skill |
|---|
| app-scaffolder | bakes instrumentation.ts + the JSON logger + /healthz+/readyz into the generated app; adds SENTRY_DSN to .env.example |
| infra-provisioner | sets SENTRY_DSN in the prod env list; points the platform health probe at /readyz; records the Sentry project in PROVISION |
| l3-support | first triage step reads Sentry + the request-id logs (a trace now exists to read) |
| devops | deploy gate fails if /readyz doesn't return 200 post-deploy |
Output
A scaffolded app where the first prod error is captured, every request is traceable
by id, and the platform can health-check it. Record the Sentry project + endpoints
in docs/infra/PROVISION-{slug}.md. Done = the three pieces exist AND are wired
into the prod env, not just present in code.
