docs(analyzer): phase 8 — operator runbook

docs/wulf-pulse-ticket-analyzer-runbook.md covers cost monitoring
queries, the $2 cost ceiling, IT Glue alias workflow, failure triage
(failed jobs vs needs_human_review), and manual ops (queue from psql,
force re-run, inspect model_traces). Calls out the manual migration
step for existing DBs and lists the unimplemented surfaces (no auto
retries, no viewed_at, no email_sent_at) so operators don't trip on
them. Linked from README.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
lorentz 2026-04-29 11:05:46 -04:00
parent ed3b363d02
commit 1c5ec0f947
3 changed files with 358 additions and 0 deletions

View file

@ -376,6 +376,44 @@ This file is updated after each phase ships.
---
## Phase 8 — Operator runbook
**Delivered**
- `docs/wulf-pulse-ticket-analyzer-runbook.md` — cost monitoring queries
(daily spend, top expensive analyses, multi-run tickets), the cost
ceiling explanation (`COST_CEILING_USD = 2.00` in `pipeline.ts`), the
IT Glue alias workflow (where to find org IDs, how to verify via
`model_traces.itglue.alias_used`), failure triage tables (failed jobs
vs. `needs_human_review` flagged completes, with the actual error
strings the worker emits), and a manual-ops section for queueing jobs
from psql.
- README.md "Documentation" section links the runbook so operators
finding the project for the first time discover it.
**Decisions worth flagging**
- **Runbook lives in `docs/`, not the README.** Per CLAUDE.md, long-form
per-feature docs go in `docs/` and the README points to them. Matches
the existing pattern (workflow-editor-guide, sync guides, etc.).
- **Manual migration step is documented.** Postgres only re-applies
migrations on first init — operators applying analyzer to an existing
DB need to run `psql -f migrations/069_*.sql`. The runbook leads with
this.
- **Listed what's *not* implemented.** Retries, `viewed_at`, share
`email_sent_at`, pre-Sonnet cost gate, share-recipient autocomplete.
Better to advertise the gaps than have an operator trip over them.
**Deliberately left out**
- No production-monitoring dashboard (Grafana etc.) — Pulse doesn't have
one for any other feature, and the SQL queries cover the same ground.
- No README expansion for the analyzer feature itself. Pulse's README is
intentionally short; the runbook + spec + build notes are the deep
docs.
---
## Status after each phase
| Phase | Tests | tsc | Notes |
@ -387,3 +425,4 @@ This file is updated after each phase ships.
| 5 | 128 | clean | API routes (no route tests) |
| 6 | 128 | clean | frontend (no FE tests) |
| 7 | 128 | clean | share email via existing SMTP transport |
| 8 | 128 | clean | operator runbook + README link |