# Design: ResolutionFlow GTM — Escalation-Mode-First Wedge

Generated by /office-hours on 2026-04-26
Branch: main
Repo: chihlasm/resolutionflow
Status: APPROVED
Mode: Startup

## Problem Statement

ResolutionFlow is a multi-tenant SaaS troubleshooting platform for MSPs, currently
in Go-to-Market Validation (pre-PMF). The backend is feature-complete (55+ endpoints,
100+ tests, FlowPilot telemetry baseline accruing). The product has users but no
paying customers.

The blocker is not engineering completeness. The blocker is the absence of a sharp
GTM story tied to a number a buyer can verify. The session reframed the wedge twice
before landing on the real one.

**What ResolutionFlow actually is:** the structuring layer between conversational AI
and the way MSP techs work tickets. AI is great at producing answers; it is bad at
producing workflow-shaped output. ResolutionFlow gives the tech the AI they already
trust (Claude/GPT) but organizes the output into actionable structured steps,
records the session, captures customer-specific context, and turns the result into
PSA-formatted ticket notes — and optionally a runbook — without the tech writing
anything.

**Positioning line:** "the senior engineer looking over your shoulder."

## Demand Evidence

The founder is the first user. Senior Systems Engineer at an MSP, losing ~20
hours/week to cross-domain interruptions (systems engineer pulled into networking
problems and vice versa). At least 4 interruptions per day, with the time cost
concentrated in the gap between AI-conversation output and MSP-ticket workflow.

This is solving-your-own-problem demand evidence — strongest possible signal at
this stage. The 20 hrs/week figure is the founder's own time, not a hypothetical.
Every MSP shop with a senior tech and a junior tech has a version of this problem.

Telemetry signal (Phase 0.5 baseline accruing): captured flows pile up but are not
being re-used. This says capture works, retrieval doesn't — which means the
"hours-saved-via-re-use" number isn't yet generatable from existing data. The
GTM-grade ROI story needs a different metric until re-use lands: minutes recovered
per escalation, generated by Approach A below.

## Status Quo

MSP techs today resolve tickets via three workarounds:

1. **AI in a tab.** Junior tech opens Claude or ChatGPT, pastes the problem, gets a
   wall of prose, parses it into action items in their head, executes, repeats. AI
   does the diagnostic work. The tech does all the structure-extraction and
   ticket-note-writing afterward.

2. **Tribal knowledge.** Junior tech pings senior in Slack. Senior tech is
   interrupted (4+ times/day per the founder's own data). Context handoff is verbal
   and lossy.

3. **Stale runbooks.** Half-maintained Notion / IT Glue / SharePoint pages that
   nobody trusts because they're 18 months out of date and don't match the current
   customer environment.

The cost of these workarounds for the founder personally: ~20 hours per week of
senior-tech time lost. For a 5-tech MSP, the equivalent is 1 full FTE worth of
senior-engineer hours leaking into context-switching and tab-hopping.

## Target User & Narrowest Wedge

**Target user:** Senior Systems Engineer at a small-to-mid MSP (5-20 techs). The
founder is exemplar #1. Buying authority is shared between senior tech (champion)
and MSP owner (signs the check).

**Narrowest paid wedge:** Escalation Mode. Single sharp feature. When a junior tech
escalates a ticket they were working in FlowPilot, the senior tech opens the ticket
and sees the entire structured session state — every step the junior tried, every
dead end, every command output — instead of starting with "tell me what you tried"
for five minutes.

Why this is the wedge:

- **Two metrics, not one** (revised after /codex review 2026-04-27):
  - **Manual baseline** (the Assignment, weeks 0-2): senior tech stopwatches the
    next 5 escalations. T1 (first diagnostic action) − T0 (open ticket) under
    today's verbal-handoff workflow. This is the "what you currently lose" number.
  - **In-product metric** (telemetry, week 3+): time-to-first-action after claim,
    derived from `ai_session_step` rows where `created_at > SessionHandoff.claimed_at`
    AND `user_id = SessionHandoff.claimed_by`. This is the "what it is now with
    structured handoff" number.
  - **The savings claim** = manual baseline − in-product metric. Quote both
    explicitly in pilot conversations. Do NOT roll the in-product number alone
    into "minutes recovered" — that's an apples-to-oranges miscount Codex caught
    in the cross-model review.
- **Single-feature demo:** a 2-minute Loom shows the magic moment — junior hits
  escalate, senior window opens with full structured context. No theory required.
- **Cross-buyer story:** sells to senior tech (less interruption) AND owner (junior
  techs resolve faster, take more accounts).
- **Hours-saved math is simple:** 4-5 minutes per escalation × 15-30 escalations
  per week per senior tech = 1-2 hours/week recovered per senior. At $80-150/hr
  fully-loaded senior tech cost, the tool pays for itself with one customer.

## Constraints

- **One-founder shop.** Cannot run three concurrent product narratives. Sequence
  matters more than scope.
- **Pre-PMF runway implied.** 4-8 week build cycles before talking to a buyer are
  expensive. Approach A's 1-2 week timeline is the binding constraint.
- **Existing architecture is mostly aligned.** FlowPilot, unified_chat_service,
  FlowProposal, ConnectWise PSA integration — most of the pieces exist. Risk is
  positioning and UX, not capability.
- **PSA copilot competition is real.** ConnectWise / Autotask / Halo are racing to
  ship AI features. The wedge has to be sharp because we lose on distribution.

## Premises

The five load-bearing claims this design rests on, all confirmed in session:

1. **Diagnostic AI is commoditized.** ResolutionFlow does not compete on
   "AI solves the ticket faster." That race is over. ChatGPT/Claude already won.
2. **The structuring layer is the wedge.** AI conversational output is too dense
   and unstructured for active troubleshooting. ResolutionFlow's value is
   organizing that output into actionable, separable, recorded steps.
3. **Escalation context is the killer feature.** "Junior hits escalate, senior gets
   full structured context in 30 seconds instead of 5 minutes" is the sharpest
   demoable moment in the entire product surface.
4. **First paying customer is bottom-up, prosumer-flavored.** Senior tech at a
   small MSP, $20-50/seat/month, monthly billing. Owner-targeted enterprise
   pricing waits until 5+ paying shops establish baseline ROI numbers.
5. **Distribution is MSP communities, not paid SaaS ads.** r/msp, MSPGeek, RocketMSP,
   PSA marketplace listings. The channel matches the buyer.

## Approaches Considered

### Approach A: Escalation Mode first (REDUCED SCOPE per /plan-eng-review)

Lead the GTM with the killer feature. Polish the escalate-with-context handoff:
junior tech mid-session hits escalate, senior tech window opens with full
structured session state. 2-min demo Loom. Pilot with **3 MSPs** in the founder's
network (capped at 3 to preserve build capacity for B). Metric: minutes recovered
per escalation.

**SCOPE REDUCTION (2026-04-27 eng review):** ~80% of Approach A is already built.
The original 2-3 week estimate assumed greenfield. Codebase audit confirms:

| What the doc said "build" | What actually exists |
|---|---|
| Session-state serialization | `ai_session.escalation_package` (JSONB), `SessionHandoff.snapshot` |
| Senior-tech inbox | [EscalationQueuePage.tsx](frontend/src/pages/EscalationQueuePage.tsx) + [EscalationQueue.tsx](frontend/src/components/flowpilot/EscalationQueue.tsx) |
| Claim workflow | [handoff_manager.py:123 claim_session()](backend/app/services/handoff_manager.py#L123) |
| API surface | [session_handoffs.py](backend/app/api/endpoints/session_handoffs.py) — POST /handoff, /claim, GET queue |
| AI assessment for senior | `_generate_ai_assessment()` in handoff_manager |
| PSA round-trip | `escalation_package_markdown`, `escalation_package_external_id` |

**Real engineering scope (~6-9 days):**

1. **Notification dual-path** (4-5 days). `notification_sent` flag is a dead column —
   never written. Wire two channels in `handoff_manager.create_handoff`:
   - **Email** (existing `EmailService.send_notification_email`) — handles offline seniors.
   - **WebSocket / SSE push** to the EscalationQueue for live demo magic moment.
   - Set `notification_sent=true` after dispatch confirmation.
   - Graceful degradation: handoff still created if notification raises (regression test required).

2. **Hero metric endpoint** (~2 hours). New `GET /api/v1/analytics/escalation-metrics`,
   account-scoped, role-gated to `require_engineer_or_admin`. Computes
   *minutes recovered per escalation* by querying:
   ```
   ai_session_step.created_at (first row by senior_tech_user_id where created_at > SessionHandoff.claimed_at)
   minus
   SessionHandoff.claimed_at
   ```
   Returns a rolling-30-day average per account. No schema change.

3. **UX polish on EscalationQueue + receiving-engineer view** (2-3 days). Confirm the
   magic-moment screen lands when senior clicks claim. Add an unread indicator on
   the queue. Wire optimistic insert when SSE event arrives.

4. **Loom + landing page copy** (1-2 days). Non-engineering. Outside this plan's scope
   but required for the GTM in week 3.

**Test plan:** 100% coverage of new paths — 13 tests including 4 e2e and 1 regression
(graceful-degradation when notification dispatch raises). Test plan artifact at
`~/.gstack/projects/chihlasm-resolutionflow/abc-main-eng-review-test-plan-20260427-000000.md`.

**Risk:** Low. Single feature, single metric, architecture-aligned. The dual-path
notification is the only mildly novel surface; both halves use existing infra.

**Reuses:** `services/handoff_manager.py`, `services/escalation_package_generator.py`,
`models/session_handoff.py`, `models/ai_session.py`, `services/notification_service.py`,
`models/notification_log.py`, EmailService, EscalationQueuePage + EscalationQueue.

### UI Specifications (locked by /plan-design-review 2026-04-27)

**Magic-moment screen** (new, after Pick Up click): dedicated handoff-context view that
loads BEFORE the regular FlowPilot session view, then dissolves on first senior action.
Four sections, single frame:

1. **Problem summary** (top, 2-3 lines): junior's framing. Bricolage Grotesque h2.
2. **What's been tried** (left or middle column): structured list of `dead_ends_flagged[]`
   and `steps_attempted[]` from `escalation_package` JSONB. Card-flat surface, IBM Plex.
3. **AI assessment** (right column): `ai_assessment_data` rendered as 3 fields —
   `likely_cause`, `suggested_steps[]`, `confidence`. accent-dim badge for confidence.
4. **Start here** (primary CTA, electric-blue, ≥44px touch target): opens FlowPilot
   session at the most-likely-next-step. Senior typing or clicking anywhere triggers
   200ms fade-out and FlowPilot view fades in. Re-openable via "Show handoff context"
   ghost button in FlowPilot toolbar.

**Hero metric ("minutes recovered per escalation"):** lives in TWO places:
- **Queue stat-card** (above EscalationQueue list on /escalations): compact, "X.X hrs
  saved this month" + "click for details" affordance. Refreshes on queue load.
- **Dedicated `/analytics/escalations` page** (owner-facing): trend chart (4-week
  rolling), per-tech breakdown, per-problem-domain segmentation. Engineer-or-admin
  role-gated.

**Real-time arrival visual** (when WebSocket pushes a new escalation):
- New card slides in from above the list, 200ms ease-out CSS transition.
- Browser tab title prefixes with " (1) " / " (N) " when tab is backgrounded; clears
  on focus.
- No sound. MUST respect `prefers-reduced-motion: reduce` (slide-in collapses to
  instant fade-in).

**Unread state:** subtle 6px dot in top-right corner of card for escalations the
current senior has never opened. Dot fades on first hover or click.

**Race-condition (two seniors click Pick Up simultaneously):** loser sees a toast
"Already claimed by [name] 2s ago" via existing `@/lib/toast`; the card flashes the
winner's name in the meta row for 1s, then dissolves from the loser's view via
optimistic update + WebSocket reconciliation.

**Unread state (Codex correction 2026-04-27):** dot indicator clears on **open,
claim, or explicit dismiss** — NOT on hover. Hover-to-clear is a bad proxy for
acknowledgment because incidental mouse movement creates false clears.

**Notification routing (Codex finding 2026-04-27):** v1 fans out the email + push
to **all engineer-or-admin role users in the same account_id as the SessionHandoff**.
No on-call/round-robin logic in v1. If pilots ask for routing, capture as v2 TODO.
The first senior to claim wins; everyone else's notification self-resolves on
WebSocket reconciliation.

**Notification delivery model (Codex correction 2026-04-27):** drop the
`notification_sent: bool` flag from v1. Replace with per-channel delivery rows
in a new `notification_log` table (already exists — reuse, don't add a new model)
keyed by `(handoff_id, channel, recipient_user_id, status)` where status ∈
{queued, sent, failed, suppressed}. This makes partial-success and per-channel
retry visible. If the existing `notification_log` schema doesn't match, defer
the per-channel persistence to a v2 TODO and v1 logs delivery attempts to the
existing telemetry stream instead. Do NOT keep the dead boolean.

**"Start here" CTA (Codex correction 2026-04-27):** opens the FlowPilot session
at the **latest known state** (the AI's most recent agent_message + the current
pending_task_lane). Surface `ai_assessment_data.suggested_steps[]` as a list of
chips below the chat input — clicking a chip prefills the input. Do NOT invent a
"jump to most-likely-next-step" capability that doesn't exist in the session model.

**`/claim` role gate (Codex correction 2026-04-27, IN-SCOPE for v1):** add
`require_engineer_or_admin` dep on POST `/handoffs/{id}/claim`. Originally
deferred to TODO during eng review; Codex correctly flagged it as wedge-relevant
because the race-condition story depends on auth gating. ~30 min change. Removed
from TODO.md.

**A11y requirements (mandatory before pilot ship):**
- Keyboard: Tab order through queue cards; Enter on focused card opens it; Pick Up
  button is a reachable target; Esc closes the handoff-context overlay.
- ARIA: `role="region"` + `aria-live="polite"` on the queue list (announces arrivals);
  `aria-label="N escalations awaiting pickup"` on the heading; the slide-in animation
  must not announce twice (debounce live-region updates).
- Pick Up button: bump from `py-2` to `py-2.5` to clear the 44px touch-target floor.
- Color contrast: confidence-badge text on accent-dim background must be ≥4.5:1
  (verify against DESIGN-SYSTEM.md tokens).

**DS token discipline:** every new piece must use `card-flat`, `accent-dim`/`accent-text`,
`text-muted-foreground`, `bg-card`/`bg-elevated`, IBM Plex / Bricolage / JetBrains,
explicit `transition` property lists (never `transition: all`). No glass, no blur,
no gradient surfaces. Electric-blue accent reserved for interactive elements only.

**Mobile responsive:** deferred to post-pilot TODO. Pre-PMF wedge target is desktop;
MSP techs work on laptops/desktops in shop environments.

**Deferred to TODO.md (out of scope for v1 wedge):**
- Peer-tech escalates colleague's session (currently session-owner-only)
- Role gate on POST /claim (currently any authenticated user in account)

### Approach B: Full Structured Resolution loop (split B1 + B2)

End-to-end demo: tech opens FlowPilot, structure appears in side panel as AI
responds, ticket notes auto-populate at end, optional runbook capture for reusable
patterns. Tells the full "senior engineer over your shoulder" story.

**B1 — Side panel + PSA-formatted ticket notes** (ships first):
- Structured side panel that surfaces parsed AI markers as live actionable steps
  while the conversation runs.
- PSA-formatted ticket-notes exporter (ConnectWise first; Autotask/Halo later).
- Effort: M (~3 weeks).

**B2 — Runbook offer-and-save** (gated on pilot demand):
- "Save this resolution as a flow?" prompt at session end, with auto-drafted
  runbook from the structured session state.
- Effort: S (~1 week). Don't build until at least 2 pilot customers explicitly
  ask for it.

- **Risk:** Medium. The structured-output panel quality is the whole demo. If it
  looks dumb, the demo dies.
- **Reuses:** FlowPilot, unified_chat_service, FlowProposal, ConnectWise PSA
  integration.

### Approach C: Senior-Tech Time-Saved Counter

Continuous measurement layer underneath A and B. Every session contributes an
estimated minutes-saved number. Owner-facing dashboard quotes "this month your
shop saved N hours of senior-tech time." Sells to MSP owner with verifiable ROI.

- **Effort:** S (~1 week + ongoing measurement methodology refinement).
- **Risk:** Medium-low. Methodology has to be defensible. If numbers look
  made-up, trust dies fast.
- **Reuses:** FlowPilot telemetry, session metadata, account-scoped analytics.

## Recommended Approach

**A first (1-2 weeks), then B (3-4 weeks after A ships), with C running underneath
both as a continuous backdrop.**

Sequence rationale:

- **A is the sharpest possible 2-minute demo.** Single feature, single metric,
  buyer-verifiable in their own data. Get it in front of 5 MSPs in week 3.
- **B is the depth play.** Once Approach A has produced first-pilot signal,
  Approach B's full structured-resolution loop becomes the "what we ship next" that
  retains pilots and converts them to paid.
- **C compounds across both.** Every session under A or B contributes to the
  time-saved counter. By week 6 there are real numbers to put in front of an MSP
  owner — turning a senior-tech-led pilot into an owner-signed contract.

This sequence is non-negotiable. Building B before A is the classic pre-PMF trap of
perfecting product before validating GTM. Building C alone is measurement without a
demo to anchor it.

## Pricing

**Pilot pricing (first 3-5 customers): $39/seat/month, monthly billing,
month-to-month.** Anchored against IT Glue (~$29/tech), Hudu (~$25/tech),
Liongard (~$3/endpoint). The premium over IT Glue/Hudu reflects the active-session
value (vs. their static-runbook value) — 30% above the runbook-only category.

Customer #6+ pricing is an Open Question (revisit after 3 pilots produce real
hours-saved data; price up if the per-seat ROI is over $200/seat/mo).

## Open Questions

1. **Free-tier shape.** Should the time-saved counter be free forever as a
   distribution lever, with paid for the structuring + escalation? Land-and-expand
   pattern. Decide after 3 pilot conversions.
2. **PSA-marketplace timing.** ConnectWise Marketplace listing requires partnership
   onboarding (~6-week cycle). Submit application week 5; expect listing live by
   week 11. Don't gate launch on it.
3. **Customer #6+ pricing.** Revisit after 3 pilot customers produce verifiable
   hours-saved numbers.

## Deferred (YAGNI until 10 paying customers)

- HIPAA / SOC2 audit positioning. Pre-PMF is too early; revisit when a regulated-
  vertical MSP asks for it explicitly.
- Multi-PSA depth (Autotask, Halo). ConnectWise alone covers ~40% of the SMB MSP
  market and is sufficient for first 5-10 customers.
- Cross-tenant pattern detection. The data-flywheel-across-shops play is at least
  6 months out; building it before single-shop ROI is proven is premature.

## Success Criteria (revised for realism)

- **Week 3:** Approach A shipped. 3 MSPs in active free pilot (cap at 3 to
  preserve B1 build capacity).
- **Weeks 3-6:** Pilot management dominates. B1 build is paused; founder runs
  pilot calls, captures bug reports, iterates UX. Stripe seat-based billing is
  set up in week 5.
- **Week 6:** First verbal commit from a pilot customer. Verified
  minutes-recovered-per-escalation number from at least 2 pilots.
- **Week 8:** First paid customer (procurement cycles run 4-6 weeks even at small
  MSPs; 2 weeks from verbal commit to signed contract is realistic). Time-saved
  counter (Approach C) producing dashboard-quality data.
- **Week 11:** B1 (side panel + PSA notes) shipped. 3-5 paying customers. First
  MSP-owner-led conversation. ConnectWise Marketplace listing live.
- **Quarter end:** $5K MRR or 10 paying customers, whichever comes first. Loom
  demos posted publicly to r/msp and MSPGeek.

## Distribution Plan (week-by-week cadence)

- **Week 3:** Escalation Mode demo Loom posted. r/msp launch post.
- **Week 4:** MSPGeek Discord AMA scheduled. RocketMSP newsletter pitch sent.
- **Week 5:** ConnectWise Marketplace listing application submitted. Stripe
  billing live for paid conversion.
- **Week 6:** First "guest on Inside MSP podcast" outreach. Second r/msp post
  (case study from a pilot, anonymized).
- **Week 7-8:** Pilot conversion calls. First paying customer.
- **Week 9-11:** B1 ships. Owner-targeted demo Loom. Second podcast outreach.

**Founder-led pilot:** The first 3-5 customers come from the founder's existing
MSP network. Treat them as design partners; expect to ship feature requests
weekly during pilot. Cap at 3 active pilots until B1 ships.

**Tech audience channels:** r/msp, r/sysadmin, MSPGeek Discord, RocketMSP
newsletter, Inside MSP podcast.
**Owner audience channels:** ConnectWise Marketplace, MSP-focused Substacks,
RIA Vendor Roundup.

CI/CD: existing Railway auto-deploy via GitHub mirror. No new pipeline needed.

## Dependencies

- **Session-state serialization (Approach A blocker).** Schema design + migration
  is the longest-lead engineering task. 3-5 days budget. Do this first.
- **Stripe seat-based billing (week 5 task).** No billing infrastructure exists
  today. ~3-5 days of work for monthly subscriptions + invoice flow. Block on
  this before week-8 first-paid milestone.
- **ConnectWise PSA integration depth.** Sufficient for ticket-notes auto-export
  (Approach B1). Autotask and Halo wait until first 5 paying ConnectWise
  customers.
- **Authentication.** Existing JWT + role hierarchy is sufficient for senior-tech
  inbox view; no new auth work needed.

## Risks and Kill-Switch

- **Risk: Session-state serialization design churn.** If the schema needs to
  change after pilot feedback, every saved session has to migrate. Mitigation:
  keep schema versioned and forward-compatible from day 1.
- **Risk: Pilot-to-paid conversion slower than 4-6 weeks.** MSP procurement is
  notoriously slow. Mitigation: get verbal commits in writing; price as
  month-to-month with no annual contract to lower the buying friction.
- **Risk: ConnectWise ships an equivalent feature in their 2026.x release.**
  Mitigation: lead the marketing on "we're independent of your PSA" — works with
  any PSA, not just ConnectWise. The founder's PSA-agnostic FlowPilot is an
  asset here.
- **Kill-switch criterion:** if 0 of 3 pilots produce a verifiable
  hours-saved-per-week number above 1.0 by week 8, **revisit the wedge**. The
  product may need to pivot to deterministic-ops territory (Read 1 from the
  session) or be repositioned. Don't sink another quarter into the current GTM
  story without this number.

## The Assignment

**This week, before any code:**

Time-track the next 5 escalations in your shop manually. For each, capture:
1. Time the senior tech opens the ticket
2. Time the senior tech takes their first diagnostic action (not counting the
   verbal "tell me what you tried" warm-up)
3. The delta — that's the wasted time per escalation today

Average those 5 numbers. **That's the hero stat in your first sales conversation:**
"Senior techs at our shop wasted N minutes per escalation just getting up to
speed. We built the thing that takes that to zero."

Don't try to pull this from telemetry — the doc itself notes that retrieval/re-use
data isn't queryable yet. Manual stopwatch on the next 5 escalations is the
fastest path to a defensible number.

This is the assignment because it forces the GTM story into the same time-zone as
the build, and it's a one-day effort that compounds for every conversation
afterward.

## What I noticed about how you think

- You contradicted my framing twice in the same session and the second
  contradiction was sharper than the first. Most founders agree with the
  diagnostic and walk out with a polished version of what they came in with. You
  said "I'm just questioning if flows are even the way to go" — and that
  sentence reset the entire wedge. That's craft.

- "The senior engineer looking over your shoulder" came out of you spontaneously,
  not as a prepared pitch. That's the line. Use it. It survives because it's
  emotional truth (every junior tech has had this, every senior tech has been
  this), not constructed marketing copy.

- You're solving your own problem with your own time. 20 hrs/week isn't a
  hypothetical user pain — it's your Tuesday. Founders who solve their own pain
  ship sharper products because the feedback loop is instant.

- The escalation feature emerged from your description, not mine. I was busy
  cataloging documentation pains. You said "junior to senior escalation? no
  worries there either" almost as an afterthought. That afterthought is the wedge.
  Pay attention to which features you describe casually versus which you push hard
  on — the casual ones are sometimes where the truth lives.

## GSTACK REVIEW REPORT

| Review | Trigger | Why | Runs | Status | Findings |
|--------|---------|-----|------|--------|----------|
| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | not run |
| Codex Review | `/codex review` | Independent 2nd opinion | 1 | INFO | 12 findings, 6 applied, 1 partial, 5 rejected |
| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | 2 issues, 0 critical gaps, scope reduced |
| Design Review | `/plan-design-review` | UI/UX gaps | 1 | CLEAR (FULL) | score 6/10 → 9/10, 8 decisions |
| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | not run |

- **CODEX:** 12 findings reviewed. Applied: 2-metric framing (#2), notification routing spec (#3), per-channel delivery model (#4), unread-state fix (#11), Start-here CTA reframe (#9), claim role gate moved in-scope (#8). Rejected: full scope reduction to PSA-brief-only (#6/7/12 — user kept queue UI as demo hero). Partial: scope concern (#5) acknowledged in eng review's email-first/polling-fallback. Misread: #1, #10.
- **CROSS-MODEL:** Claude (eng + design reviews) and Codex agree on 6/12 findings. The major disagreement was scope — Codex argued for cutting the queue UI, user rejected. Both agree on metric definition, notification routing, claim auth gating.
- **UNRESOLVED:** 0
- **VERDICT:** ENG + DESIGN CLEARED, CODEX REVIEWED — ready to implement.
