resolutionflow/docs/FlowAssist_Migration/FLOWPILOT-MIGRATION.md

FlowPilot Migration — Design & Implementation Doc

Target: Transform /assistant (ResolutionAssist) into the new unified /pilot (FlowPilot) surface. Audience: Claude Code (implementation) reviewed by Michael (owner). Status: Design locked. Ready for phased implementation. Last updated: April 17, 2026

---

0. Prerequisite reading for Claude Code

Before writing any code, read these in order:

1. This document end-to-end.
2. mockups/01-session-primary.png — the target state for the main session UI.
3. mockups/02-script-template-match.png, 03-script-three-options.png, 04-script-templatize-prompt.png — Script Generator integration states.
4. The source HTML files mockups/01-session-primary.html and mockups/02-04-script-integration.html — authoritative for spacing, colors, and component structure. When CSS or layout questions arise during implementation, these files are the tiebreaker.

Do not proceed to implementation until you have confirmed you understand the following three architectural claims. If any of them are unclear, stop and ask.

1. There is one AI troubleshooting surface, not two. The existing split between FlowPilot (guided) and ResolutionAssist (chat) is collapsed into a single chat-primary product called FlowPilot at /pilot. The ai_sessions.session_type discriminator column is retained for data, but the product shows one unified UI.
2. The task lane is the load-bearing structural feature. It is not a sidebar of metadata. It actively tracks diagnostic state: What we know, Questions, Diagnostic checks, Suggested fix. Engineers interact with it; facts flow between sections.
3. Resolve and Escalate are deterministic artifact generators, not free-text prompts. When an engineer clicks Resolve, a structured summary is generated from task lane state (not from the chat transcript alone) and posted to CW. The summary structure is fixed: Problem / What we confirmed / Root cause / Resolution.

---

1. Why this change

The current state

• /assistant is a chat-primary AI session with a [QUESTIONS] and [DIAGNOSTIC_CHECKS] task lane.
• /pilot was specced as a separate guided, confidence-tiered wizard with a different UI and lifecycle.
• The FLOWPILOT-AND-RESOLUTIONASSIST.md design document treated them as two products sharing a backend.

The problems with the current state

• Two sidebar entries, two session histories, two mental models for engineers to learn.
• The PSA integration scope doubles (writebacks for lifecycle events must be built twice, or built for Pilot and bolted onto Assist).
• The Team Wiki moat depends on structured session artifacts with explicit resolutions — a chat-only mode produces weaker artifacts.
• The cockpit positioning (the core ResolutionFlow brand promise) does not map to a blank chat window.
• Branching into two modes forces a decision onto the engineer ("which mode for this ticket?") that has no right answer.

The resolution

The existing /assistant UI already does most of what /pilot was supposed to do — structured questions, diagnostic checks, lifecycle actions in the header. It is closer to the right product than the doc anticipated. Rather than building Pilot as a second surface, we extend Assist with the missing structural features (What we know, auto-generated summaries, escalation packages) and rename it FlowPilot.

The strategic move

FlowPilot becomes the single canonical troubleshooting surface. Every PSA writeback, every Wiki compilation path, every Script Generator invocation points here. One session shape, one lifecycle, one integration surface.

---

2. Terminology used in this document

Term	Meaning
Session	A single ai_sessions row representing one troubleshooting conversation.
Task lane	The right-side panel containing What we know, Questions, Diagnostic checks, Suggested fix.
Fact	An item in the What we know section. Has text, source_type (question / diagnostic_check / user_note), and source_ref (FK to the originating question/check, or null for user notes).
Suggested fix	The AI's current best-guess resolution path. Has a confidence score and, optionally, a reference to a Script Library template.
Promotion	The act of a question answer or diagnostic check result being converted into a fact in What we know. Triggered by AI, confirmed/editable by engineer.
Resolution note	The structured document generated when the engineer clicks Resolve. Posted to CW as a ticket note.
Escalation package	The structured handoff document generated when the engineer clicks Escalate. Posted to CW and attached to the session for the next engineer.

---

3. Target UI — annotated

3.1 Primary session view

The session UI is a four-column layout:

1. Icon rail (64px wide) — primary app navigation. FlowPilot / Tickets / Trees / Scripts / Wiki. Avatar at bottom.
2. Session list (260px wide) — all sessions grouped by state (Active / Recent). Each row shows title, state dot, PSA ticket number, and client name.
3. Conversation column (fluid) — the chat thread, composer, and incident header.
4. Task lane (380px wide) — What we know, Questions, Diagnostic checks, Suggested fix, and the Resolve action at the bottom.

Key visual and behavioral elements numbered against the mockup:

Incident header (top of conversation column)

• PSA chip showing CW #48291 in cyan, monospaced
• Client / contact / priority meta line
• Incident title in Bricolage Grotesque 19px
• Four lifecycle buttons right-aligned: Pause (ghost), Share update (neutral), Escalate (amber), Resolve (green)

Conversation column

• Standard chat thread with pilot and user avatars
• Pilot uses cyan gradient avatar; user uses purple gradient
• AI messages in bg-2 bubbles with subtle border; user messages in cyan-tinted bubbles
• Composer at bottom with inline action chips (Attach / Paste logs / Ticket context) and a send button

Task lane sections, in order:

1. What we know (NEW)

   • Header: WHAT WE KNOW · 4 (section title + count)
   • Each fact is a card: bg-2 background, dashed circular green check, fact text, and a provenance line (from question · rules out tenant/license)
   • "+ Add a note" button at the bottom for manual facts from the engineer
   • Background has a subtle green-to-transparent gradient to visually distinguish from the rest of the lane

2. Questions

   • Header: QUESTIONS · 2 unanswered
   • Each unanswered question: title, AI hint text, Answer / Skip buttons
   • Answered questions dim to 55% opacity with a dashed border and show the resolution inline (Answered · isolated to jsmith (promoted to What we know))

3. Diagnostic checks

   • Header: DIAGNOSTIC CHECKS · 1 / 3 run
   • "Run remaining 2 checks" button at top when applicable
   • Each check: icon + command name (monospaced), description
   • Completed checks dim and show "Complete · findings promoted to What we know" in green

4. Suggested fix

   • Header: SUGGESTED FIX · 94% confidence
   • Amber-accented card with fix title and description
   • Clicking opens the Script Generator flow (Section 5)

Resolve action bar (bottom of task lane)

• Small hint text ("Summary preview is open →")
• Full-width "Resolve & post to CW" button in green

Resolution note preview (floating, anchored to Resolve button)

• A persistent popover, NOT a modal
• Shows the draft resolution note with Problem / What we confirmed / Root cause / Resolution sections
• Displays the target ticket (CW #48291) and status change (Resolved)
• Edit button opens an inline editor; Confirm & post fires the PSA writeback

3.2 Script Generator integration — template match

When the suggested fix references an existing Script Library template, clicking the fix opens the Script Generator panel in place of (or sliding over) the task lane. Key behavior:

• A Verified template badge appears above the parameter form
• Parameters pre-filled from session context get a cyan from session tag and a cyan-tinted input background
• Each pre-filled parameter has a hint line explaining the source: "Pulled from CW company config for Acme Corp"
• The engineer can adjust any pre-filled value before generating
• ⌘K → "script" invokes the generator mid-conversation from anywhere in the session

3.3 Script Generator integration — no template match (three-option dialog)

When no template matches the suggested fix, FlowPilot drafts a session-specific script and presents three paths:

1. Run as one-off (neutral outline CTA)

   • Script generated and captured in session documentation, discarded after
   • Tradeoffs: fastest, but team won't benefit next time

2. Run now, templatize after resolve (RECOMMENDED, cyan primary CTA)

   • Script generated for this ticket; draft template queued
   • Post-resolve prompt offers to templatize (Section 5.3)
   • Tradeoffs: zero cognitive overhead now, only templatize what works, ~30s review later

3. Build as template now (purple outline CTA)

   • Full parameterization upfront
   • Tradeoffs: immediate team benefit, but adds time mid-ticket

The drafted script renders as a code preview above the option cards with the AI's proposed parameters highlighted in amber.

3.4 Script Generator integration — post-resolve templatization prompt

If the engineer picked Option 2 in the three-option dialog and Resolve succeeds, this prompt appears after the resolution note is posted to CW:

• Success banner confirms the resolution posted
• Templatize card shows the script with AI-proposed parameters substituted in as {{ gateway_host }}, etc.
• Right pane lists extracted parameters with remove buttons (engineer can adjust)
• Provenance note: "generated from CW #48307 · resolved by M. Davis"
• Three actions: Skip / Edit parameters / Save as team template
• "Don't ask me again for this team" opt-out in footer

---

4. Data model changes

4.1 New columns on ai_sessions

ALTER TABLE ai_sessions
  ADD COLUMN resolution_note_markdown TEXT NULL,
  ADD COLUMN resolution_note_posted_at TIMESTAMPTZ NULL,
  ADD COLUMN resolution_note_external_id VARCHAR(128) NULL,  -- CW note ID after posting
  ADD COLUMN escalation_package_markdown TEXT NULL,
  ADD COLUMN escalation_package_posted_at TIMESTAMPTZ NULL;

No migration of session_type — the column stays. New sessions all default to the unified FlowPilot type.

4.2 New session_facts table (the What we know backing store)

CREATE TABLE session_facts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id UUID NOT NULL REFERENCES ai_sessions(id) ON DELETE CASCADE,
  account_id UUID NOT NULL REFERENCES accounts(id),  -- for RLS, per multi-tenant architecture
  text TEXT NOT NULL,
  source_type VARCHAR(32) NOT NULL CHECK (source_type IN ('question', 'diagnostic_check', 'user_note', 'ai_synthesis')),
  source_ref UUID NULL,  -- FK to session_questions.id or session_diagnostic_checks.id, null for user_note
  source_summary TEXT NULL,  -- free-text provenance label, e.g. "rules out tenant/license"
  created_by UUID NOT NULL REFERENCES users(id),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  deleted_at TIMESTAMPTZ NULL
);
CREATE INDEX idx_session_facts_session ON session_facts(session_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_session_facts_account ON session_facts(account_id);

Important: source_ref is a polymorphic FK and should NOT have a database-level FK constraint. Enforce integrity at the service layer.

4.3 New session_suggested_fixes table

CREATE TABLE session_suggested_fixes (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id UUID NOT NULL REFERENCES ai_sessions(id) ON DELETE CASCADE,
  account_id UUID NOT NULL REFERENCES accounts(id),
  title VARCHAR(200) NOT NULL,
  description TEXT NOT NULL,
  confidence_pct INTEGER NOT NULL CHECK (confidence_pct BETWEEN 0 AND 100),
  script_template_id UUID NULL REFERENCES script_templates(id),  -- null if no template match
  ai_drafted_script TEXT NULL,                                    -- populated if no template match
  ai_drafted_parameters JSONB NULL,                               -- AI's proposed parameterization
  user_decision VARCHAR(32) NULL CHECK (user_decision IN ('one_off', 'draft_template', 'build_template', 'dismissed')),
  superseded_at TIMESTAMPTZ NULL,  -- set when a new suggestion replaces this one
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_session_suggested_fixes_session ON session_suggested_fixes(session_id) WHERE superseded_at IS NULL;

A session can have multiple suggested fixes over time as the AI's understanding evolves. Only one is active (superseded_at IS NULL) at a time.

4.4 New draft_templates table

Backing store for Option 2 in the three-option dialog — scripts generated during sessions that are pending templatization.

CREATE TABLE draft_templates (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  account_id UUID NOT NULL REFERENCES accounts(id),
  source_session_id UUID NOT NULL REFERENCES ai_sessions(id),
  source_user_id UUID NOT NULL REFERENCES users(id),
  script_body TEXT NOT NULL,
  proposed_parameters JSONB NOT NULL,  -- {"parameters": [{"key": "...", "label": "...", "type": "..."}]}
  proposed_name VARCHAR(200) NULL,
  proposed_category_id UUID NULL REFERENCES script_categories(id),
  status VARCHAR(32) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'accepted', 'rejected')),
  resolved_at TIMESTAMPTZ NULL,  -- when the user acted on the draft
  promoted_template_id UUID NULL REFERENCES script_templates(id),  -- if accepted, the created template
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

Accepted draft templates produce a new script_templates row and record the source session for provenance display.

4.5 Extension to script_templates

ALTER TABLE script_templates
  ADD COLUMN source_session_id UUID NULL REFERENCES ai_sessions(id),
  ADD COLUMN source_user_id UUID NULL REFERENCES users(id),
  ADD COLUMN source_ticket_ref VARCHAR(64) NULL;  -- e.g. "CW #48307" for display

These fields power the provenance chip in the Script Library: "generated from CW #48307 · resolved by M. Davis · used 7 times".

4.6 Per-account settings

ALTER TABLE account_settings
  ADD COLUMN templatize_prompt_enabled BOOLEAN NOT NULL DEFAULT true;

Controls whether the post-resolve templatize prompt appears. Toggleable from the prompt's footer ("Don't ask me again for this team") and from admin settings.

---

5. API endpoints

All endpoints follow ResolutionFlow conventions: /api/v1/ prefix, JWT auth, tenant-scoped via RLS.

5.1 Session facts

GET    /api/v1/sessions/{id}/facts               List facts for a session (ordered by created_at ASC)
POST   /api/v1/sessions/{id}/facts               Create a manual fact (user_note source_type)
PATCH  /api/v1/sessions/{id}/facts/{fact_id}     Edit fact text or summary (only for user_note or AI-synthesized facts)
DELETE /api/v1/sessions/{id}/facts/{fact_id}     Soft-delete
POST   /api/v1/sessions/{id}/facts/promote       Promote a question answer or check result to a fact
                                                 Body: { source_type, source_ref, proposed_text, proposed_summary }
                                                 Returns the created fact. Used by the AI synthesis flow and
                                                 by the engineer's explicit "promote to What we know" action.

5.2 Suggested fixes

GET    /api/v1/sessions/{id}/suggested-fixes/active     Returns the current active fix (superseded_at IS NULL) or 404
POST   /api/v1/sessions/{id}/suggested-fixes/{fix_id}/decision
                                                        Body: { decision: "one_off" | "draft_template" | "build_template" | "dismissed" }
                                                        Records the user's path choice. Server-side side effects:
                                                        - one_off: generates script via ScriptTemplateEngine, returns rendered script
                                                        - draft_template: same as one_off, plus creates draft_templates row
                                                        - build_template: redirects to full template creation flow
                                                        - dismissed: marks fix as superseded

5.3 Draft templates (post-resolve flow)

GET    /api/v1/draft-templates                          List pending drafts for the current user's account
                                                        (used by the Script Library "X scripts ready to review" notification)
GET    /api/v1/draft-templates/{id}                     Get a single draft including its proposed parameterization
POST   /api/v1/draft-templates/{id}/accept              Body: { name, category_id, parameters_schema, edits }
                                                        Creates a new script_templates row with source_session_id set,
                                                        sets draft status to 'accepted', returns the new template
POST   /api/v1/draft-templates/{id}/reject              Sets status to 'rejected'

5.4 Resolution notes and escalation packages

POST   /api/v1/sessions/{id}/resolution-note/preview    Generates the draft resolution note from current session state
                                                        WITHOUT posting. Returns { markdown, target_ticket_ref }.
                                                        Called when the task lane renders and refreshed whenever
                                                        facts/suggested fix change.
POST   /api/v1/sessions/{id}/resolution-note/post       Body: { markdown }  (engineer-edited version)
                                                        Posts to the linked PSA ticket, updates ticket status if configured,
                                                        marks session resolved.
POST   /api/v1/sessions/{id}/escalation-package/preview Same pattern for escalation
POST   /api/v1/sessions/{id}/escalation-package/post    Posts and transitions session to escalated state

---

6. Services to implement

6.1 FactSynthesisService (new)

Location: services/fact_synthesis_service.py

Purpose: Converts question answers and diagnostic check results into candidate facts. Called by the AI pipeline when the LLM emits a [PROMOTE] marker, and by explicit engineer action.

Key methods:

• synthesize_from_question(question_id: UUID, raw_answer: str) -> dict — returns {proposed_text, proposed_summary} via LLM call. The summary is the short provenance label ("rules out tenant/license").
• synthesize_from_check(check_id: UUID, check_output: str) -> dict — same pattern for diagnostic check output.
• create_fact(session_id, source_type, source_ref, text, summary, user_id) -> SessionFact — persists the fact.

Prompt engineering note: The synthesis prompt should be conservative — short, factual statements. Hallucinated specifics are a trust-killer. The prompt must explicitly instruct: "Use only information present in the answer/output. If the answer does not contain a substantive fact, return null."

6.2 ResolutionNoteGeneratorService (new)

Location: services/resolution_note_generator.py

Purpose: Produces the structured resolution note markdown from session state.

Input: session_id Output: {markdown: str, target_ticket_ref: str | None}

Template structure:

## Problem
{ai-synthesized one-paragraph problem statement, pulling from session description + incident header}

## What we confirmed
{bulleted list of session_facts, grouped by source_type}

## Root cause
{ai-synthesized from the active suggested fix + facts}

## Resolution
{description of the fix applied, parameters used if a script ran, outcome}

The service pulls from four data sources: ai_sessions, session_facts, session_suggested_fixes (active), and script_generations (if scripts ran during the session). Passwords in script_generations.parameters_used must be redacted (already a Script Generator pattern per the existing plan).

Critical: This service is called on every fact/suggestion change to keep the preview live. Cache aggressively — LLM calls for every keystroke will blow the budget. Invalidate the cache on any write to session_facts or session_suggested_fixes.

6.3 EscalationPackageGeneratorService (new)

Location: services/escalation_package_generator.py

Same structure as ResolutionNoteGenerator but with a handoff-oriented template:

## Problem
...

## What we've confirmed
...

## What we've tried
{list of diagnostic_checks run with their outcomes, scripts generated}

## Current hypothesis
{active suggested fix description}

## Suggested next steps
{ai-synthesized from the gap between facts and a complete resolution}

6.4 TemplateExtractionService (new)

Location: services/template_extraction_service.py

Purpose: Given a concrete rendered script and session context, propose a parameterization.

Input: {script_body: str, session_context: dict, ticket_context: dict} Output: {parameters: [{key, label, type, inferred_from}], templated_body: str}

Implementation approach:

• LLM call with a structured prompt: "Given this script that resolved a ticket, identify values that would change for a different invocation. Propose a parameter schema following the Script Generator conventions (text / password / select / boolean / multi_text / number / textarea)."
• Post-process to ensure the proposed template renders back to the original script when given the extracted parameter values.
• Conservative default: prefer fewer parameters. If a value looks environment-agnostic (e.g. a command name), don't parameterize it.

This service is the engine behind Option 2 and Option 3 of the three-option dialog, and behind the post-resolve templatize prompt.

6.5 Extend PSAWritebackService (existing)

Add methods:

• post_resolution_note(session_id, markdown) -> {external_id, posted_at}
• post_escalation_package(session_id, markdown) -> {external_id, posted_at}
• transition_ticket_status(ticket_ref, new_status) -> {success, verified_status}

The transition_ticket_status method must verify the status change took effect (per the existing ConnectWise integration principle: "never told 'success' when CW silently rejected the change").

6.6 Model selection per service

Each AI-calling service must use a configurable model string from application settings, not a hardcoded model. Use these defaults:

FACT_SYNTHESIS_MODEL = "claude-haiku-4-5-20251001"           # short transformation, latency-sensitive
RESOLUTION_NOTE_MODEL = "claude-sonnet-4-6"                  # customer-facing artifact, quality matters
ESCALATION_PACKAGE_MODEL = "claude-sonnet-4-6"               # same
TEMPLATE_EXTRACTION_MODEL = "claude-sonnet-4-6"              # creates persistent library artifact
MAIN_CONVERSATION_MODEL = "claude-sonnet-4-6"                # primary FlowPilot chat

Do not hardcode model strings at call sites. Every new service must read from settings with a service-specific key.

Instrumentation requirement: log a disputed_fact_rate metric for fact synthesis — the percentage of AI-synthesized facts that engineers subsequently edit or delete. If this exceeds 10% over a 500-session window, escalate FACT_SYNTHESIS_MODEL to claude-sonnet-4-6. If under 5%, Haiku is performing correctly.

Do not use Opus 4.7 for any of these services at current scale.

---

7. Frontend components

7.1 Routes to change

Current route	New route	Action
/assistant	/pilot	Rename the route. The existing page moves. /assistant permanently redirects to /pilot with no sunset date.
/pilot (if it exists as a separate guided flow)	REMOVED	Collapse into the unified surface.
/pilot/session/:id	/pilot/session/:id	No change (this is where the unified session UI lives)

Sidebar nav entry renames from "ResolutionAssist" to "FlowPilot" with the cockpit icon.

7.2 New React components

Under src/components/pilot/:

TaskLane.tsx                  -- The right-side panel, owns all four sections
  sections/
    WhatWeKnow.tsx            -- New component for the facts list
    WhatWeKnowItem.tsx        -- Single fact card with provenance line
    AddNoteButton.tsx         -- "+ Add a note" inline composer
    Questions.tsx             -- Existing questions rendering (moved if already present)
    DiagnosticChecks.tsx      -- Existing checks rendering (moved if already present)
    SuggestedFix.tsx          -- New or refactored component for the suggested fix card
ResolveButton.tsx             -- The Resolve CTA at the bottom of the task lane
ResolutionNotePreview.tsx     -- Floating popover anchored to Resolve button
EscalatePackagePreview.tsx    -- Same pattern for Escalate

ScriptGenInline/              -- Script Generator embedded in session context
  TemplateMatchPanel.tsx      -- Scene 1 mockup: template pre-filled
  NoTemplateDialog.tsx        -- Scene 2 mockup: three-option dialog
  TemplatizePrompt.tsx        -- Scene 3 mockup: post-resolve prompt
  ParameterizationPreview.tsx -- Shared component: script with highlighted params

7.3 Component behavior contracts

WhatWeKnowItem

• Props: {fact: SessionFact, onEdit, onDelete}
• Renders the fact text, a green checkmark, and the provenance line with source-type color coding
• Clicking the fact text opens inline edit (only for user_note and ai_synthesis sources — question/check facts are read-only, edit the source instead)

TaskLane

• Subscribes to a session state hook that polls for fact / question / check / suggested-fix updates
• On any state change, calls POST /api/v1/sessions/{id}/resolution-note/preview to refresh the ResolutionNotePreview
• Debounce preview refresh to 500ms to avoid LLM spam

NoTemplateDialog (three-option dialog)

• Props: {suggestedFix, onDecision}
• Renders the three cards with the middle (draft_template) marked as recommended
• onDecision posts to /api/v1/sessions/{id}/suggested-fixes/{fix_id}/decision and either opens the Script Generator (one_off / draft_template) or navigates to full template creation (build_template)

TemplatizePrompt

• Rendered after successful Resolve when a draft template exists for the session
• Fetches proposed parameters from the draft template record
• Save button posts to /api/v1/draft-templates/{id}/accept

---

8. AI prompt changes

The existing FlowPilot / ResolutionAssist system prompt needs updates to emit the new markers.

8.1 New marker: [PROMOTE]

Used to surface facts to What we know. Syntax:

[PROMOTE]
source_type: question
source_ref: {question_id}
text: OWA login and send/receive confirmed working for jsmith
summary: rules out tenant/license
[/PROMOTE]

The AI should emit [PROMOTE] blocks in the same message that answers or processes a question/check, so the fact appears in What we know simultaneously with the chat acknowledgment.

8.2 New marker: [SUGGEST_FIX]

[SUGGEST_FIX]
title: Clear cached credentials + rebuild Outlook profile
description: Stale cached credential in Credential Manager is holding the pre-reset token...
confidence: 94
script_template_slug: clear-outlook-credentials   # or omitted if no template match
ai_drafted_script: |                              # only if no template match
  # Generated by FlowPilot...
  ...
[/SUGGEST_FIX]

8.3 Removed markers

The old [FORK] marker from the ResolutionAssist prompt is removed. Forks were a Guided-mode concept; in the unified model, they're replaced by Questions with mutually exclusive answer options.

---

9. Implementation phases

Each phase ends with a git commit and verification step. Do not advance to the next phase until verification passes.

Phase 0 — Prompt caching infrastructure (prerequisite)

A codebase audit revealed that prompt caching is only implemented in assistant_chat_service.py (the file being deprecated). Every other Anthropic API call site — including all of FlowPilot's 7 call sites through AnthropicProvider — is uncached. Phase 0 must land before Phase 2 starts because new services built in Phase 2 will inherit caching from AnthropicProvider automatically once it's fixed.

Deliverables:

• 0.1 Promote AnthropicProvider.generate_json() and generate_text_stream() in ai_provider.py to the cached pattern currently implemented in assistant_chat_service.py:_call_anthropic_cached(). Convert the system string parameter to a structured system block list with cache_control: {"type": "ephemeral"} on the static portion. Add a second breakpoint on the last history message. For the streaming variant, capture the final usage object via get_final_message(). Log cache_read_input_tokens and cache_creation_input_tokens on every response.
• 0.2 Update integrations.py:557 (/tickets/ai-parse) to move the members list and team-stable boards data into a cached system block.
• 0.3 Add cache_control to one-shot generators: ai_tree_generator, kb_conversion, ai_fix, script_builder. Same pattern as 0.1.
• 0.4 Extract the caching logic from assistant_chat_service.py:_call_anthropic_cached() into AnthropicProvider and delete _call_anthropic_cached. assistant_chat_service should call the provider like every other service. This prevents two canonical implementations of the same pattern.

Verification:

• Hit any FlowPilot endpoint twice within 5 minutes. First call shows cache_creation_input_tokens > 0, second call shows cache_read_input_tokens > 0.
• If the second call returns zero cache reads, inspect the prefix for silent invalidators (timestamps, unsorted JSON keys, varying tool list ordering). Fix before proceeding.

git commit -m "feat(ai): promote AnthropicProvider to cached pattern, consolidate caching implementation"

Dependencies:

• Phase 1 (route rename and schema) can run in parallel with Phase 0.
• Phase 2 (What we know) must not start until Phase 0 is complete and verified.

Phase 1 — Data model and route rename (backend + routing only)

Deliverables:

• Alembic migration creating session_facts, session_suggested_fixes, draft_templates tables and the column additions to ai_sessions, script_templates, account_settings
• All tables include account_id and have RLS policies following the multi-tenant architecture (per existing project standard)
• /assistant → /pilot route rename with permanent redirect (stays in place indefinitely; no sunset date)
• Sidebar nav entry rename
• No UI changes yet beyond the nav label

Verification:

• Run migration on a fresh dev database
• Confirm RLS policies active via the existing CI grep check for tenant_filter()
• Navigate to /assistant — should 301 to /pilot
• Navigate to /pilot — should render the existing ResolutionAssist UI with the sidebar entry now reading "FlowPilot"

git commit -m "feat(pilot): rename /assistant to /pilot, add session_facts + suggested_fixes + draft_templates schema"

Phase 2 — What we know (task lane + service + API)

Deliverables:

• FactSynthesisService and its LLM prompt
• Fact CRUD API endpoints
• WhatWeKnow, WhatWeKnowItem, AddNoteButton components
• Task lane layout adjustment: What we know section renders above Questions
• Counter in task lane header updates to X / Y answered format
• AI prompt updated to emit [PROMOTE] markers; backend parses them and creates facts

Verification:

• Open a session, answer a question; within 2 seconds a fact should appear in What we know with correct provenance
• Click "+ Add a note", type a manual fact, confirm it appears with source_type: user_note
• Run a diagnostic check, confirm the check result promotes to a fact
• Facts persist across page reloads
• RLS: a user from a different account cannot read or write facts for this session

git commit -m "feat(pilot): add What we know section with fact synthesis"

Phase 3 — Suggested fix + resolution note preview

Deliverables:

• session_suggested_fixes API endpoints and data flow
• SuggestedFix component in the task lane
• AI prompt updated to emit [SUGGEST_FIX] markers
• ResolutionNoteGeneratorService and preview endpoint
• ResolutionNotePreview floating popover anchored to Resolve button
• Preview refreshes on fact / suggested-fix changes (debounced)

Verification:

• Session with ≥3 facts and an active suggested fix shows a populated Resolve preview
• Editing a fact updates the preview within 1 second
• Preview markdown renders correctly with all four sections (Problem / What we confirmed / Root cause / Resolution)
• Preview contains no hallucinated information not present in session state (human review of 5 real-ish sessions)

git commit -m "feat(pilot): add suggested fix tracking and Resolve note preview"

Phase 4 — Resolve and Escalate PSA writebacks

Deliverables:

• transition_ticket_status method with CW verification
• post_resolution_note endpoint and CW integration
• Resolve button fires: post note → transition status → mark session resolved → show templatize prompt (if applicable)
• EscalationPackageGeneratorService and parallel flow for Escalate
• Escalate button fires: post package → transition status → mark session escalated → route via CW rules

Verification:

• Complete a session end-to-end with a ConnectWise test instance
• Click Resolve, edit the preview, confirm post — verify the note appears in CW and status changes to Resolved
• Click Escalate on a different session — verify the package is posted and the ticket routes correctly
• Attempt to Resolve without a linked PSA ticket — should mark the session resolved without erroring, note stored in resolution_note_markdown only

git commit -m "feat(pilot): wire Resolve and Escalate to ConnectWise writeback"

Phase 5 — Script Generator inline integration

Deliverables:

• ScriptGenInline/TemplateMatchPanel — when suggested fix has script_template_id, clicking the fix opens this panel with pre-filled parameters from session context
• Parameter pre-fill logic: pulls from session facts, ticket context (company configs), and AI-suggested values in the [SUGGEST_FIX] marker
• ScriptGenInline/NoTemplateDialog — three-option dialog when no template match
• User decision persisted on session_suggested_fixes.user_decision
• TemplateExtractionService for generating parameterization proposals
• Script generation flow produces a script_generations record linked to the session (existing Script Generator behavior)

Verification:

• Session with a template-matched suggested fix: clicking opens generator with ≥2 pre-filled parameters
• Session with a custom script suggested fix: dialog appears with three options, script preview shows parameters highlighted
• All three paths end correctly: one-off generates and closes, draft creates draft_templates row and generates, build_template opens full template creation
• ⌘K → "script" anywhere in a session opens the generator directly

git commit -m "feat(pilot): integrate Script Generator inline with suggested fixes"

Phase 6 — Post-resolve templatize prompt

Deliverables:

• TemplatizePrompt component
• Logic: after Resolve success, check for pending draft_templates rows for this session; if any, show the prompt
• Accept flow creates a new script_templates row with source_session_id, source_user_id, source_ticket_ref set
• "Don't ask me again" writes to account_settings.templatize_prompt_enabled
• Script Library sidebar shows a small badge when draft_templates with status='pending' exist for the current user

Verification:

• Resolve a session where the engineer picked Option 2 — templatize prompt appears with AI-proposed parameters
• Accept the prompt — new template appears in the Script Library with the provenance chip ("generated from CW #...")
• Skip the prompt — draft marked rejected, Script Library shows no new template
• Toggle "don't ask me again" — next session Resolve skips the prompt even with a pending draft

git commit -m "feat(pilot): add post-resolve templatize prompt for draft templates"

Phase 7 — Polish

Deliverables:

• Visual polish against the mockup files (spacing, colors, animations)
• Loading states for LLM calls (fact synthesis, preview generation, template extraction)
• Empty states (new session with no facts yet, no active suggested fix, no draft templates pending)
• Keyboard shortcuts: ⌘K (command menu), ⌘↵ (send composer), ⌘G (generator), ⌘R (resolve with confirm)
• Responsive behavior: task lane collapses on <1200px viewports into a bottom drawer

Verification:

• Compare each major screen side-by-side with the mockup PNG files — colors, spacing, typography within 5px / exact color match
• All flows work on a 1280px viewport without horizontal scroll
• Keyboard shortcuts documented in-app via ? overlay

git commit -m "feat(pilot): visual polish and keyboard shortcuts"

---

10. Design system reference

All components must use the existing ResolutionFlow design system. Pulling the key tokens from the mockup CSS for quick reference — these should already exist in your tokens file; if they don't, add them:

/* Backgrounds */
--bg-0: #070b12;          /* page background */
--bg-1: #0d131c;          /* sidebar / chrome */
--bg-2: #121a25;          /* card / bubble background */
--bg-3: #1a2332;          /* raised element */

/* Borders */
--border: rgba(148, 163, 184, 0.12);
--border-strong: rgba(148, 163, 184, 0.22);

/* Text */
--text-primary: #e2e8f0;
--text-secondary: #94a3b8;
--text-tertiary: #64748b;

/* Brand cyan (FlowPilot accent) */
--cyan-400: #22d3ee;
--cyan-500: #06b6d4;
--cyan-600: #0891b2;
--cyan-bg: rgba(34, 211, 238, 0.10);
--cyan-border: rgba(34, 211, 238, 0.30);

/* Semantic */
--success: #34d399;   /* Resolve, facts */
--warning: #fbbf24;   /* Escalate, proposed parameters */
--danger:  #f87171;
--purple:  #a78bfa;   /* Script Generator / templates */

Typography:

• Body: IBM Plex Sans, 14px/1.5
• Headings: Bricolage Grotesque, 500 weight, -0.01em letter-spacing
• Code: JetBrains Mono

Icons: Phosphor Icons (Duotone) per the memory-recorded design decision to migrate off Lucide.

---

11. Non-goals for this migration

Do not build these as part of this work. They belong to later phases of the roadmap.

• Confidence tiers (Discovery / Exploring / Guided). We explicitly removed these. The task lane itself is the progress signal.
• Mode toggle between Guided and Quick ask. There is one mode.
• "Convert to guided" promotion flow. No longer applicable.
• Team Wiki compilation from resolved sessions. Tracked separately; depends on this migration but is not part of it.
• SharePoint integration. Sequenced after ConnectWise per roadmap.
• Template marketplace / sharing across accounts. Tracked under Client Context System roadmap item.

---

12. Risks and mitigations

Risk	Mitigation
LLM fact synthesis hallucinates specifics not in the answer	Conservative prompt; engineer can edit/delete any AI-synthesized fact; provenance line shows the source so the engineer can verify
Resolution note preview LLM cost at scale	Cache aggressively, invalidate only on session state write; debounce UI updates to 500ms; consider lower-tier model for preview generation (final post-to-CW version can use the better model)
ConnectWise silently rejects status change	transition_ticket_status must re-fetch and verify; fail loudly if the change didn't stick
Template extraction proposes bad parameterization	Engineer reviews before saving; draft templates never silently become real templates; provenance chip lets team admins audit
Users lose muscle memory from /assistant → /pilot rename	Permanent redirect (no sunset date); inline toast on first /pilot visit explaining the rename
Existing sessions have no session_facts entries, so What we know is empty	Acceptable — Phase 2 deliberately does not backfill; facts only accumulate for new or ongoing sessions after deploy. Document in release notes.

---

13. Questions for Michael before implementation starts

These are the decisions Claude Code cannot make unilaterally. Answer these inline in the doc or in chat before kicking off Phase 1.

1. Keyboard shortcut for Resolve — I've proposed ⌘R (with a confirm). Browsers intercept ⌘R for page reload. Alternative: ⌘⇧R or no shortcut. Preference?
2. Default templatize_prompt_enabled value — I defaulted to true. If your beta testers find it annoying we'll learn fast, but it's a tradeoff between "every engineer sees the prompt" and "feature gets discovered only by those who know about it".
3. Resolution note posts immediately, or stage for review? — Current design: engineer edits preview inline, clicks Confirm & post. Alternative: stage in CW as draft note for a supervisor to approve before posting. Affects MSPs with strict compliance.

---

End of document