resolutionflow/docs/FlowAssist_Migration/CODEX-FlowAssist-Migration-PLAN.md

FlowPilot Migration Plan: Phase 0 Through Phase 7

Summary

• Stay code-change-free until execution is explicitly requested.
• Implement in commit-sized phases, with Phase 0 as a prerequisite for AI-heavy Phases 2+.
• Use this repo’s existing /api/v1/ai-sessions API namespace instead of the doc’s generic /sessions path.
• Move the existing chat-first AssistantChatPage to /pilot; /assistant becomes a permanent redirect.
• Keep ai_sessions.session_type for compatibility, but the user-facing product becomes one FlowPilot surface.

Phase 0: Prompt Caching Infrastructure

• Consolidate Anthropic prompt caching into backend/app/core/ai_provider.py, then route all Anthropic calls through that provider.
• Preserve the existing cached behavior from assistant_chat_service, but remove the private duplicate cached implementation once provider parity exists.
• Add cache-control blocks for static system prompt sections and stable tool/context prefixes; keep volatile user messages outside the cached prefix.
• Update one-shot AI generators and /tickets/ai-parse to separate stable context from changing request content.
• Instrument every Anthropic response with cache_read_input_tokens and cache_creation_input_tokens.
• Acceptance: two identical FlowPilot/provider-backed calls within 5 minutes show creation tokens on the first call and read tokens on the second.

Phase 1: Schema + Route Rename

• Add Alembic migration after current repo head with:
  • session_facts
  • session_suggested_fixes
  • draft_templates
  • account_settings
  • new artifact columns on ai_sessions
  • provenance columns on script_templates
• Create account_settings as one lazy row per account:
  • account_id primary key, FK to accounts(id) with cascade delete
  • preferences JSONB NOT NULL DEFAULT '{}'
  • timestamps
  • get_setting(key, default) helper on the SQLAlchemy model
  • templatize_prompt_enabled default read as true when the row/key is absent
• Apply RLS to all new tenant-scoped tables using the repo’s app.current_account_id policy pattern.
• Route /pilot and /pilot/:sessionId to the existing chat UI; redirect /assistant and /assistant/:sessionId permanently.
• Update sidebar, command palette, dashboard cards, session list links, and visible labels from “AI Assistant”/ResolutionAssist to “FlowPilot” where they describe the troubleshooting surface.
• Acceptance: /pilot renders the chat UI, /assistant redirects, RLS grep/check passes, and no Phase 2 UI is introduced yet.

Phase 2: What We Know

• Add FactSynthesisService for conservative conversion of answers/check outputs into facts.
• Add fact APIs under /api/v1/ai-sessions/{id}/facts:
  • list, create manual note, update editable fact, soft-delete, promote source item.
• Extend unified_chat_service marker parsing with [PROMOTE]; do not create a separate marker pipeline.
• Because current questions/checks live in ai_sessions.pending_task_lane JSON, Phase 2 must assign stable UUIDs to task-lane questions/actions/checks when they are first persisted. session_facts.source_ref points to those stable JSON item IDs; it remains polymorphic and unconstrained at the DB level.
• Add frontend task lane components under the new FlowPilot component namespace:
  • TaskLane
  • WhatWeKnow
  • WhatWeKnowItem
  • AddNoteButton
  • moved/refactored Questions and Diagnostic Checks sections
• Place What We Know above Questions. Facts from questions/checks are read-only at the fact card level; manual and AI-synthesis facts are editable.
• Acceptance: answering a question or completing a check can promote a fact within 2 seconds; manual notes persist; page reload preserves facts; cross-account access is blocked.

Phase 3: Suggested Fix + Resolve Preview

• Add suggested-fix APIs under /api/v1/ai-sessions/{id}/suggested-fixes:
  • get active suggested fix
  • record decision for one-off/draft-template/build-template/dismissed
• Extend unified_chat_service marker parsing with [SUGGEST_FIX]; supersede the prior active fix when a new one is persisted.
• Add ResolutionNoteGeneratorService that builds the fixed markdown shape:
  • Problem
  • What we confirmed
  • Root cause
  • Resolution
• Add preview endpoint at /api/v1/ai-sessions/{id}/resolution-note/preview.
• Generate the preview from ai_sessions, session_facts, active suggested fix, and linked script generations; redact sensitive script parameters.
• Cache preview output by session-state version or content hash; invalidate on fact/suggested-fix/script-generation writes.
• Add SuggestedFix, ResolveButton, and ResolutionNotePreview popover. Debounce preview refresh to 500ms.
• Acceptance: a session with facts and a suggested fix shows a four-section preview; editing a fact refreshes preview; human review confirms no unsupported claims.

Phase 4: Resolve + Escalate Writebacks

• Add EscalationPackageGeneratorService with handoff-oriented markdown:
  • Problem
  • What we’ve confirmed
  • What we’ve tried
  • Current hypothesis
  • Suggested next steps
• Add preview/post endpoints under /api/v1/ai-sessions/{id}:
  • /resolution-note/preview
  • /resolution-note/post
  • /escalation-package/preview
  • /escalation-package/post
• Extend PSA writeback service using the existing PSA provider registry and post_note seam.
• Implement “confirm and fire”: engineer edits preview, clicks Confirm & post, then server posts to PSA and stores result metadata.
• Ticket status transitions must verify by re-fetching status; failed verification is surfaced as an error, not silent success.
• Resolving without a linked PSA ticket stores markdown and marks the session resolved without external posting.
• Acceptance: ConnectWise test ticket receives the note/package, status verification works, and unlinked sessions resolve locally.

Phase 5: Inline Script Generator Integration

• Add inline Script Generator components:
  • TemplateMatchPanel
  • NoTemplateDialog
  • ParameterizationPreview
• For template matches, clicking the suggested fix opens the existing Script Generator flow with parameters prefilled from facts, ticket context, account/PSA config, and AI-suggested values.
• For no-template matches, show the three-option dialog:
  • Run as one-off
  • Run now, templatize after resolve
  • Build as template now
• Persist the selected path on session_suggested_fixes.user_decision.
• Add TemplateExtractionService for converting concrete scripts into proposed parameter schemas and templated bodies.
• Link every script generation back to ai_sessions via existing script_generations.ai_session_id.
• Cmd+K → script opens the inline generator from the FlowPilot session; no Resolve keyboard shortcut is added.
• Acceptance: matched templates prefill parameters; no-match flow shows three options; all options produce the correct session/template side effects.

Phase 6: Post-Resolve Templatize Prompt

• Add TemplatizePrompt after successful Resolve only when:
  • the account setting allows prompts
  • the session has pending draft_templates
  • the user chose “Run now, templatize after resolve”
• Accept flow creates a real script_templates row with:
  • source_session_id
  • source_user_id
  • source_ticket_ref
  • accepted parameter schema/body edits
• Skip flow marks the draft rejected.
• “Don’t ask me again for this team” writes {"templatize_prompt_enabled": false} to account_settings.preferences.
• Script Library shows a pending-drafts badge/count for the account.
• Acceptance: accept creates a visible template with provenance; skip creates no template; disabled prompt is respected on the next resolve.

Phase 7: Polish

• Match the authoritative mockup HTML for spacing, colors, typography, and component structure; use PNGs for visual target confirmation.
• Add loading states for fact synthesis, preview generation, template extraction, PSA post/verify, and script generation.
• Add empty states for:
  • no facts
  • no questions
  • no checks
  • no suggested fix
  • no pending draft templates
• Add keyboard shortcuts except Resolve:
  • Cmd+K command palette
  • Cmd+Enter send composer
  • Cmd+G script generator
• At widths below 1200px, collapse the task lane into a bottom drawer.
• Use existing design tokens where present; add missing tokens only if needed to match the mockups.
• Acceptance: major screens visually compare within the doc’s tolerance, no horizontal scroll at 1280px, mobile task lane works, and shortcuts do not conflict with browser reload.

Public Interfaces

• New backend routes use /api/v1/ai-sessions/{id}/..., not /api/v1/sessions/{id}/....
• Existing chat creation/message APIs remain compatible.
• session_type remains queryable and stored, but frontend routing no longer sends chat sessions to /assistant.
• New persistent entities:
  • session_facts
  • session_suggested_fixes
  • draft_templates
  • account_settings
• New persisted artifact columns on ai_sessions store resolution/escalation markdown and PSA post metadata.

Test Plan

• Migration tests:
  • fresh DB upgrade succeeds
  • downgrade succeeds if the repo expects reversible migrations
  • new tables have RLS enabled/forced
  • tenant policy includes app.current_account_id
• Backend tests:
  • fact CRUD and promotion authorization
  • suggested-fix supersession and decision persistence
  • preview generation cache invalidation
  • Resolve/Escalate local-only behavior without PSA
  • PSA status verification failure path
  • draft-template accept/reject behavior
• Frontend tests:
  • route redirects
  • task lane rendering and persistence
  • inline editing and preview refresh
  • script generator option flows
  • templatize prompt settings behavior
  • responsive drawer behavior
• Manual QA:
  • run through one ConnectWise linked Resolve
  • run through one Escalate
  • run one template-match script path
  • run one no-template draft-template path through post-resolve save

Assumptions

• Phase 0 is included and must be complete before Phase 2 begins.
• No Resolve keyboard shortcut in this migration.
• Templatize prompt defaults to enabled.
• Resolution notes use engineer review plus Confirm & post, not supervisor staging.
• Existing component folders may be renamed opportunistically, but behavior and route migration matter more than directory-name purity.
• No backfill of What We Know for old sessions.
• Team Wiki compilation, SharePoint integration, marketplace sharing, and confidence-tier UI are out of scope.