Windsurf rules

1---
2name: wire-observability
3model: sonnet
4description: "Add structured JSON logging, observability commands, and idempotent setup scripts to a project. Use when a project needs production-readiness instrumentation, when user wants structured logging, or as a production-readiness gate at any phase of development."
5---
6 
7# Wire Observability
8> **HARD GATE** — **HARD GATE** — Observability is not optional. Before shipping, verify: structured logging is in place, key metrics are instrumented, error cases emit signals. 'We'll add metrics later' becomes 'never.'
9 
10 
11Add structured logging, observability commands, and idempotent setup scripts. Can be invoked at any phase — recommended at the end of the first working slice, before the first deploy.
12 
13## What this sets up
14 
151. **Structured JSON logging** — machine-readable logs for debugging and observability
162. **Observability commands** — how to check the system's health documented in CLAUDE.md
173. **Idempotent setup scripts** — scripts that can be run repeatedly without side effects
18 
19## Process
20 
21### 1. Assess current state
22 
23Check what's already in place:
24- Is there a logging library? (pino, winston, structlog, zap, slog, etc.)
25- Is logging JSON or plain text?
26- Is there a health check endpoint or command?
27- Are there setup scripts? Are they idempotent?
28 
29### 2. Add structured JSON logging
30 
31**For user-facing CLI output:** plain text is fine.
32**For everything else:** structured JSON.
33 
34Structured log entry format:
35```json
36{
37  "level": "info",
38  "timestamp": "2025-01-15T10:23:45.123Z",
39  "message": "User created",
40  "userId": "usr_abc123",
41  "requestId": "req_xyz789"
42}
43```
44 
45Guidelines:
46- Include `level`, `timestamp`, `message` in every entry
47- Add context fields relevant to the operation (userId, requestId, traceId)
48- Log at boundaries: HTTP requests in/out, DB queries, external API calls, background job start/end
49- Log errors with stack traces: `logger.error({ err, context }, "Operation failed")`
50- **Never log secrets, passwords, tokens, or PII**
51 
52### 3. Document observability commands in CLAUDE.md
53 
54Add an "Observability" section to the project's CLAUDE.md:
55 
56```markdown
57## Observability
58 
59| What | Command |
60|------|---------|
61| View logs | `<log tail command>` |
62| Health check | `<health check command>` |
63| Check DB connection | `<db ping command>` |
64| View metrics | `<metrics command>` |
65```
66 
67### 4. Write idempotent setup scripts
68 
69An idempotent script can be run multiple times and always produces the same result (no errors on re-run).
70 
71Pattern: check if the thing already exists before creating it.
72 
73```bash
74#!/usr/bin/env bash
75set -euo pipefail
76 
77# Idempotent: only create if not exists
78if ! psql -c &quot;SELECT 1 FROM pg_database WHERE datname = 'myapp'&quot; | grep -q 1; then
79  createdb myapp
80  echo &quot;Database created&quot;
81else
82  echo &quot;Database already exists, skipping&quot;
83fi
84```
85 
86Place setup scripts in `scripts/setup.sh` (or language-appropriate equivalent). Document the command in CLAUDE.md under Commands.
87 
88### 5. Verify
89 
90- [ ] Run the app and confirm JSON logs appear in the correct format
91- [ ] Run `scripts/setup.sh` twice — second run should produce no errors
92- [ ] Health check command returns success
93- [ ] No sensitive data in log output
94 
95## BCP Plus Integration
96 
97This skill maps to **BCP Plus dimension 11 (Quality Attributes)** — specifically performance, reliability, and availability instrumentation. Structured logging, health checks, and idempotent setup scripts are observable manifestations of quality-attribute requirements. The NFR Gate rule applies: standard-expectation items (e.g., "the app should log errors") score 0 with a one-line rationale; only above-standard quality requirements (e.g., p99 latency tracking, SLO-based alerting) contribute to the dimension 11 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern.
98