resolutionflow/docs/FLOWPILOT-AND-RESOLUTIONASSIST.md

FlowPilot & ResolutionAssist

ResolutionFlow offers two AI-driven troubleshooting modes that share the same session backend but present very different interaction styles. Both work standalone and become richer when paired with a PSA connection.

---

At a glance

	FlowPilot	ResolutionAssist
Style	Guided, structured	Conversational, freeform
Entry	/pilot	/assistant
Interaction	Questions → Actions → Resolution, one step at a time	Natural chat with inline questions/actions
Best for	Reproducible workflows, low-context engineers, handoffs	Exploratory problems, quick lookups, rubber-ducking
Lifecycle	Active → Paused → Resolved / Escalated / Abandoned	Active → Resolved / Abandoned (lightweight)
Confidence tracking	Yes — drives tier transitions	No — always responsive to user direction
Navigation guard	Yes — prevents accidental loss	No — free to leave and return

Both modes share the ai_sessions table (discriminated by session_type), the same multimodal AI backend (image uploads, markdown, cached prompts), and the same [QUESTIONS] / [ACTIONS] / [FORK] marker vocabulary that renders inline TaskLane elements.

---

FlowPilot — guided troubleshooting

FlowPilot is a wizard-style AI engineer that walks you through a problem one diagnostic step at a time. It runs on confidence tiers:

• Discovery (confidence < 0.4) — asking broad, open-ended questions to characterize the problem
• Exploring (0.4–0.8) — proposing targeted actions and narrowing hypotheses
• Guided (≥ 0.8) — recommending a specific fix with steps to verify

The FlowPilot session flow

1. Intake. You start from /pilot or from the dashboard "New Session" button. The intake screen accepts free-text description, PSA ticket context, screenshots, or log pastes.
2. Preference check. Before suggesting any fix, the AI asks whether you want a GUI or script approach. This is enforced in the system prompt so you never get steps you can't execute.
3. Step-by-step progression. Each AI response is either a question (with clickable options), an action (with "Done" / "Didn't work" buttons), a [FORK] (two distinct paths to try), or a final resolution suggestion. You respond, the AI updates its confidence, and the next step is generated.
4. Action bar. The session header always shows Pause & Leave, Resolve, Escalate, Share Update, and Close. Pausing freezes the session; resuming restores the full context.
5. Resolve / Escalate. Resolve marks the ticket fixed and generates a clean summary of what worked. Escalate packages the problem summary and steps tried into an escalation package that the next engineer (or the PSA ticket) inherits.

Why FlowPilot exists

• New engineers get senior-engineer-level diagnostic rigor without needing the experience to know what to ask next.
• Documented resolutions — every step is captured, so the generated note on the ticket is substantive (not just "fixed it").
• Handoff-friendly — escalation packages mean the next person doesn't start from zero.

---

ResolutionAssist — conversational AI

ResolutionAssist is a chat with an expert IT systems engineer. It's less structured than FlowPilot but still surfaces interactive elements when the AI wants structured input.

The ResolutionAssist flow

1. Open a chat. From /assistant or the dashboard. Sessions show up in the left sidebar just like any messaging app.
2. Send a message. Freeform prose. Attach up to 3 images per message (screenshots, error dialogs, network diagrams). Paste logs, code, or PowerShell output.
3. AI responds. The response is prose, but any [QUESTIONS] or [ACTIONS] blocks render as a TaskLane — a side panel with clickable options and action buttons. You can answer via chat or click the TaskLane elements.
4. Branching ([FORK]). If the AI proposes two paths ("check cable or restart switch?"), the fork renders as a choice. Picking one continues the conversation down that path.
5. Resume later. Unlike FlowPilot, there's no navigation guard. Leave mid-conversation; every message is stored.

Why ResolutionAssist exists

• Unstructured problems — "I have no idea where to start, here's a screenshot" works great.
• Reference lookups — "what's the right PowerShell command to check Exchange health" is faster in chat than through an intake form.
• Senior engineers — when you already know what you're doing and just want a second opinion or a syntax check.

---

Without a PSA connection

Both modes work standalone. Without ConnectWise connected:

• Sessions live entirely in ResolutionFlow. They're listed in your session history, searchable, and shareable via public share links (/shared/sessions/:token).
• Summaries generated on Resolve are saved to the session record but not written anywhere else. You can copy/paste into whatever ticketing or documentation system you use.
• Escalating a FlowPilot session routes the escalation package to another ResolutionFlow engineer on your team — not to an external PSA ticket.
• No ticket context is injected into the AI prompt, so the AI starts cold with only what you provide in the intake or first message.

Standalone use cases:

• Evaluating ResolutionFlow before committing to a PSA integration
• Troubleshooting internal IT issues that aren't client-facing
• Teams using a PSA ResolutionFlow doesn't integrate with yet
• Knowledge-base research ("what are my options for X") that don't map to a ticket

---

With a PSA connection (ConnectWise)

When ConnectWise is connected, both modes become ticket-aware and write back to the PSA as a first-class client.

FlowPilot + PSA

Starting from a ticket:

• Click a ticket row (from /tickets or the dashboard queue) and pick "Start FlowPilot." The ticket's problem description, recent notes, configurations, company details, and related tickets are auto-injected into the AI's context. No manual retyping.
• The session shows the linked ticket badge in the header.

During the session:

• Share Update — posts an interim note to the CW ticket with the current AI summary, so stakeholders can see progress without interrupting you.
• Status changes — the detail panel and session header let you move the ticket through statuses (New → In Progress → Waiting on Customer → Resolved) directly from ResolutionFlow. Status writes are verified against CW so you're never told "success" when CW silently rejected the change.
• Resource assignment — add yourself or a teammate as a co-assignee without touching the owner. If the ticket has no owner yet, assigning sets owner; if there's already an owner, you're added as an additional resource via a CW schedule entry.

On Resolve:

• Final summary is posted as a ticket note.
• Ticket status can auto-update to Resolved (per your team's settings).

On Escalate:

• The escalation package (problem summary + steps tried) is posted as a note.
• The ticket can be routed via CW's normal escalation rules.
• The next engineer picking up the ticket can auto-start a new session with the full escalation context pre-filled.

Spin-off tickets (new):

• During any session, if you discover a separate issue, the AI can propose create_spin_off_ticket. Accepting opens the New Ticket modal pre-filled with the current ticket's company and board, so a second ticket is one click away without leaving your session.

ResolutionAssist + PSA

Starting from a ticket:

• Same ticket-context injection as FlowPilot. When opened with a linked ticket, the AI sees company, configs, notes, and related tickets.
• A "New Ticket" button appears in the header — lets you spawn a separate ticket mid-conversation (same flow as FlowPilot's spin-off).

During the chat:

• Ask the AI about the ticket directly: "Summarize what's been tried," "What configs does this company have?" — the AI already has that context loaded.
• [ACTIONS] can include create_spin_off_ticket when the AI detects a separate issue surfaced in the conversation.

Writing back:

• ResolutionAssist is a lighter-weight mode, so it doesn't auto-post on resolve. You can manually copy the conversation summary to a ticket note if useful.
• Status updates and resource assignment are done via the /tickets page rather than the chat UI.

---

Choosing between them

I want to…	Use
Walk through a known issue type with step-by-step rigor	FlowPilot
Document every action taken for audit or handoff	FlowPilot
Escalate with a full context package	FlowPilot
Ask a question, get an answer, move on	ResolutionAssist
Paste a screenshot and say "what's wrong here?"	ResolutionAssist
Stay on the ticket for 2 minutes, not 20	ResolutionAssist
Troubleshoot without breaking flow to switch pages	Either, with the linked ticket panel open alongside

The two modes aren't competitive. A common workflow is to start in ResolutionAssist to scope the problem, then kick off a FlowPilot session when you realize the issue is going to take real diagnosis. Both show up in the unified session history.

---

Tickets page — the PSA hub

/tickets is the CW ticket manager built into ResolutionFlow. With a PSA connection:

• Search and filter tickets by assignment (me / unassigned / specific member via searchable picker), board, status, priority, company, open/closed.
• Slide-out detail panel shows notes, configurations, related tickets, and assignees — all fetched in parallel for fast hydration.
• From the detail panel: change status, add/remove assignees, post notes, or "Start FlowPilot" / "Open in ResolutionAssist" with full context.
• New Ticket modal offers both AI-parse ("Create a high-priority ticket for Acme — Outlook not syncing for jsmith") and a traditional form.

Without a PSA connection, /tickets is hidden from the sidebar entirely — there's nothing to show.

---

Summary

• FlowPilot = guided, structured, lifecycle-heavy, ideal for resolvable issues and handoffs.
• ResolutionAssist = freeform chat, ideal for scoping and quick answers.
• Without PSA = both work, sessions live in ResolutionFlow, summaries are yours to export.
• With PSA = both become ticket-aware, write back to CW (notes, status, resources), and can spawn spin-off tickets mid-session.

The AI is the same under the hood. The difference is how much structure you want around the conversation — and how deeply the result needs to integrate with your ticketing system.