resolutionflow/03-DEVELOPMENT-ROADMAP.md

# Development Roadmap

> **Last Updated:** May 7, 2026
> **Product:** ResolutionFlow (repo path: `resolutionflow/`; `patherly` is the legacy internal name)
> **Target Market:** MSP companies — IT service providers managing infrastructure and support for multiple clients

---

## Status as of 2026-05-07

The historical phase content below (Phase 1 through Phase 5) is preserved as a factual record. **This section is the live status overlay — read it first.**

**Where we are:** Pre-PMF, Go-to-Market Validation. Backend feature-complete (50+ endpoints, 100+ tests). FlowPilot session UX is the daily-driver surface and recently went through PR #155 (escalation wedge), #156 (`applied_pending` non-terminal status), #158 (impeccable pass + tasklane keyboard flow), #159 (Diátaxis User Guides), #160 (sidebar IA + account redesign).

**Currently in flight:** Self-serve signup cutover. Phase 1 backend (#161) and Phase 2 frontend (#162) merged. PR #164 (open) closes the last code blockers — plan taxonomy reconciliation (`team` → `enterprise`, add `starter`) and `INTERNAL_TESTER_EMAILS` allowlist for the soft cutover. After merge, remaining work is **manual operations only**: Stripe Dashboard live-mode setup, Railway prod env vars, internal validation pass, public flag flip. See `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-2-frontend-cutover.md` Phase O for the checklist.

**Product thesis being tested:** "We're not a documentation app. We are the documentation builders." Captured in `~/.gstack/projects/chihlasm-resolutionflow/abc-feat-self-serve-signup-phase-2-design-20260507-112020.md` (office-hours design doc). Pre-build assignment: 3 calls with external Directors of Onboarding (cold, no friendly contacts) to validate the framing before adopting it as the public positioning.

**What's not yet decided:** Whether to formally cut branching Flows from the pilot UI surface in favor of a Project (linear procedure) + FlowPilot + Documentation-Builder positioning. Discussed in /office-hours but no implementation work scheduled — gated on the 3 external validation calls.

---

## Completed Work

### Phase 1: MVP
- FastAPI backend with 25+ API endpoints, PostgreSQL, Docker, Alembic migrations
- JWT auth with refresh token rotation, invite codes, password complexity
- Trees CRUD, sessions, export (Markdown/Text/HTML), full-text search
- React 19 + Vite + TypeScript + Tailwind frontend
- Tree navigation (session player), session history, export download
- Production deployment on Railway (resolutionflow.com)
- 7 seed decision trees, 100+ integration tests

### Phase 2: Team-Ready
- RBAC (super_admin, team_admin, engineer, viewer) with `usePermissions` hook
- Tree Editor — form-based with visual canvas preview, Zustand + immer + zundo (undo/redo)
- Tree organization — categories, tags (autocomplete), user folders (3-level hierarchy)
- Admin panel — 8 pages (users, invite codes, audit logs, plan limits, feature flags, settings, categories)
- Session enhancements — timer, keyboard hints, repeat last, auto-recovery, scratchpad (Ctrl+/)
- Session outcomes with step timing tracking
- Mobile-responsive design
- Security hardening (Phases A-D) — rate limiting, audit logs, soft delete, SQL escaping

### Phase 2.5: Step Library & Procedural Flows
- **Step Library** — CRUD, search, ratings, reviews, visibility filtering, verified-use badge (backend complete, frontend browse/search/rate pending)
- **Procedural flows** — `procedural` tree type, step-by-step execution engine, intake forms, section headers, resume support, type-aware routing, auto-start on page load
- **Maintenance flows** — `maintenance` tree type, batch session launch, saved target lists, APScheduler cron scheduling, maintenance detail page
- **Session sharing** — ShareSessionModal, SharedSessionPage, MySharesPage, share links with copy/manage
- **Export improvements** (Phases A-C) — step cutoff, summary block, detail levels, editable preview, sensitive data redaction
- **Rebrand** — Patherly → ResolutionFlow branding, Slate & Ice glassmorphism design system
- **Flexible intake** — deferred variable resolution, prepared sessions for reuse

### Phase 3: Intelligence & Polish (Mar 2026)
- **AI Flow Assist** — Conversational AI chat builder for generating troubleshooting and procedural flows. Multi-phase interview, progressive tree generation with live preview, save to flow library
- **Cross-Reference / Loop-Back Support** — Ghost references, dashed purple arrows, node picker dropdowns, circular reference detection as warnings
- **Editor-Embedded Flow Assist** — 320px AI side panel in editor, ghost node suggestions, delta responses, model tier routing
- **Procedural Flow Assist** — AI suggestions for procedural flow editing with `[STEPS_UPDATE]` markers
- **AI Chat Conclusion** — Outcome tracking, AI-generated ticket summaries, resume flow
- **AI Copilot** — In-session copilot panel with RAG, standalone assistant chat
- **KB Accelerator** — Upload .md files and convert to troubleshooting/procedural flows with AI, tree builder with validation gate
- **Script Generator** — Backend engine with parameter detection, template editor with conditional/looping, PowerShell and Bash generation
- **Command Palette** — Quick flow navigation and actions (Ctrl+K)
- **Session-to-Flow Converter** — AI-powered conversion of finished sessions into reusable flows
- **Sidebar Redesign** — Activity feed, grouped navigation, improved flow discovery
- **Flow Export/Import** — JSON export, import with validation, cross-team flow transfer
- **Survey System** — Public survey page, admin invite tracking, response viewer with CSV export, email invitations, read/unread/archive/delete management
- **Email Verification** — Tokens, banner, admin toggle (platform setting)
- **Account Management** — Profile settings, delete/leave/transfer team, chat retention settings
- **Slate & Ice Aesthetic Redesign** — Glassmorphism with ice-cyan accents, Bricolage Grotesque + IBM Plex Sans + JetBrains Mono typography, orchestrated page-load animations
- **Tailwind CSS v3 → v4 Migration** — CSS custom properties, glass utilities, React Flow CSS integration
- **Landing Page + Beta Signup** — Marketing-ready landing page with CSS polish
- **PostHog Product Analytics** — 60+ events instrumented, PostHogProvider, identifyUser/resetAnalytics wired to auth, Dockerfile build args for Railway
- **Playwright E2E Tests** — 17 spec files, full CI job, auth storage state, both webServers managed in config
- **ConnectWise PSA Integration (Core)** — Provider pattern (`BasePsaProvider` / `ConnectWiseProvider`), connection CRUD, ticket context retrieval, session-to-ticket linking, member mapping, credential encryption, in-memory TTL cache

### Phase 3.5: Polish & Professional (Mar 2026 — PR #114)
- **Empty States** — Illustrative empty states across 8 pages, upgraded EmptyState component with illustration + learn-more support
- **Onboarding Checklist** — Backend status/dismiss endpoints, dashboard checklist widget with structured steps
- **Professional PDF Export** — WeasyPrint branded template, supporting data in all export formats
- **Team Branding** — CRUD endpoints + UI settings for export customization
- **Supporting Data Capture** — CRUD endpoints + UI for attaching evidence/context to sessions

---

## In Progress

| Task | Status | Notes |
|------|--------|-------|
| Self-serve signup cutover (Phase O) | In Progress | PR #164 merge → Stripe live-mode Dashboard setup → Railway prod env vars → internal validation → public flag flip. Code blockers cleared by #164 (taxonomy + `INTERNAL_TESTER_EMAILS` allowlist). |
| External validation of documentation-builder thesis | Not started | 3 calls with external Directors of Onboarding (cold). Decision gate before scoping a "Day 1 onboarding checklist" build. |
| ConnectWise PSA Integration (Advanced) | Deferred | Core complete — ticket linking, note posting, member mapping, ticket context retrieval. Callback webhooks deferred until pilot signal demands them. |

---

## What's Next

### Phase O Cutover (Weeks 0-1)

| Step | Status |
|---|---|
| Merge PR #164 (taxonomy reconciliation + allowlist) | Open, CI green |
| Stripe Dashboard live-mode setup (Products + Prices for Starter/Pro, no Prices on Enterprise, Customer Portal config, webhook endpoint with 5 events) | Manual op |
| Railway prod env vars (`sk_live_*`, `whsec_*`, `INTERNAL_TESTER_EMAILS`, prod Google + Microsoft OAuth credentials, `OAUTH_REDIRECT_BASE`, `STRIPE_PUBLISHABLE_KEY`, `VITE_STRIPE_PUBLISHABLE_KEY` for frontend redeploy) | Manual op |
| Run `python -m scripts.sync_stripe_plan_ids` against prod backend; verify `plan_billing` has `sk_live_*` price IDs | Manual op |
| Internal validation pass (9 scenarios from Phase O Task 46) | Manual op |
| Email pilots about complimentary status, flip `SELF_SERVE_ENABLED=true` (frontend redeploy required for `VITE_SELF_SERVE_ENABLED`) | Manual op |
| PostHog signup-funnel dashboard + Sentry alert at >1/hour Stripe webhook errors | Manual op |

### Near-Term Priorities (from Stack Priorities Plan)

| Feature | Status | Description |
|---------|--------|-------------|
| Coverage gates in CI | ✅ Complete | Backend enforced at 80%, frontend coverage reporting enabled |
| Security headers | ✅ Complete | HSTS, CSP (report-only), X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy |
| Web Vitals / performance budgets | ✅ Complete | LCP, INP, CLS, FCP, TTFB reported to PostHog via web-vitals |
| Search and recall improvements | ✅ Complete | Structured filters + FTS + Voyage AI semantic search shipped (see CURRENT-STATE.md "Search & Recall" section) |

### 3A: Quick Wins & UX (Priority: Medium)

| Feature | GitHub Issue | Description |
|---------|-------------|-------------|
| Quick Actions Dashboard | #70 | Landing page with recent sessions, pinned flows, one-click actions |
| Step Feedback Flag | #58 | "This Step is Wrong" flag during sessions — feeds back to tree authors |
| Quick-Start from Clipboard | #62 | Paste a ticket description, AI suggests the best matching flow |

### 3B: Analytics & Intelligence (Priority: Medium)

| Feature | GitHub Issue | Description |
|---------|-------------|-------------|
| Tree Effectiveness Dashboard | #61 | Usage stats, common paths, avg completion time, success rates per flow |
| Recurring Issue Detection | #60 | Identify repeat problems across sessions — surface patterns to team leads |

### 3D: Remaining Infrastructure
- File attachments for sessions (S3-compatible storage, drag-and-drop, screenshot paste)
- Tree forking UI (backend schema exists — migration 022)
- Step Library frontend completion

---

## Phase 4: Integrations & Automation

**Goal:** Connect ResolutionFlow to the MSP tools teams already use.

### 4A: PSA Integration (Priority: HIGH — Core Complete)

| Feature | GitHub Issue | Description |
|---------|-------------|-------------|
| ConnectWise PSA — Advanced | #63 | ~~Core integration~~ ✅ — Remaining: callback webhooks, real-time ticket events, deeper session context |
| Autotask PSA | — | Second PSA provider using same `BasePsaProvider` pattern |

### 4B: Intelligence Layer (Priority: Strategic)

| Feature | GitHub Issue | Description |
|---------|-------------|-------------|
| Client Intelligence Sidebar | #64 | Per-client context panel — past sessions, known issues, environment details |
| Intelligence Loop / Analytics Engine | #65 | Cross-session pattern analysis, auto-suggest flow improvements, team benchmarking |

### 4C: Automation
- PowerShell script execution framework with security sandbox (script generator foundation complete)
- Script library management
- Automation toggle at action nodes

### 4D: Enterprise
- SSO integration (SAML/OAuth)
- Advanced RBAC and approval workflows
- White-label configuration

---

## Phase 5: Collaboration & Advanced AI

**Goal:** Team-oriented features and deeper AI integration.

### 5A: Team Features

| Feature | GitHub Issue | Description |
|---------|-------------|-------------|
| Team Activity Feed | #71 | Real-time feed of team activity — new sessions, shared flows, completions |
| Push Steps to Active Sessions | #67 | Senior engineers can push guidance to an active session in real-time |

### 5B: Advanced AI

| Feature | GitHub Issue | Description |
|---------|-------------|-------------|
| Multi-Tree Sessions | #68 | Navigate across multiple flows in a single session, AI-suggested flow transitions |

> **Note:** AI Copilot (#69) completed in Phase 3. Session-to-Flow converter and KB Accelerator also delivered.

### 5C: Platform Growth
- Public API with key management and webhooks
- Community tree marketplace
- Mobile apps (React Native)
- Slack / Teams integration

---

## Long-Term Vision

- Self-learning flows (improve automatically based on usage patterns)
- Vertical-specific flow libraries (healthcare IT, financial services, education)
- Advanced compliance (SOC 2, ISO 27001)
- Voice-guided troubleshooting
- Evidence-rich sessions (screenshots, attachments, command output capture)
- Buyer-facing trust surfaces (changelog, status page, security page)
- Queue / worker architecture for AI, indexing, webhook fan-out

---

## Open GitHub Issues Summary

| # | Title | Priority | Phase | Status |
|---|-------|----------|-------|--------|
| #63 | PSA Integration (ConnectWise / Autotask) | HIGH | 4A | Core complete, advanced in progress |
| #70 | Quick Actions Dashboard | Medium | 3A | Not started |
| #66 | Tree Templates + Import/Export | Medium | 3C | ✅ Export/Import done |
| #62 | Quick-Start from Clipboard | Medium | 3A | Not started |
| #61 | Tree Effectiveness Dashboard | Medium | 3B | Not started |
| #60 | Recurring Issue Detection | Medium | 3B | Not started |
| #58 | Step Feedback Flag | UX | 3A | Not started |
| #64 | Client Intelligence Sidebar | Strategic | 4B | Not started |
| #65 | Intelligence Loop / Analytics Engine | Strategic | 4B | Not started |
| #71 | Team Activity Feed + Collaboration | Low | 5A | Not started |
| #69 | AI Copilot — In-Session Intelligence | Low | 5B | ✅ Complete |
| #68 | Multi-Tree Sessions | Low | 5B | Not started |
| #67 | Push Steps to Active Sessions | Low | 5A | Not started |