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