wulf-pulse/docs/wulf-pulse-ticket-analyzer-build-notes.md

# AI Ticket Analyzer — Build Notes

A running journal of the multi-phase build for the AI Ticket Analyzer feature.
Captures what was delivered each phase, design decisions worth flagging, and
what was deliberately left out. Spec lives in
`wulf-pulse-ticket-analyzer-prompt.md`.

This file is updated after each phase ships.

---

## Phase 1 — Migration + Zod schemas

**Delivered**

- `migrations/069_create_analyzer_tables.sql` — three tables
  (`analyzer_analyses`, `analyzer_shares`, `analyzer_jobs`) with `pgcrypto`
  extension guard, indexes per spec, status `CHECK` constraints, and FK types
  corrected to `TEXT` (not `UUID`) to match Better Auth's `user.id`.
- `lib/types/analyzer.ts` — Zod schemas for every LLM-stage parsed JSON
  (`TaggedEvent`, `TriageResponse`, `DeepAnalysisResponse`, `OpusResponse`),
  persisted row shapes, job status, API request bodies, and the internal
  `PreprocessedTicket` payload that flows through the pipeline.

**Decisions worth flagging**

- `triggered_by_user_id` is **nullable + `ON DELETE SET NULL`** (not `NOT NULL`).
  An analysis should still be readable in history if the triggering user is
  later deleted. `analyzer_shares.shared_by_user_id` is `NOT NULL +
  ON DELETE CASCADE` (audit-log style — share rows go with the user).
- `evidence_timestamps` typed as `string().datetime({offset: true})` (ISO
  timestamps), not numeric indices. More robust to model hallucination and
  reads better in the UI.
- `TaggedEvent` does NOT support a "two separate events" form for time entries
  with both Summary + Internal Notes — single event with both fields, per the
  spec's preference for a cleaner timeline.

**Deliberately left out**

- Migration is committed but **not applied** to any running DB. Postgres only
  re-applies migrations on first init of a fresh volume; the existing DB needs
  a manual run of this migration when phase 5 is exercised.

---

## Phase 2 — Stage 0 pre-processor + IT Glue redaction

**Delivered**

- `lib/services/analyzer/itglue-redact.ts` — recursive walk; matches keys
  against `/password|secret|key|token|credential|api[_-]?key/i`; replaces
  values with `[REDACTED]`. Subtree redaction (key matching `auth` → no leaves
  leak), defensive copy, cycle guard (`[CIRCULAR]` marker).
- `lib/services/analyzer/preprocessor.ts` — filters workflow noise + Service
  Desk Notification rows, tags ticket_create/notes/time entries with
  `actor / actor_type / source / visibility / summary_notes / internal_notes /
  hours`, sorts chronologically, computes `sha256` content hash over canonical
  JSON of `(events, status, priority, queue)`.
- `vitest@^4.1.5` added as devDep with `vitest.config.ts` setting up the
  `@/` alias. Two test files at this phase: 32 redaction tests + 36
  preprocessor tests including the regression run against the
  `T20260424.0045` fixture.
- Type-aliasing fix in `lib/types/analyzer.ts`: added `export type X =
  z.infer<typeof X>` for `ActorType`, `EventSource`, `Visibility`, `Severity`,
  `ComplexityTier`, `TicketType` — the Zod-enum const exports alone don't
  produce a usable TypeScript type.

**Decisions worth flagging**

- `actor_type` is classified by **email domain, not author text**, per the
  spec. `lorentz@wulfconsulting.com` is `wulf_tech` regardless of how the
  message reads. Sonnet handles the role nuance at Stage 3.
- Time entries with no narrative content (no summary, no internal notes) are
  dropped — a purely numeric entry adds nothing.
- Vendor-domain allowlist is intentionally short and conservative (Vertafore,
  Datto, Microsoft, etc.). Misclassifying a customer domain as "vendor" is
  worse than the default `client_contact`.

**Deliberately left out**

- No real protection for secrets embedded in **free text** (e.g. a notes field
  containing the literal string "the password is hunter2"). The redaction
  guarantee is on field **keys**, not values. The IT Glue search test
  documents this contract explicitly so it isn't "fixed" without thought.

---

## Phase 3 — Anthropic SDK setup + Stage 1 (Haiku triage)

**Delivered**

- `lib/services/llm/{models,pricing,client,call}.ts` — model ID constants,
  per-model rate table (Haiku $1/$5, Sonnet $3/$15, Opus $5/$25 per 1M tokens
  + cache read/write tiers), lazy SDK singleton, generic
  `callLLMStage<T>({model, system, user, schema, maxTokens, client?})`
  helper that:
  - Marks the system prompt with `cache_control: {type: "ephemeral"}`
  - Sends NO `temperature`/`top_p`/`top_k` (Opus 4.7 would 400)
  - Strips a single ` ```json ` fence before parsing
  - On parse failure, retries **once** with prior-attempt + error in a
    follow-up user turn
  - Returns `{data, usage, estimated_cost_usd, attempts, raw_response}`
- `lib/services/analyzer/stages/stage1-triage.ts` — Haiku caller with the
  spec's verbatim system prompt and a 50KB user-payload cap that drops oldest
  internal-only events first when oversized.
- `lib/services/analyzer/itglue-search.ts` — search facade that runs every
  result through `redact()` before returning. Snippets capped at 2000 chars,
  doc count capped at 10. `itglue-aliases.json` skeleton for known fuzzy
  org-name mappings.
- 32 new tests across pricing/call/Stage 1/IT Glue search.

**Decisions worth flagging**

- **Manual JSON.parse + Zod validate, not `output_config.format` /
  `client.messages.parse()`.** The spec said retry-once on Zod parse failure,
  and Zod 4 ↔ JSON Schema conversion has edge cases I didn't want to depend
  on (e.g. `.datetime({offset: true})` → JSON Schema `format`). Manual parse
  is what the spec asks for and is more transparent.
- **Prompt caching probably won't fire on these stages.** Our system prompts
  are ~1-2 KB (~250-500 tokens); minimum cacheable prefix is 2048 (Sonnet) or
  4096 (Haiku/Opus) tokens. The `cache_control` marker is a no-op below
  threshold and incurs no cost — left in defensively, but caching is not a
  meaningful lever for this workload.
- **Redaction is on KEY names, not free text** — re-stated for emphasis. The
  IT Glue search test asserts this contract.
- **`itglue-aliases.json` is a skeleton** with `_comment` / `_example` keys
  documenting the format. Real org-id entries get added when phase 5 wires
  this into the pipeline.

**Deliberately left out**

- No live API integration test. All Stage 1 tests use a mocked `Anthropic`
  client. A real-API smoke test belongs in phase 5+ when we run end-to-end.
- Did **not** wrap `lib/services/itglue-client.ts` in a redacting search
  facade for non-LLM callers. The redaction primitive is ready; non-LLM
  callers (sync service, data browsers) intentionally have full data — they
  are not the path that needs protection.

---

## Phase 4 — Pipeline + Job worker (Stages 3, 4, 5)

**Delivered**

- `lib/services/analyzer/stages/stage3-deep-analysis.ts` — Sonnet caller,
  spec's verbatim prompt, 80KB payload cap.
- `lib/services/analyzer/stages/stage4-deep-reasoning.ts` — Opus caller plus
  pure helpers `shouldRunDeepReasoning()` and `applyOpusUpdates()`.
- `lib/services/analyzer/data-access.ts` — `loadTicketBundle(ticketNumber)`
  joins `tickets` / `statuses` / `priorities` / `queues` / `companies` /
  `contacts` / `resources` / `ticket_notes` / `time_entries` and returns the
  exact `RawTicketBundle` shape the preprocessor expects. Throws typed
  `TicketNotFoundError`.
- `lib/services/analyzer/persistence.ts` — `getNextAnalysisVersion`,
  `findExistingAnalysisByContentHash`, `insertAnalysis`, plus job
  `claimQueuedJob` / `updateJobStatus` / `completeJob` / `failJob` /
  `queueJob` / `getJob`. Job claim uses `FOR UPDATE SKIP LOCKED` so multiple
  Next.js workers can poll safely.
- `lib/services/analyzer/pipeline.ts` — composes Stage 0 → idempotency check
  → Stage 1 → (Stage 2 if `itglue_lookup_needed`) → Stage 3 → (Stage 4 if
  trigger fires AND cost ceiling not reached) → result. Cost circuit breaker
  trips at $2.00 before Opus, sets `needs_human_review=true` with a
  reason. Returns full `model_traces` for debugging.
- `lib/services/analyzer/worker.ts` — singleton with 2-second poll loop;
  auto-starts in production; opt-in in dev via
  `ANALYZER_WORKER_AUTOSTART=1`; **skipped** under vitest. `runJob()`
  exposed for tests + manual triggers. `TicketNotFoundError` produces a
  user-facing job error message that fingers the sync as the culprit.
- 28 new tests bringing the total to 128.

**Decisions worth flagging**

- **Worker auto-start is more conservative than `sync-scheduler.ts`.** That
  one auto-starts on any non-browser import (including tests). I gated this
  one because the worker hits the database AND runs LLM calls — much higher
  blast radius. To run locally, set `ANALYZER_WORKER_AUTOSTART=1`.
- **Cost circuit breaker only fires before Opus.** Sonnet runs unconditionally
  even if it would push past $2. Spec wording matches; if the team wants
  stricter control, the natural place is next to `COST_CEILING_USD` in
  `pipeline.ts`.
- **Idempotency check matches `status='complete'` only.** Failed runs don't
  poison the cache.
- **IT Glue failures are tolerated.** Search throws → analysis continues
  without context, doesn't fail the run.
- `worker.test.ts` casts `mockImplementationOnce` to `as never` because
  vitest's overload resolution fights us when the mocked function has multiple
  call signatures. Functional, just ugly.

**Deliberately left out**

- No live API integration test (still). Phase 5+ is the natural place for an
  end-to-end smoke test.
- Stage 3 doesn't have a fixture-driven happy-path test like Stage 1; it's
  exercised at the orchestration layer via `pipeline.test.ts` only. Worth
  adding direct Stage 3 tests later.
- Migration `069` still not applied — same as phase 1.

---

## Phase 5 — API routes

**Delivered**

- Persistence read paths added to `lib/services/analyzer/persistence.ts`:
  `getAnalysisById`, `listAnalysesByTicketNumber`, `listNeedsReview`,
  `createShare`, plus a shared `rowToPersistedAnalysis` row mapper.
- 6 routes under `app/api/analyzer/`:
  | Route | Method | Returns |
  |---|---|---|
  | `tickets/[ticketNumber]/analyze` | POST | `{status, jobId?, existingAnalysisId?}` |
  | `tickets/[ticketNumber]/analyses` | GET | `{analyses: PersistedAnalysis[]}` |
  | `jobs/[jobId]` | GET | `{job}` |
  | `analyses/[id]` | GET | `{analysis}` |
  | `analyses/[id]/share` | POST | `{share}` |
  | `needs-review?limit=&offset=` | GET | `{analyses}` |

**Decisions worth flagging**

- **Analyze runs preprocess inline.** The route does
  `loadTicketBundle → preprocessTicket → findExistingAnalysisByContentHash`
  synchronously to support the spec's `existingAnalysisId?` immediate
  response. The worker also runs this — duplicated work, but preprocess is
  fast (deterministic, one DB load) and the alternative (always queue,
  frontend polls to discover the short-circuit) is worse UX.
- **Email send deferred to phase 8** per the spec's delivery order. The share
  route persists the audit row and validates the recipient domain against
  `ALLOWED_SHARE_DOMAINS`. Until phase 8, share rows have `viewed_at = null`
  indefinitely.
- **`requireAuth()` everywhere — not `requireAdmin()`.** Any authenticated
  user can analyze a ticket they have access to. If `/needs-review` should
  be admin-only later, swap that one to `requirePermission('analyzer',
  'review')` once the permission map is decided.
- **No new permission entries added to `lib/permissions.ts`.** Adding scoped
  permissions for a feature still under build risks getting them wrong.
- Routes are NOT in `middleware.ts` `publicRoutes` — they require a session.

**Deliberately left out**

- No API route tests. The repo has zero `app/api/**/*.test.ts` files; the
  routes are thin orchestration on top of already-tested persistence. Adding
  integration tests means setting up a test harness for the auth helpers +
  Postgres, which is a separate effort.

---

## Phase 6 — Frontend pages

**Delivered**

- `components/analyzer/analyze-button.tsx` — `<AnalyzeButton>` with the full
  state machine: POSTs to the analyze endpoint, navigates straight to an
  existing analysis if `existingAnalysisId` came back, otherwise polls
  `/api/analyzer/jobs/:jobId` every 2s and renders stage labels (Queued →
  Fetching → Triaging → Searching IT Glue → Analyzing → Deep review → Done).
  5-minute hard timeout. Failures surface as toast errors. Supports `force`
  for explicit re-run.
- `components/analyzer/share-modal.tsx` — `<ShareModal>` with a shadcn Dialog
  + email field + optional note (max 2000 chars). POSTs to the share
  endpoint and surfaces server-side validation errors (domain not allowed →
  toast).
- `components/analyzer/analysis-view.tsx` — the full 10-section analysis
  layout per spec. Header with model-tier badges (Haiku/Sonnet/Opus pills),
  confidence score, total cost, Share + Re-analyze buttons. Summary, Next
  Step (with rationale collapsed), Timeline (vertical list with 🟢 / 🔒 /
  🔄 markers, click to expand), What Was Done / Should Have Been Done
  side-by-side on wide screens, Gaps colored by severity with "Evidence:"
  links that scroll-and-expand the matching timeline event,
  Post-Resolution (only if present), Human Review Flags (only if needed),
  IT Glue References.
- `app/analyzer/ticket/[ticketNumber]/page.tsx` — ticket detail with the
  Analyze button and a list of historical versions; latest is badged.
- `app/analyzer/analysis/[id]/page.tsx` — fetches one analysis and renders
  it via `<AnalysisView>`.
- `app/analyzer/queue/page.tsx` — needs-review queue, shows ticket number,
  version, summary preview, top reasons, confidence badge, and a `high gap`
  badge if any gap is high severity.

**Decisions worth flagging**

- **Imperative `useState` + `useEffect` + `fetch`**, no SWR / react-query —
  matches CLAUDE.md and the rest of the repo. Don't refactor to a global
  cache layer for these three pages; if it becomes a real pain, that's a
  whole-app concern.
- **`'use client'` everywhere.** The pages use `use(params)` (the React
  hook) to unwrap Next.js 16's `params: Promise<...>` shape on the client.
  Server components weren't appropriate here — every page does interactive
  state (analyze flow, expand events, share modal).
- **Stage labels render directly from `JobStatus` enum values**, not a
  separate label list, so any new statuses added to the enum auto-render
  with their default name.
- **Re-analyze banner not implemented yet.** The spec calls for "New
  activity since last analysis · Re-analyze" when the live content_hash
  drifts from the persisted one. That requires a live-preprocess endpoint
  (or running preprocess on the page render). Skipped for now — the user
  can always click Re-analyze. Worth adding once we have real-world signal
  on whether activity drift is common.
- **No autocomplete on the share-recipient field.** Spec says "autocomplete
  from existing wulf-pulse user list if available". Skipped — the existing
  user list is in Better Auth's `user` table; exposing it requires a
  small API endpoint. Easy follow-up.
- **No navigation entry yet.** `components/navigation/app-navigation.tsx`
  doesn't yet have an "Analyzer" link. Adding that is a one-line edit; I
  left it for the operator to opt in once the feature is staged.
- **Printable analysis view** — the spec mentions "printable" for the
  analysis page. The current layout is print-friendly by accident (no
  fixed sidebars, sectioned cards), but no explicit `@media print` styles
  yet. Add when someone asks.

**Deliberately left out**

- No frontend tests. vitest is configured for `lib/**/*.test.ts` only; the
  pages and components are visually verified. Component tests with
  testing-library would be a separate setup decision.
- Analysis view doesn't auto-refresh while a job is running on a
  *different* version. If a user navigates to an old version while a new
  one is in progress, they don't see the in-progress state. Acceptable —
  the queue view + ticket history give that signal.

---

## Phase 7 — Share-via-email integration

**Delivered**

- `sendAnalysisShareEmail()` added to `lib/services/email.ts` — re-uses the
  existing nodemailer SMTP transport that already serves magic-link and
  invitation mail. Subject `Pulse analysis · <ticket> v<n> — <summary
  excerpt>`, gradient-header HTML body matching the other Pulse emails, plain
  text fallback, `replyTo` set to the sharer so a recipient reply lands with
  the right person.
- Share route `app/api/analyzer/analyses/[id]/share/route.ts` now resolves
  the sharer's session, builds the analysis URL from `BETTER_AUTH_URL`
  (falling back to `NEXT_PUBLIC_BETTER_AUTH_URL`, then `localhost:3100`),
  persists the audit row, then attempts the email send.
- Share-modal frontend handles the new `emailSent`/`emailError` fields:
  success → green toast; row-saved-but-send-failed → orange `toast.warning`
  carrying the SMTP error.

**Decisions worth flagging**

- **Audit row persists even if email send fails.** The `analyzer_shares`
  row is the audit log, not just a delivery receipt. SMTP outages should
  not erase the record that the user attempted a share.
- **Response is HTTP 200 on email failure.** The route returns
  `{share, emailSent: false, emailError}`. A non-2xx would imply the share
  itself failed; surfacing `emailSent: false` is the more honest signal.
- **No `email_sent_at` column added.** Adding it requires a migration and
  a way to retry — neither is asked for by the spec. Send state lives only
  in the response and the server log line `[ANALYZER-SHARE] email send
  failed for share <id>`. If retries become a real need, a dedicated
  `analyzer_share_email_attempts` table is the natural shape.
- **Used existing nodemailer SMTP, not Graph sendMail.** Spec said "via
  M365 Graph using existing wulf-pulse mail integration if one exists;
  otherwise use a new module" — `email.ts` *is* the existing module. The
  Graph integration in this codebase is read-only (mailbox search, user
  reports), not send-capable.
- **HTML escaping is hand-rolled.** Five-replace function for
  amp/lt/gt/quote/apos. The user-controlled fields (sender name, note,
  analysis summary, next step) all flow through it. The repo has no HTML
  escaper utility and the magic-link/invitation emails don't need one
  because their inputs are URLs and admin-set names.

**Deliberately left out**

- **No retries.** A failed send is logged once and surfaced to the user.
  They can re-share if they want — that creates a fresh audit row, which
  is correct behavior.
- **No tests.** `lib/services/email.ts` has no existing tests, mocking
  nodemailer fully would add a non-trivial test scaffold for one
  function, and the share route is route-handler thin. Consistent with
  phases 5/6.
- **No `viewed_at` tracking yet.** The migration has the column but
  nothing writes to it. A `/share/:id/viewed` endpoint with an
  unguessable token would be the smallest addition; spec didn't ask, so
  skipped.

---

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

---

## Phase 9 — Ticket browser + analysis-view formatting

Reactive to first-use feedback: the analysis page Summary / Next Step
text was bare and dense, and there was no way to discover tickets to
analyze without typing the URL.

**Delivered**

- `<ProseText>` helper inside `analysis-view.tsx` — splits text on blank
  lines, renders each chunk as a separate `<p>` with `leading-7` and
  `whitespace-pre-line`. Applied to Summary, Next Step, Next Step
  rationale, and Post-Resolution Analysis. Single-paragraph text still
  renders cleanly.
- Summary + Post-Resolution headers got an uppercase tracking-wide
  treatment to act as section dividers, and body text bumped to
  `text-base text-foreground` so it reads as a finding rather than a
  caption.
- Next Step card now has a subtle `bg-primary/5` tint, an `ArrowRight`
  icon next to "Recommended Next Step", a stronger separator before
  the rationale collapsible, and the rationale itself renders in a
  bordered indented block.
- New `/analyzer/tickets` browse page — pill-style period chips
  (Today, Yesterday, This week, Last week, Last 30/60 days, All time),
  a client (company) Select, an issue-type Select, and a debounced
  free-text search across ticket_number/title. Compact table with
  per-row Analyze/Re-analyze button (reusing `<AnalyzeButton>`) and a
  "View" button shortcut to the existing analysis when one is
  recorded. Active-filter count + clear-all in the filter card header.
- New API `GET /api/analyzer/tickets/list` — filters by `period`
  (computed in Postgres against `last_activity_date`), `companyId`,
  `issueType`, `search`. Returns 50 rows + total via `COUNT(*) OVER ()`,
  plus `latestAnalysisId` from a LATERAL join into `analyzer_analyses`.
- New API `GET /api/analyzer/tickets/filter-options` — companies that
  have at least one non-deleted ticket (drops dormant accounts) +
  active issue types ordered by `sort_order, label`.
- Top-level "Analyzer" nav menu added to `app-navigation.tsx`, with
  "Browse Tickets" + "Needs Review". Earlier phases left this off
  intentionally; this phase opts in.

**Decisions worth flagging**

- **Period filters on `last_activity_date`, not `create_date`.**
  "Today" surfaces tickets that had activity today (new tickets,
  re-opened, status churn) — much more useful for an analyzer-driven
  triage flow than tickets created today. A new ticket created today
  also has activity today, so we don't lose those.
- **Period math runs in Postgres via `date_trunc('day', NOW())` etc.**
  Database server-clock = app-process clock for an internal Docker
  stack, so naive timestamps and naive `NOW()` agree. If users
  complain about edge-of-day drift, swap to
  `NOW() AT TIME ZONE 'America/New_York'` — Pulse's primary user base.
- **Default period is `last_30d`.** "All time" pulls many thousands of
  rows; defaulting wide-open hurts first-page latency. 30 days hits
  ~7K rows in our DB, paginates cleanly.
- **Per-row analyze button reuses `<AnalyzeButton>` directly.** Each
  row gets its own component instance — no shared state, the running
  state lives per-button. The button navigates on completion, which
  feels right: click Analyze, watch the stages, land on the analysis
  page.
- **`force=true` is set automatically on tickets that already have an
  analysis.** Re-analyze should re-run, not short-circuit to the
  cached row. The "View" button covers the cached path.
- **No Linear/JIRA-style multi-select filters.** Single-value Selects
  are simpler and match the rest of Pulse.

**Deliberately left out**

- **No saved views.** A filter URL is shareable, but there's no
  bookmark / saved-view UX. Add when someone asks.
- **No `latest_analysis_status` exposure.** A failed analysis doesn't
  show up — the LATERAL join filters by `status='complete'`. So a
  ticket whose only analysis failed looks like an un-analyzed ticket.
  Acceptable: re-running is the intended action there anyway.
- **Search is `ILIKE '%...%'`.** No tsvector / trigram index. 7K-row
  scans are sub-100ms in this DB; if the corpus grows past low six
  digits, swap in `pg_trgm`.

---

## Status after each phase

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 1 | 0 | clean | migration + types only |
| 2 | 68 | clean | redaction + preprocessor regression |
| 3 | 100 | clean | + LLM scaffolding + Stage 1 |
| 4 | 128 | clean | + pipeline + worker |
| 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 |
| 9 | 128 | clean | browse page + analysis-view formatting + nav entry |

---

# Phase 2 (cross-ticket analysis)

Spec: `docs/ticket-analyzer-phase2-spec.md`. Eight sub-phases delivered as
one Phase 2 push.

## 2.1 — Schema additions

**Delivered**

- Migration 070: `analyzer_stage_executions` table (per-stage I/O for
  every analyzer run, including failed attempts) + three columns on
  `analyzer_analyses`: `source_snapshot`, `aggregate_fingerprint`,
  `fingerprint_generated_at`.
- `model_traces` column annotated with a `LEGACY` `COMMENT ON COLUMN`
  for the SQL side and a `// LEGACY` doc comment in TS — kept for
  back-compat until aggregate reports have soaked.
- Zod schemas: `AggregateFingerprint`, `StageName`, `StageExecution`
  (read-back), `StageExecutionRecord` (write-time interface).

**Decisions worth flagging**

- `analyzer_stage_executions.analysis_id` starts NOT NULL in 070.
  Migration 071 (Phase 2.6) relaxes it and adds the
  mutually-exclusive CHECK with `aggregate_report_id`.
- 070 is idempotent (`IF NOT EXISTS` on every object) so re-running
  against an already-applied DB is safe.

## 2.2 — Pipeline writes to stage executions

**Delivered**

- `recordedStage(meta, fn, callbacks, outputSelector)` helper in
  `pipeline.ts` wraps each stage call, emits a `StageExecutionRecord`
  on success or failure (re-throws after recording). Pipeline wires
  it into Stage 1 (triage), Stage 3 (analyze), Stage 4 (deep_review).
  Stage 0 (preprocess) and Stage 2 (itglue) are recorded inline since
  they're not LLM calls.
- Pipeline result now includes `triage_response`, `sonnet_response`,
  `opus_response` for downstream stages (Stage 6 fingerprint).
- Worker's `runJob` collects records via `onStageRecord` callback,
  bulk-inserts them after `insertAnalysis` succeeds. On pipeline
  throw, worker captures the preprocessed bundle via `onPreprocessed`
  callback, persists a `status='failed'` analyzer_analyses row with
  source_snapshot intact, and bulk-inserts the partial stage records
  linked to it.
- New persistence functions: `bulkInsertStageExecutions`,
  `insertFailedAnalysis`, `updateAnalysisFingerprint`.

**Decisions worth flagging**

- **Failure-tolerant audit**: spec says "Every stage that runs MUST
  insert a row, including stages that fail." We persist a failed
  analyzer_analyses row even on pipeline crash so the partial stage
  records have a parent. Without this the FK would be orphaned.
- **Single bulk insert**: ~5–6 stage rows per pipeline run. One
  multi-VALUES INSERT is fast enough; no need for COPY.
- **`model_traces` double-write retained**: the legacy column still
  receives the old payload. Drop it in a future migration once
  aggregate reports have soaked through prod.

## 2.3 — Prose formatting

**Delivered**

- Stage 3 system prompt updated with the markdown formatting rules
  from the spec verbatim (banned filler phrases, action-verb
  emphasis, no headers).
- `react-markdown@10`, `remark-gfm@4`, `@tailwindcss/typography@0.5`
  added. Tailwind 4 plugin registered via `@plugin
  "@tailwindcss/typography"` in `app/globals.css`.
- `<AnalysisMarkdown>` component at `components/analyzer/analysis-markdown.tsx`
  renders prose with `prose prose-sm dark:prose-invert
  max-w-none prose-p:leading-7`. Coerces stray model headers into
  bold paragraphs (the prompt forbids them but defense-in-depth).
- `<ProseText>` removed. Summary, Recommended Next Step,
  next_step_rationale, and post_resolution_analysis all use
  `<AnalysisMarkdown>`.

**Decisions worth flagging**

- Tailwind 4 syntax: `@plugin "@tailwindcss/typography"` in CSS, no
  JS config needed.
- Stage 3 prompt change is back-compatible — old analyses with
  plain-text summaries still render fine through ReactMarkdown.

## 2.4 — Stage 6 fingerprint + backfill CLI

**Delivered**

- `lib/services/analyzer/stages/stage6-fingerprint.ts` — Haiku call
  with the spec's verbatim system prompt. Server-overrides
  `generated_by_model` and `generated_at` after parse so the model's
  guess for those fields can't drift.
- Worker integration: after `insertAnalysis` succeeds, run
  fingerprint with try/catch. Failure logs a warn, fingerprint
  stays NULL on the row, but the analysis is still complete and
  usable. The fingerprint stage record is added to the bulk insert
  whether it succeeded or failed.
- `scripts/backfill-fingerprints.ts` — idempotent CLI. Reads
  `analyzer_analyses.model_traces.{triage_response, sonnet_response,
  opus_response}` (which Phase 1 was already storing), runs Stage 6,
  writes `aggregate_fingerprint`. Supports `--dry-run` and
  `--limit=N`. Skips analyses where model_traces is incomplete.

**Decisions worth flagging**

- Stage 6 input is just the analysis content (triage + sonnet +
  optional opus). No `pre` payload needed — fingerprinting is about
  the produced *analysis*, not the source ticket.
- Backfill processes oldest-first (triggered_at ASC). Lets us
  observe a few rounds before chewing through hundreds.
- Stage 6 failure is non-fatal. Spec: "If fingerprinting fails, do
  NOT fail the overall analysis."

## 2.5 — Browse / filter UI rebuild

**Delivered**

- New endpoint: `GET /api/analyzer/tickets` (replaces the simpler
  `GET /api/analyzer/tickets/list` from Phase 1.9). Multi-select
  CSV-style query params (clientId, issueType, queue, status,
  priority, assignedTo); analyzed segmented filter (any/yes/no/stale);
  needsReview toggle; search; sort.
- `/api/analyzer/tickets/filter-options` extended with queues,
  statuses, priorities, resources (joined to "has at least one
  ticket" so the dropdowns aren't padded).
- New `<MultiSelect>` component at `components/ui/multi-select.tsx`
  — Popover + checkbox list with optional search box (auto-shown
  above 8 options). One trigger + one popover, no shadcn Command
  dependency.
- `/analyzer/tickets` page rebuilt:
  - Sticky filter bar with period pills, multi-selects, search,
    analyzed segmented, needs-review checkbox, sort
  - Active-filter chips (click to clear individual filter)
  - Bulk selection persisted via localStorage (key
    `analyzer:ticket-selection:v1`) — survives pagination
  - "Analyze N selected" — sequential job queue, forces re-analyze
    on `stale` rows
  - "Generate aggregate report" — routes to `/analyzer/reports/new`;
    only enabled when all selected are `current`
- Top nav reorganized: Browse Tickets / Aggregate Reports / Needs
  Review under "Analyzer".

**Decisions worth flagging**

- **Staleness via `last_activity_date > completed_at`**, not
  content-hash compare. The spec lets either; the date heuristic is
  good enough and avoids per-row preprocessing on 50-row paginated
  responses.
- **`MultiSelect` is a one-popover-per-instance design** — multiple
  popovers can be open across the bar. Acceptable; matches how
  Linear / Vercel's table filters behave.
- **No "Select all matching filters" semantic**. Selection is an
  explicit per-row action stored as ticket numbers in localStorage.
  Filter-level selection adds significant complexity (server has to
  resolve filter→IDs, two-modes everywhere). Skipped for V1; the
  spec's intent (don't lose selection on pagination) is met.
- **Bulk Analyze is sequential, not parallel.** N concurrent calls
  would all hit `claimQueuedJob` and the worker would process them
  one at a time anyway (single in-process worker). Sequential POSTs
  are more honest about that.

## 2.6 — Aggregate reports

**Delivered**

- Migration 071: `analyzer_aggregate_reports` table + ALTER on
  `analyzer_stage_executions` to drop NOT NULL on `analysis_id`,
  add `aggregate_report_id` FK, add the
  `analyzer_stage_executions_parent_check` CHECK constraint
  (`(analysis_id IS NOT NULL) <> (aggregate_report_id IS NOT NULL)`).
- `lib/services/analyzer/stages/aggregate-reduce.ts` — Sonnet (Opus
  opt-in) reduce stage with the spec's verbatim system prompt and
  `AggregateReduceResponse` Zod schema.
- `lib/services/analyzer/aggregate-persistence.ts` — `createAggregateReport`,
  `getAggregateReport`, `listAggregateReports`, `runAggregateReport`,
  `bulkInsertReportStageExecutions`. The runner is fire-and-forget
  (called via `void runAggregateReport(id)` from the POST endpoint);
  it persists distributions immediately so the UI can show partial
  results during the LLM call.
- IT Glue context fetcher: per-client `findOrganizationByName` +
  `getFlexibleAssets`, capped at 200 doc titles total per spec.
  Failure tolerant — per-client errors don't fail the report.
- API endpoints:
  - `POST /api/analyzer/aggregate-reports` — validates (≤100,
    fingerprint exists, not stale), creates pending row, fires runner
  - `GET  /api/analyzer/aggregate-reports/:id` — full report row
    (UI polls this every 3s while pending/running)
  - `GET  /api/analyzer/aggregate-reports` — paginated list
- Pages:
  - `/analyzer/reports/new?ids=T...,T...` — pre-flight: shows
    selected tickets, options (title, IT Glue context toggle),
    Generate button
  - `/analyzer/reports/[id]` — pending → distributions → completed.
    Sections: header, executive summary, four distribution mini-bar
    cards, documentation gaps (with `itglue_check` color tone),
    process gaps (severity tone), recurrence clusters, recommended
    actions (sorted by priority), narrative summary.
  - `/analyzer/reports` — table list of past reports

**Decisions worth flagging**

- **Fire-and-forget runner**, no separate worker module. The POST
  endpoint kicks `void runAggregateReport(id)`; updates land in the
  row when the LLM call completes. Frontend polls. Avoids adding a
  second polling worker alongside `analyzerWorker`.
- **Stage names reused for aggregate sub-stages.** The CHECK constraint
  on `analyzer_stage_executions.stage` enumerates the per-analysis
  stage names. Aggregate sub-stages (SQL aggregation, IT Glue context,
  reduce LLM) are recorded with `stage='analyze'` / `'itglue'` plus
  `aggregate_report_id` set. A future migration could add
  `aggregate_sql` / `aggregate_reduce` to the enum and re-emit those
  rows; for now the existing names are good enough for forensics.
- **`generated_by_user_id` is TEXT nullable**, not `uuid NOT NULL`
  per spec. Better Auth's `user.id` is text, and we want the report
  to remain readable if the generating user is later deleted —
  matches the pattern from `analyzer_analyses.triggered_by_user_id`.
- **Distributions persist before LLM call** so partial-state UI
  doesn't have to wait the full 30–90s for anything to render.

## 2.7 — Cost guards

**Delivered**

- Migration 072: `analyzer_cost_audit` table.
- `lib/services/analyzer/cost-guard.ts`:
  `estimateAggregateReportCost`, `getUserDailySpend`, `evaluateCost`,
  `recordCostAuditDecision`. Thresholds: `REQUIRES_CONFIRMATION_USD = 5`,
  `SOFT_WARN_DAILY_USD = 20`, `HARD_BLOCK_DAILY_USD = 50`.
- `evaluateCost` produces a four-state decision (`approved` /
  `requires_confirmation` / `blocked` / `overridden`) plus boolean
  `softWarn`/`hardBlocked`/`requiresConfirmation`/`isOverride`
  fields the API can return for UX.
- POST `/api/analyzer/aggregate-reports` enforces:
  - `requires_confirmation` → 400 with `requiresConfirmation:true,
    estimatedCost, dailySpendBefore` so the frontend can show
    `confirm()` and re-POST with `confirmedCost:true`.
  - `blocked` → 403 with the daily spend in the body.
  - Every decision (including `approved`) writes a row to
    `analyzer_cost_audit`.
- Override env var `ANALYZER_DAILY_COST_OVERRIDE_USERS`
  (comma-separated user ids).
- Frontend new-report page: catches `requiresConfirmation`,
  shows `window.confirm()` with the dollar figure, retries with
  `confirmedCost: true`.

**Decisions worth flagging**

- **Cost estimate is char/4 → tokens × Sonnet pricing.** Crude but
  pessimistic in the right direction. At 100 tickets the estimate
  comes in under $0.50 — far below the $5 threshold — so the
  confirmation modal almost never fires in practice. Ceiling exists
  to catch payload bloat / Opus-opt-in scenarios.
- **Daily window is trailing 24h, not "today UTC".** Avoids
  midnight-edge-of-day reset gaming; rolling window is what the
  spec calls "$X/day" naturally.
- **Soft warn at $20/day is informational only.** Fields exposed
  in the cost evaluation; UI can choose to surface, but the API
  doesn't refuse to proceed. Hard block at $50/day is the only
  enforcement.

## 2.8 — Documentation

**Delivered**

- `docs/wulf-pulse-ticket-analyzer-runbook.md` — added Phase 2
  sections covering stage execution forensics, fingerprint backfill,
  aggregate report flow + SQL queries, cost guard configuration +
  override env var, and the rebuilt browse UI behavior.
- This file — the per-sub-phase notes above.

---

## Status after Phase 2

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 2.1 | 128 | clean | schema (070) |
| 2.2 | 128 | clean | stage_executions writes + failure-tolerant persistence |
| 2.3 | 128 | clean | markdown rendering + Stage 3 prompt |
| 2.4 | 128 | clean | Stage 6 fingerprint + backfill CLI |
| 2.5 | 128 | clean | browse UI rebuild |
| 2.6 | 128 | clean | aggregate reports (071, runner, 3 endpoints, 3 pages) |
| 2.7 | 128 | clean | cost guards (072, audit log, threshold gating) |
| 2.8 | 128 | clean | runbook + build notes |