docs: Add Session Scratchpad design and update project references

- Add Session Scratchpad design doc (Idea 6 from brainstorm) - Update CLAUDE.md production URLs to resolutionflow.com - Update CORS lesson domain refs for rebrand - Add .claude/settings.local.json to gitignore docs - Add docs/plans/ to project structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-04 02:34:25 -05:00
parent d28fad7066
commit a09f62a751
3 changed files with 340 additions and 5 deletions
--- a/docs/plans/2026-02-04-feature-ideas-brainstorm.md
+++ b/docs/plans/2026-02-04-feature-ideas-brainstorm.md
@@ -12,6 +12,7 @@ Every feature should follow the core principle that makes ResolutionFlow work:
 **Engineers don't document — they troubleshoot, and the tool captures documentation as a byproduct.**

 New features should:
+
 - Reduce engineer cognitive load
 - Automate capture of what they're already doing
 - Make reusing knowledge frictionless
@@ -42,23 +43,28 @@ New features should:
 **Effort:** Small (backend export change, no new UI)

 ### What
+
 Every session automatically tracks duration (start → end) and includes it in the export.

 ### Export Output
+
 ```
 Session Duration: 23 minutes
 Started: 2:30 PM | Completed: 2:53 PM
 ```

 ### Why
+
 MSP engineers bill by the hour. They troubleshoot in ResolutionFlow, export notes, then separately log time in their PSA. This eliminates the second step.

 ### Implementation Notes
+
 - Timestamps already exist in session decisions — just compute elapsed time
 - Add duration to export templates (markdown, text, HTML)
 - No new UI required — purely a backend export enhancement

 ### Future Enhancement
+
 - When PSA integration exists: if no PSA connected, ResolutionFlow tracks time natively. If PSA connected, still track time but also push it directly to the ticket in the PSA.
 - Analytics: average resolution time per tree, per client, per engineer

@@ -70,6 +76,7 @@ MSP engineers bill by the hour. They troubleshoot in ResolutionFlow, export note
 **Effort:** Medium

 ### What
+
 Two mechanisms for sharing in-progress troubleshooting context:

 1. **"Share Progress" button** (available mid-session) — generates a formatted summary of steps completed so far. Copy to clipboard, paste into Teams/Slack. One click instead of typing "here's what I've tried."
@@ -77,6 +84,7 @@ Two mechanisms for sharing in-progress troubleshooting context:
 2. **Read-only session link** — shareable URL where anyone with the link can see the session state. If they sign in and get assigned, they can resume from where the previous engineer left off.

 ### Workflow
+
 1. Junior engineer gets stuck → clicks "Share Progress"
 2. Pastes formatted summary into Teams chat with senior
 3. Senior reads structured summary (not a wall of chat text)
@@ -84,11 +92,13 @@ Two mechanisms for sharing in-progress troubleshooting context:
 5. If escalating: ticket reassigned in PSA, senior resumes the session in ResolutionFlow

 ### Implementation Notes
+
 - Copy/paste version is nearly free — existing export logic on incomplete sessions + "Steps remaining" section
 - Read-only link: generate share token, create public read-only session view (no auth)
 - Resume capability: allow session reassignment to another user

 ### Why This Matters
+
 Eliminates the "what have you tried so far?" back-and-forth that happens on every escalation. The structured format means the senior gets context in 30 seconds instead of 10 minutes of chat.

 ---
@@ -99,9 +109,11 @@ Eliminates the "what have you tried so far?" back-and-forth that happens on ever
 **Effort:** Small

 ### What
+
 Action nodes (which show commands to run) get an optional "Paste Output" text area. Engineer runs the command, copies output, pastes it in.

 ### Export Output
+
 ```
 > Ran: Get-Service -Name Spooler
 > Output:
@@ -111,15 +123,18 @@ Action nodes (which show commands to run) get an optional "Paste Output" text ar
 ```

 ### Why
+
 Engineers already run commands and read output. Today the output is lost — the export says "ran this command" but not what it returned. This captures the evidence.

 ### Implementation Notes
+
 - Add optional `command_output` field to session decision JSONB
 - Add collapsible text area below commands on action nodes in TreeNavigationPage
 - Include in export with code formatting
 - Pairs well with Scratchpad (Idea 6) and Share Progress (Idea 2)

 ### Future Enhancement
+
 - Syntax highlighting for common output formats (PowerShell, JSON)
 - Image paste for screenshots of GUI-based evidence

@@ -131,9 +146,11 @@ Engineers already run commands and read output. Today the output is lost — the
 **Effort:** Medium-Large

 ### What
+
 A senior engineer (or anyone) can send a troubleshooting step directly to someone's active session. Flips the step library from a pull model (browse and find) to a push model (someone sends it to you).

 ### Workflow
+
 1. Junior shares progress link (Idea 2)
 2. Senior sees they're stuck at "VDA not registering"
 3. Senior picks a step from their personal library (or types one quickly)
@@ -143,15 +160,18 @@ A senior engineer (or anyone) can send a troubleshooting step directly to someon
 7. Step documented in export, optionally saved to junior's library

 ### Why
+
 Replaces unstructured Teams/Slack troubleshooting advice with structured, documented, reusable steps. The knowledge stays in the system.

 ### Implementation Notes
+
 - Requires lightweight notification/inbox system (polling or WebSocket)
 - Builds on: Share Progress (Idea 2) + Step Library (existing)
 - New API: `POST /api/v1/sessions/{id}/send-step`
 - Frontend: notification badge + step insertion flow

 ### Analytics Potential
+
 - Which seniors send the most steps (mentorship tracking)
 - Which pushed steps get reused (knowledge value)
 - Which juniors receive fewer pushes over time (skill growth)
@@ -164,6 +184,7 @@ Replaces unstructured Teams/Slack troubleshooting advice with structured, docume
 **Effort:** Medium

 ### What
+
 Aggregate completed session data to show statistical hints on decision nodes:

 - Badge: "78% of engineers chose Option B here"
@@ -171,9 +192,11 @@ Aggregate completed session data to show statistical hints on decision nodes:
 - At common stuck points: "Engineers often add a custom step here"

 ### Why
+
 Delivers on the tagline. For a junior engineer staring at three options, seeing "most engineers went this way" is a confidence boost. For tree authors, analytics reveal dead-end branches.

 ### Implementation Notes
+
 - Aggregate query on session `path_taken` and `decisions` JSONB
 - Compute per-node: choice distribution, resolve rate, custom step frequency
 - Cache aggregates (recompute daily or on-demand)
@@ -181,6 +204,7 @@ Delivers on the tagline. For a junior engineer staring at three options, seeing
 - Resolve rate: track whether session completed at a solution node + optional "did this fix it?" prompt

 ### Data Requirements
+
 - Needs sufficient session volume per tree to be statistically meaningful (suggest: show after 10+ sessions)
 - Weight recent sessions higher than old ones

@@ -193,12 +217,15 @@ Delivers on the tagline. For a junior engineer staring at three options, seeing
 **Priority:** Must-have (per Michael)

 ### What
+
 A persistent sidebar during active sessions for capturing ambient data: IP addresses, error codes, server names, usernames — anything that doesn't fit a specific decision node's notes field.

 ### Why
+
 During troubleshooting, engineers accumulate bits of data (from `ipconfig`, Event Viewer, phone conversations) that live on sticky notes or in their head. This gives it a home and includes it in the export.

 ### Export Output
+
 ```
 ## Evidence / Reference
 - Server IP: 192.168.1.50
@@ -208,6 +235,7 @@ During troubleshooting, engineers accumulate bits of data (from `ipconfig`, Even
 ```

 ### Implementation Notes
+
 - Persistent sidebar (collapsible) in TreeNavigationPage
 - Store in session JSONB as `scratchpad` array of entries
 - Each entry: text + optional label + timestamp
@@ -216,6 +244,7 @@ During troubleshooting, engineers accumulate bits of data (from `ipconfig`, Even
 - Future: structured key-value pairs, tags, image paste

 ### Pairs With
+
 - Command Output Capture (Idea 3): structured output at nodes + freeform notes in scratchpad = complete evidence
 - Share Progress (Idea 2): scratchpad content included in shared summary

@@ -227,9 +256,11 @@ During troubleshooting, engineers accumulate bits of data (from `ipconfig`, Even
 **Effort:** Large

 ### What
+
 When troubleshooting reveals the problem is in a different domain, branch into another tree mid-session without losing context. The export captures the entire journey.

 ### Workflow
+
 1. Engineer is in "VPN Issues" tree, 5 steps deep
 2. Discovers the actual problem is DNS, not VPN
 3. Clicks "Open Related Tree" → selects "DNS Resolution Issues"
@@ -238,6 +269,7 @@ When troubleshooting reveals the problem is in a different domain, branch into a
 6. Export shows unified narrative with both trees

 ### Export Output
+
 ```
 ## VPN Connection Issues
 1. Verified VPN client version: OK
@@ -255,6 +287,7 @@ When troubleshooting reveals the problem is in a different domain, branch into a
 ```

 ### Implementation Notes
+
 - Session model needs: `parent_session_id`, `branched_at_node_id`
 - "Open Related Tree" action on any node (tree selector modal)
 - Breadcrumb shows tree chain: VPN > DNS
@@ -262,6 +295,7 @@ When troubleshooting reveals the problem is in a different domain, branch into a
 - Back button returns to parent session at bookmark point

 ### Why
+
 Real troubleshooting rarely stays in one domain. This captures the full diagnostic story.

 ---
@@ -272,22 +306,27 @@ Real troubleshooting rarely stays in one domain. This captures the full diagnost
 **Effort:** Small-Medium

 ### What
+
 When an engineer starts a session and enters a client name, show previous sessions for that client in that tree. If the same resolution keeps being reached, prompt for root cause action.

 ### UI
+
 - At session start: "3 previous sessions for Warner Robins in this tree (last: Jan 28)" + link to view
 - At resolution (if recurring): "This is the 3rd time this issue was resolved the same way for this client. Consider documenting a permanent fix or escalating to address root cause."

 ### Why
+
 Turns ResolutionFlow from reactive (fix the ticket) to proactive (fix the root cause). For MSP managers, recurring issues per client = business intelligence for infrastructure upgrade proposals.

 ### Implementation Notes
+
 - Query: sessions grouped by client_name + tree_id, count + last date
 - Display at session start (inline, not blocking)
 - Recurrence prompt: compare resolution node_id across sessions
 - Future (with PSA/RMM): correlate with alert data for richer signals

 ### Data Model
+
 - No schema changes needed — query existing sessions table
 - Optional: normalize client names (fuzzy match or client_id foreign key)

@@ -299,9 +338,11 @@ Turns ResolutionFlow from reactive (fix the ticket) to proactive (fix the root c
 **Effort:** Medium

 ### What
+
 Data-driven health indicators for trees, surfaced to tree authors and admins.

 ### Signals
+
 - **Custom step frequency**: Engineers keep adding steps at the same node → tree is missing a branch
 - **Abandonment rate**: Sessions started but not completed → tree isn't leading to resolutions
 - **Low resolve rate**: Solution nodes that don't actually fix issues
@@ -309,14 +350,17 @@ Data-driven health indicators for trees, surfaced to tree authors and admins.
 - **Escalation rate**: High percentage of sessions shared/escalated from this tree

 ### Display
+
 - Green/yellow/red health badge on tree library cards
 - Author notification: "Your 'VPN Issues' tree has yellow health — 4 engineers added custom steps at 'Check Split Tunnel Config' this month"
 - Admin dashboard: team-wide tree health overview

 ### Why
+
 Creates a self-improving ecosystem. Sessions generate data → data identifies weak trees → authors improve trees → next engineer gets a better experience.

 ### Implementation Notes
+
 - Scheduled aggregation job (daily)
 - Health score algorithm: weighted combination of signals
 - Store as computed field on tree (or separate analytics table)
@@ -331,21 +375,25 @@ Creates a self-improving ecosystem. Sessions generate data → data identifies w
 **Status:** Ultimate goal

 ### What
+
 Three layers of AI, each building on the last, leveraging ResolutionFlow's unique structured troubleshooting dataset.

 ### Layer 1: Smart Tree Suggestions
+
 - Engineer pastes ticket description: "User at Warner Robins reports Outlook keeps crashing after latest update"
 - AI suggests: "Recommended: Outlook/Email Issues tree → Start at 'Recent Update' branch"
 - Not just which tree — which branch to start at, skipping generic initial questions
 - **Implementation:** NLP parsing of ticket text, match against tree node content and tags

 ### Layer 2: Session-Driven Tree Evolution
+
 - Aggregate session data reveals patterns: "35% of engineers add 'Check MFA Token' after 'Auth Failed' node, and it resolves 80% of the time"
 - Generate suggestion to tree author: "Recommended new branch based on 18 successful sessions"
 - Author reviews and approves with one click — tree evolves from real usage
 - **Implementation:** Aggregation queries + LLM formatting suggestions + author approval UI

 ### Layer 3: AI Tree Generation
+
 - Senior describes: "We keep getting Azure AD Sync issues, no tree exists"
 - AI generates complete tree draft using:
  - Similar trees in the system
@@ -356,9 +404,11 @@ Three layers of AI, each building on the last, leveraging ResolutionFlow's uniqu
 - **Implementation:** RAG over tree corpus + session data + LLM generation + tree editor integration

 ### Why This Is the Moat
+
 ConnectWise or IT Glue could build a decision tree tool. But they don't have hundreds of structured session paths with outcomes to learn from. ResolutionFlow's data is structured by design — decision trees + session paths + outcomes — not unstructured ticket notes. That's a dataset purpose-built for learning optimal troubleshooting paths.

 ### Phasing
+
 - Layer 1 can ship independently with basic NLP
 - Layer 2 needs sufficient session volume (6+ months of real usage)
 - Layer 3 needs Layers 1 + 2 data + LLM integration
@@ -371,9 +421,11 @@ ConnectWise or IT Glue could build a decision tree tool. But they don't have hun
 **Effort:** Medium

 ### What
+
 Replace the tree library as the default landing page with a troubleshooting command center.

 ### Sections
+
 - **Resume sessions** — "VPN Issues - Acme Corp (started 20 min ago)" for incomplete sessions
 - **Quick starts** — Frequent tree+client combos: "File Share Access for Warner Robins — Quick start?" One tap.
 - **Team activity** — "Sarah completed 'AD Replication' for Client X (12 min)" — visibility without a standup
@@ -381,6 +433,7 @@ Replace the tree library as the default landing page with a troubleshooting comm
 - **Recurring alerts** — Clients with repeat issues that need attention

 ### Why
+
 Turns ResolutionFlow from a tool you visit per-ticket into something you keep open all day. Reduces friction from "open app → find tree → start session" to "open app → click the obvious next action."

 ---
@@ -388,22 +441,26 @@ Turns ResolutionFlow from a tool you visit per-ticket into something you keep op
 ## Suggested Build Order

 ### Near-term (build now, small effort, immediate value)
+
 1. **Session Scratchpad** (Idea 6) — must-have per Michael
 2. **Session Time Tracking** (Idea 1) — quick win, enhances every export
 3. **Command Output Capture** (Idea 3) — quick win, pairs with scratchpad

 ### Mid-term (build next, medium effort, high value)
+
 4. **Share Progress / Escalation** (Idea 2) — daily use for team collaboration
 5. **Recurring Issue Detection** (Idea 8) — leverages existing data immediately
 6. **Quick Actions Dashboard** (Bonus) — improves daily UX
 7. **Path Analytics** (Idea 5) — needs session volume, start collecting data now

 ### Later (larger effort, needs foundation)
+
 8. **Push Steps to Active Sessions** (Idea 4) — needs notification system
 9. **Tree Health Scores** (Idea 9) — needs session volume + analytics infrastructure
 10. **Multi-Tree Sessions** (Idea 7) — complex UX, large refactor

 ### Long-term vision
+
 11. **AI Tree Intelligence** (Idea 10) — phased rollout, ultimate differentiator

 ---