From 8b9733b2825bc3a098f0ae72d6d0234fd29283f5 Mon Sep 17 00:00:00 2001 From: Michael Chihlas Date: Tue, 10 Mar 2026 00:42:54 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20add=20flexible=20intake=20design=20?= =?UTF-8?q?=E2=80=94=20deferred=20variables=20+=20prepared=20sessions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- .../2026-03-10-flexible-intake-design.md | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/plans/2026-03-10-flexible-intake-design.md diff --git a/docs/plans/2026-03-10-flexible-intake-design.md b/docs/plans/2026-03-10-flexible-intake-design.md new file mode 100644 index 00000000..43175dba --- /dev/null +++ b/docs/plans/2026-03-10-flexible-intake-design.md @@ -0,0 +1,139 @@ +# Plan: Flexible Intake — Deferred Variables + Prepared Sessions + +## Context + +The current intake form on procedural flows is a blocking modal that forces engineers to enter all variables before the flow starts. This creates friction because: +- Engineers don't always have all the information upfront +- Information often lives in PSA tickets, RMM tools, or was communicated verbally +- Sometimes a lead/PM has the info and wants to set up the session for an engineer to execute later + +**Goal:** Replace the blocking intake modal with two complementary workflows: +1. **Deferred Variables** — start the flow immediately, fill variables inline as you encounter them +2. **Prepared Sessions** — pre-fill variables ahead of time, optionally assign to an engineer, execute later + +--- + +## Design + +### Workflow 1: Deferred Variables (Start Now, Fill Later) + +- "Start Flow" launches the session immediately — no intake modal +- Variables begin empty +- When a step references `[VAR:server_name]` and it's unfilled, an **inline input prompt** renders in place — visually prominent with the field's label, help text, and styling that stands out (cyan border, slight glow) +- Once filled, the value persists and resolves everywhere in the session +- Engineers can also open a **"Session Variables" side panel** at any time to see/edit all variables +- At **session completion**, if required variables are still empty → soft warning with a prompt to fill them (for complete export documentation), but not a hard block + +### Workflow 2: Prepared Sessions (Set Up Ahead, Execute Later) + +- From a flow's detail page: "Prepare Session" action opens a form to fill variables + assign an engineer +- Creates a session in `prepared` state — `started_at` is null, variables populated, no steps executed +- **Assignment:** Preparer can assign to a specific engineer on their team (or leave unassigned) +- **Personal queue:** Engineers see prepared sessions assigned to them in a dedicated section (Quick Start page or Session History tab) +- Clicking a prepared session opens the flow with variables pre-populated; execution begins normally +- Unassigned prepared sessions are visible to all team members + +### Data Model Changes + +**Session model additions:** +- `prepared_by_id` — UUID FK to users, nullable. Who created the prepared session. +- `assigned_to_id` — UUID FK to users, nullable. Who should execute it. +- Use existing convention: `started_at IS NULL` = prepared, `started_at IS NOT NULL, completed_at IS NULL` = active, `completed_at IS NOT NULL` = completed + +**Session variables become mutable:** +- `session_variables` is currently write-once at session creation +- New endpoint: `PATCH /sessions/{id}/variables` — updates individual variables during an active session +- Only the session owner (or assigned engineer) can update variables + +**Migration:** One migration adding `prepared_by_id` and `assigned_to_id` columns with FK constraints. + +### Variable Resolution Changes + +**Backend:** +- No changes to export pipeline — it already resolves variables from `session_variables` +- New `PATCH /sessions/{id}/variables` endpoint accepts partial variable updates +- Session creation no longer validates required intake fields (they can be filled later) + +**Frontend — `resolveVariables()` in `lib/variableResolver.ts`:** +- Currently returns a plain string with `[VAR:x]` replaced +- New behavior: also identify unresolved variables so `StepDetail` can render inline prompts + +**Frontend — `StepDetail.tsx`:** +- When rendering step content, unresolved `[VAR:x]` references render as inline input components +- Inline prompt design: input field with the field's label as placeholder, cyan border, subtle glow background to make them visually prominent and easy to spot +- On blur/enter: calls `PATCH /sessions/{id}/variables` → re-renders step with resolved value +- Lookup field metadata (label, field_type, help_text, options) from the intake form definition in the tree snapshot + +**Frontend — Session Variables Panel:** +- Existing "View Parameters" button becomes "Session Variables" — now editable +- Shows all intake form fields with filled/unfilled status +- Unfilled required fields highlighted +- Editing a field here updates the session and re-resolves all visible steps + +### API Changes + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `PATCH` | `/sessions/{id}/variables` | Update one or more session variables (partial dict merge) | +| `POST` | `/sessions` | Remove required-field validation for intake forms (allow empty start) | +| `GET` | `/sessions` | Add `assigned_to_id` and `status=prepared` filter params | +| `POST` | `/sessions/prepare` | New endpoint: create a prepared session with variables + optional assignee | + +### UI Changes + +| Location | Change | +|----------|--------| +| **Flow detail page** | "Start Flow" no longer shows intake modal. Add "Prepare Session" option (dropdown or secondary button) | +| **ProceduralNavigationPage** | Remove `IntakeFormModal` gating. Add "Session Variables" panel button. Inline prompts on steps with unfilled variables | +| **StepDetail** | Render inline input prompts for unresolved `[VAR:x]` references | +| **Quick Start page** | New "Prepared for You" section showing assigned prepared sessions | +| **Session History** | New "Prepared" tab/filter showing prepared sessions | +| **Prepare Session form** | New modal/page: select flow, fill variables, assign engineer, save | +| **Session completion** | Soft warning if required variables still empty | + +### What Gets Removed + +- `IntakeFormModal.tsx` — no longer used as a blocking gate (may repurpose as the "Prepare Session" form) +- Required-field validation in `POST /sessions` for intake form fields +- The `showIntakeForm` / intake modal state in `ProceduralNavigationPage` + +--- + +## Implementation Phases + +### Phase 1: Mutable Variables + Inline Prompts +**Files:** `sessions.py`, `variableResolver.ts`, `StepDetail.tsx`, `ProceduralNavigationPage.tsx` +1. Add `PATCH /sessions/{id}/variables` endpoint +2. Remove intake form required-field blocking from `POST /sessions` +3. Update `resolveVariables()` to identify unresolved variables +4. Build inline variable prompt component for `StepDetail` +5. Make "View Parameters" panel editable +6. Remove `IntakeFormModal` gating from `ProceduralNavigationPage` + +### Phase 2: Prepared Sessions +**Files:** `sessions.py`, `session.py` (schemas), migration, `PrepareSessionModal.tsx`, `QuickStartPage.tsx`, `SessionHistoryPage.tsx` +1. Migration: add `prepared_by_id`, `assigned_to_id` to sessions table +2. `POST /sessions/prepare` endpoint +3. `GET /sessions` filter support for `assigned_to_id` and prepared status +4. Prepare Session modal/form (reuse IntakeFormModal field rendering) +5. "Prepared for You" section on Quick Start +6. "Prepared" filter on Session History + +### Phase 3: Polish +1. Soft completion warning for unfilled required variables +2. Prepared session staleness indicator (optional) +3. Notification when a session is prepared/assigned to you (optional, future) + +--- + +## Verification + +- Start a procedural flow without filling any variables → flow starts immediately, no modal +- Navigate to a step with `[VAR:server_name]` → see inline input prompt +- Fill the variable inline → value resolves across all steps +- Open Session Variables panel → see all fields, edit one → reflected in steps +- Prepare a session from flow detail page → assign to another engineer +- Log in as assigned engineer → see prepared session in Quick Start queue +- Click prepared session → flow opens with variables pre-filled, execute normally +- Complete a session with one unfilled required variable → see soft warning +- Export session → variables resolved in output, unfilled ones show as `[VAR:x]` or blank