resolutionflow/docs/archive/04-FEATURE-SPECIFICATIONS.md

Feature Specifications

Core Features (MVP)

1. Tree Navigation Interface

Description: The primary interface where engineers work through troubleshooting decision trees in real-time.

User Flow:

1. User selects a tree from library
2. Optionally enters ticket number and client name
3. System displays first question/decision point
4. User makes selection and optionally adds notes
5. System progresses to next appropriate node
6. Process repeats until resolution or manual exit
7. User exports completed session

UI Components:

• Question Display: Large, clear text showing current decision point
• Decision Options:
  • Yes/No buttons (for binary decisions)
  • Multiple choice buttons (for multi-option decisions)
  • Action confirmation button (for action steps)
• Notes Field: Expandable text area for adding context
• Navigation:
  • Back button (undo last decision)
  • Progress indicator (X of Y steps, or visual tree progress)
  • Exit/Save button
• Help Panel: Collapsible sidebar with:
  • Help text for current node
  • Suggested commands/scripts
  • Links to documentation
  • Option to attach files

Technical Requirements:

• State management for current position in tree
• Undo functionality (maintain decision history)
• Auto-save progress every 30 seconds
• Handle browser refresh gracefully
• Support keyboard navigation (arrow keys, enter, esc)

Edge Cases:

• Network disconnection during session → Save locally, sync when reconnected
• User closes browser mid-session → Recover session on return
• Tree structure changes while session active → Use snapshot of tree
• Circular tree logic → Detect and prevent infinite loops

---

2. Documentation Links Integration

Description: Contextual documentation and resource links embedded at each decision node.

Features:

• Multiple Link Types:
  • Vendor documentation (Microsoft Learn, Citrix docs, etc.)
  • Internal KB articles (wiki/Confluence links)
  • Video tutorials (YouTube, internal training)
  • Related troubleshooting trees
• Display:
  • Show as expandable "Resources" section
  • Icon indicating link type (📄 doc, 🎥 video, 🌲 tree)
  • Open in new tab/window
  • Preview tooltip on hover
• Management:
  • Add/edit links in tree editor
  • Track link clicks (analytics)
  • Validate URLs (check for 404s)
  • Support internal and external links

Data Structure:

"documentation_links": [
  {
    "title": "Citrix VDA Communication Requirements",
    "url": "https://docs.citrix.com/...",
    "type": "vendor_docs",
    "description": "Official Citrix documentation on VDA-DDC communication"
  },
  {
    "title": "Internal: VDA Troubleshooting Guide",
    "url": "https://wiki.company.com/...",
    "type": "internal_kb"
  },
  {
    "title": "Video: VDA Registration Deep Dive",
    "url": "https://youtube.com/...",
    "type": "video",
    "duration": "8:32"
  }
]

UI Considerations:

• Don't clutter main interface - use expandable sections
• Allow quick copy of URLs
• Indicate when link was last verified
• Option to suggest new links (crowdsourcing)

---

3. Export Functionality

Description: Generate professional, formatted documentation from troubleshooting sessions.

Export Formats:

Plain Text

Ticket #12345 - Citrix VDA Not Registering
Troubleshooting Path: Citrix VDA Diagnostics
Technician: Michael Chihlas
Date: 2026-01-22 14:30
Client: City of Warner Robins

STEPS PERFORMED:
1. Network Connectivity Check
   - Can ping VDA from Delivery Controller: YES
   - Note: Response time 2ms, no packet loss

2. Service Status Verification
   - Citrix Virtual Desktop Agent service status: STOPPED
   
3. Service Recovery
   - Started Citrix VDA service
   - Note: Service had stopped due to NetLogon dependency failure

4. Registration Verification
   - VDA showing as registered in Studio: YES
   - Note: User able to launch session successfully
   
RESOLUTION:
Started Citrix VDA service after resolving NetLogon dependency issue. 
VDA successfully registered with Delivery Controller.

ATTACHED FILES:
- eventvwr_screenshot.png
- service_status_before.txt

TIME SPENT: 15 minutes

Markdown

# Ticket #12345 - Citrix VDA Not Registering

**Troubleshooting Path:** Citrix VDA Diagnostics  
**Technician:** Michael Chihlas  
**Date:** 2026-01-22 14:30  
**Client:** City of Warner Robins

## Steps Performed

### 1. Network Connectivity Check
✓ Can ping VDA from Delivery Controller: **YES**

> Response time 2ms, no packet loss

### 2. Service Status Verification
✗ Citrix Virtual Desktop Agent service status: **STOPPED**

### 3. Service Recovery
✓ Started Citrix VDA service

> Service had stopped due to NetLogon dependency failure

### 4. Registration Verification
✓ VDA showing as registered in Studio: **YES**

> User able to launch session successfully

## Resolution
Started Citrix VDA service after resolving NetLogon dependency issue. VDA successfully registered with Delivery Controller.

## Attached Files
- [eventvwr_screenshot.png](link)
- [service_status_before.txt](link)

---
**Time Spent:** 15 minutes

HTML

• Styled version of markdown
• Embeds images inline
• Collapsible sections
• Print-friendly CSS
• Copy button for easy paste into web forms

Customization Options:

• Include/exclude sections (steps, resolution, attachments, time)
• Custom header/footer
• Branding/logo
• Date/time format
• Technician name format
• Template selection (different formats for different ticket systems)

Technical Implementation:

• Backend template engine (Jinja2)
• Frontend preview before export
• Copy to clipboard functionality
• Download as file
• Send via email (Phase 3)

---

4. Tree Editor

Description: Visual interface for creating and editing decision trees.

Editing Modes:

• Visual Mode: Drag-and-drop node editor (like flowchart)
• Form Mode: Fill-in-the-blanks forms for each node
• JSON Mode: Direct JSON editing (for advanced users)

Node Types:

1. Decision Node: Question with multiple possible answers
2. Action Node: Instruction to perform a task
3. Resolution Node: Terminal node indicating issue resolved
4. Branch Node: Link to another tree or manual escalation

Node Configuration:

• Common Fields:

  • Node ID (auto-generated, editable)
  • Node type
  • Title/Question text
  • Help text (optional)
  • Documentation links (optional)
  • Allow notes (toggle)
  • Allow attachments (toggle)
  • Allow custom branch (toggle)

• Decision Node Specific:

  • Decision type (yes/no, multiple choice, numeric range)
  • Options and next node for each

• Action Node Specific:

  • Action instructions
  • Commands/scripts to run
  • Expected outcome
  • Automation available (toggle)
  • Automation configuration
  • Next node

• Resolution Node Specific:

  • Resolution summary template
  • Success criteria
  • Follow-up recommendations

Tree Metadata:

• Tree name
• Description
• Category/tags
• Estimated time to complete
• Difficulty level
• Author
• Version
• Creation/update dates

Validation:

• No orphaned nodes (every node reachable from start)
• No circular references (detect loops)
• Every decision has valid next nodes
• Terminal nodes exist
• Required fields filled

UI Features:

• Auto-save draft
• Preview mode (test the tree)
• Duplicate tree (create variations)
• Import/export tree JSON
• Publish (make active) vs. Draft
• Version history (Phase 3)

---

5.5 User Preferences (MVP)

Description: Basic user settings to personalize the application experience, stored locally for MVP with optional server sync in later phases.

MVP Settings:

Setting	Options	Default	Storage
Theme	Light / Dark / System	System	localStorage
Default Export Format	Markdown / Text / HTML	Markdown	localStorage

UI Components:

• Settings Access: Gear icon in user menu dropdown
• Settings Modal: Simple modal with toggle/dropdown for each setting
• Theme Toggle: Can also be quick-access icon in header

Theme Implementation:

Light Mode:
- Background: White/light gray
- Text: Dark gray/black
- Accents: Brand colors

Dark Mode:
- Background: Dark gray (#1a1a2e or similar)
- Text: Light gray/white
- Accents: Adjusted brand colors for dark backgrounds

System:
- Follows OS preference via prefers-color-scheme media query
- Updates automatically if OS setting changes

Technical Requirements:

• Persist to localStorage immediately on change
• Apply theme without page reload (CSS variables)
• Respect system preference on first visit
• Export format preference used as default in export dialog

Future Enhancements (Phase 2+):

• Sync preferences to user account (database)
• More settings: auto-save interval, keyboard shortcuts, notification preferences
• Per-tree preferences (remember last used export format per tree)

---

5. Attachment Support

Description: Upload and attach files (screenshots, logs, command outputs) to specific decision nodes during troubleshooting.

Supported File Types:

• Images: PNG, JPG, GIF, WebP
• Documents: TXT, LOG, CSV, JSON, XML
• Screenshots: Direct paste from clipboard (Ctrl+V)
• Archives: ZIP (for bundled logs)

File Size Limits:

• Individual file: 10 MB
• Per session: 50 MB
• Total per user: 500 MB (soft limit, alert before reaching)

Upload Methods:

1. File Picker: Click to browse and select
2. Drag & Drop: Drag files onto upload area
3. Paste: Ctrl+V to paste screenshot from clipboard
4. Command Output: Copy-paste terminal output, save as .txt

Features:

• Preview: Thumbnail for images, icon for others
• Annotation: Add caption/description to each file
• Organize: Files associated with specific decision node
• Download: Download individual files or all as ZIP
• Delete: Remove unwanted attachments
• Reference in Notes: Auto-reference in export ("See attached screenshot")

Storage:

• S3-compatible object storage
• Organized by session_id/node_id/filename
• Pre-signed URLs for secure access
• Automatic cleanup of old sessions (retention policy)

Export Integration:

• List attached files in export
• Include inline images in HTML/PDF exports
• Provide download links in text/markdown exports
• Option to bundle as ZIP with export

Technical Considerations:

• Virus scanning (Phase 3)
• Content-Type validation
• Generate thumbnails for images
• Compress images to reduce storage
• CDN for faster delivery

---

Advanced Features (Phase 3+)

6. Automation Integration

Description: Execute PowerShell scripts or commands directly from action nodes, capturing output and integrating into troubleshooting flow.

Architecture:

Frontend → Backend API → Automation Worker → PowerShell/Script → Return Output

Safety Mechanisms:

• Execution Sandbox: Isolated environment, limited permissions
• Timeout: Max execution time (5 minutes default)
• Resource Limits: CPU, memory, network constraints
• Approval Required: Sensitive scripts need admin approval
• Audit Log: Every execution logged with user, timestamp, parameters, output

Script Types:

1. Read-Only: Get information (Get-Service, Test-Connection)
2. Safe Actions: Restart services, clear caches
3. Configuration Changes: Modify settings (require extra confirmation)

User Experience:

• Option at Action Node: "Run Automation" vs. "Manual" buttons
• Parameter Input: If script needs parameters (hostname, username)
• Progress Indicator: Show script is running
• Output Display: Show script output in real-time or after completion
• Error Handling: Clear error messages, suggest manual steps
• Capture Output: Automatically save output as attachment

Script Management:

• Script Library: Centralized repository of approved scripts
• Versioning: Track script versions
• Testing: Test mode before production use
• Permissions: Control who can run which scripts
• Documentation: Each script has description, parameters, example usage

Integration with ChihlasChecker:

• Import existing PowerShell scripts
• Wrap scripts with parameter handling
• Standardize output format
• Error code mapping

Example Script Configuration:

{
  "script_id": "restart-citrix-vda-service",
  "name": "Restart Citrix VDA Service",
  "description": "Restarts the Citrix Virtual Desktop Agent service and its dependencies",
  "type": "powershell",
  "requires_elevation": true,
  "timeout_seconds": 300,
  "parameters": [
    {
      "name": "ComputerName",
      "type": "string",
      "required": true,
      "description": "VDA hostname or IP address",
      "validation": "^[a-zA-Z0-9.-]+$"
    }
  ],
  "script": "path/to/script.ps1",
  "risk_level": "medium",
  "approval_required": false
}

---

7. Offline Mode

Description: Continue using the application without internet connectivity, with automatic sync when connection restored.

Offline Capabilities:

• Navigate cached trees
• Add notes and make decisions
• Queue file attachments (upload when online)
• View past sessions (cached)

What Requires Online:

• Creating new trees
• Sharing with team
• Accessing uncached trees
• Running automation
• Real-time collaboration

Technical Implementation:

• Service Worker: Intercept network requests, serve from cache
• IndexedDB: Store trees, sessions, user data locally
• Sync Queue: Track changes made offline, sync when online
• Conflict Resolution: Handle conflicts if tree was updated while offline

User Experience:

• Status Indicator: Clear online/offline badge
• Sync Status: "Syncing..." indicator when uploading changes
• Cache Management: Settings to control what's cached
• Manual Sync: Button to force sync attempt

Data Synchronization:

1. User goes offline mid-session
2. Continues making decisions, adding notes (stored locally)
3. Attempts to attach file (queued for upload)
4. User regains connection
5. System detects online status
6. Uploads queued attachments
7. Syncs session data to server
8. Resolves any conflicts
9. Updates local cache with server changes

Conflict Resolution:

• Last-write-wins for session data (sessions are user-specific)
• Alert user if tree structure changed significantly
• Option to review changes before syncing

---

8. Client Context System

Description: Store and auto-populate client-specific information to speed up troubleshooting and reduce repetitive data entry.

Stored Context:

• Infrastructure Details:
  • Server names (DC names, Citrix DDC, file servers)
  • IP addresses and subnets
  • Domain names
  • VPN configurations
• Common Issues:
  • Known recurring problems
  • Specific quirks of client environment
• Contact Information:
  • Primary contacts
  • Escalation paths
• Documentation Links:
  • Client-specific network diagrams
  • Password vault links
  • Configuration management links

Features:

• Client Selection: Dropdown or search to select client at session start
• Auto-Population: When client selected, pre-fill known values in tree
• Context Cards: Display relevant client info in sidebar during troubleshooting
• Quick Edit: Update client context without leaving session
• Privacy: Sensitive data encrypted, access controlled

Example Usage:

1. User starts session for "City of Warner Robins"
2. System loads Warner Robins context
3. When tree asks "What is the primary domain controller?", it pre-fills "WR-DC01"
4. User can accept or override
5. Saves time and reduces errors

Data Structure:

{
  "client_id": "warner-robins-city",
  "client_name": "City of Warner Robins",
  "context": {
    "domain_controllers": ["WR-DC01.wrga.local", "WR-DC02.wrga.local"],
    "citrix_ddc": ["WR-CTX01.wrga.local"],
    "file_servers": ["WR-FS01.wrga.local"],
    "subnets": ["10.20.0.0/16"],
    "vpn_gateway": "vpn.wrga.gov",
    "primary_contact": "John Smith - IT Director",
    "escalation": "jane.doe@wrga.gov",
    "notes": "Always check VPN tunnel to courthouse first - frequently drops"
  }
}

---

9. "Send to Engineer" Feature

Description: Generate a simplified, read-only view or checklist from a decision tree that can be shared with onsite engineers or junior staff.

Use Cases:

• Remote engineer creates troubleshooting plan
• Shares link with onsite tech
• Onsite tech follows steps, reports results
• Remote engineer updates plan if needed

Features:

• Simplified View: Streamlined UI, just the steps
• Checklist Mode: Check off completed steps
• Print-Friendly: Clean layout for printing
• Share Link: Generate unique URL, no login required (optional)
• QR Code: For easy mobile access
• Expiration: Links expire after X hours/days
• Password Protection: Optional password for sensitive clients

Generated Content:

Warner Robins - VDA Registration Issue
Generated by: Michael Chihlas
Date: 2026-01-22

[ ] Step 1: Check network connectivity
    From DDC, run: ping WR-VDA05
    Expected: Replies with <5ms latency
    
[ ] Step 2: Verify VDA service status
    Run: Get-Service BrokerAgent
    Expected: Status = Running
    
[ ] Step 3: If service stopped, start it
    Run: Start-Service BrokerAgent
    Wait 30 seconds
    
[ ] Step 4: Verify registration
    Open Citrix Studio
    Check Machine Catalogs
    Expected: WR-VDA05 shows "Registered"

Notes/Results:
[Space for onsite tech to write notes]

Contact remote engineer if issues: michael@msp.com

Technical Implementation:

• Generate static HTML page from tree
• Store in temporary location (S3)
• Track access (analytics)
• Auto-delete after expiration
• Optional: Collect results back (if onsite tech submits form)

---

10. Personal Tree Branching (Phase 2.5)

Description: Allow users to insert custom steps during an active troubleshooting session without modifying the original tree, then optionally save their modified version as a personal tree.

User Flow:

1. User navigates an official tree
2. At any decision point, user clicks "+ Add Custom Step"
3. User creates step manually OR selects from Step Library
4. Custom step is inserted into their session only (original tree unchanged)
5. Session continues with custom step included
6. Export includes all custom steps with clear marking
7. After session completion, user is prompted to save as personal tree (optional)

UI Components:

• Add Custom Step Button: Appears at each decision node
• Step Creation Modal:
  • Tab 1: "Type My Own" - free-form step creation
  • Tab 2: "Browse Library" - searchable step repository
• Custom Step Indicator: Visual badge showing step is user-added (not from original tree)
• Save as Tree Prompt: Post-session dialog offering to save modifications

Step Types:

1. Decision: Yes/No or multiple choice question
2. Action: Task to perform with optional commands/scripts
3. Resolution: Terminal node indicating issue resolved

Technical Requirements:

• Custom steps stored separately from original tree structure
• Session tracks insertion points (after which node ID)
• Export template renders custom steps with visual distinction
• Tree fork creates deep copy with user as owner
• Forked trees maintain reference to original (for analytics/updates)

Edge Cases:

• Original tree updated after fork → Notify user, offer to view changes
• User deletes custom step mid-session → Remove from session, continue normally
• Circular reference from custom step → Validate and prevent before insertion
• Custom step at terminal node → Allow, becomes new branch point

---

11. Step Library (Phase 2.5)

Description: A repository of reusable troubleshooting steps that users can pull into any session, organized by visibility, categories, tags, and user ratings.

Library Hierarchy:

• My Steps: Private to individual user
• Team Steps: Visible to all team members
• Admin Curated: Organization-wide, managed by administrators
• Community/Public: User-contributed, rated by users, visible to all

Features:

• Search & Filter:
  • Full-text search across titles, descriptions, commands
  • Filter by step type (decision, action, resolution)
  • Filter by category (admin-managed)
  • Filter by tags (user-defined)
  • Filter by visibility level
  • Filter by minimum rating (e.g., 4+ stars)
  • Sort by: recent, popular, highest rated, most used
• Step Preview:
  • View full step details before inserting
  • See usage count and rating breakdown
  • View author, creation date, and last updated
  • See category and tags
• Step Management:
  • Create new steps (saved to "My Steps" by default)
  • Assign category and add tags during creation
  • Edit and delete own steps
  • Promote to Team visibility (if permitted)
  • Submit to Community (requires admin approval)

Categories (Admin-Managed)

Categories provide structured organization for steps. Admins define and manage categories.

Default Categories:

Category	Description
Citrix / VDI	Virtual desktop, XenApp, XenDesktop, VDA issues
Active Directory	AD, LDAP, Group Policy, authentication
Microsoft 365	Exchange Online, Teams, SharePoint, OneDrive
Networking	DNS, DHCP, VPN, firewall, connectivity
File Services	File shares, permissions, DFS, storage
Printing	Print servers, drivers, spooler issues
Backup & Recovery	Backup software, disaster recovery, restore
Security	Antivirus, permissions, security incidents
Hardware	Servers, workstations, peripherals
Other	Miscellaneous steps

Tags (User-Defined)

Tags provide flexible, user-driven organization:

• Created by any user when adding/editing a step
• Lowercase, alphanumeric with hyphens (e.g., vda-registration, powershell)
• Auto-suggest existing tags while typing
• Popular tags shown as quick-filters
• Recommended: 3-5 tags per step

User Ratings & Reviews

Public and team steps can be rated by users to surface the most helpful content.

Rating System:

• Star Rating: 1-5 stars (required when rating)
• Helpful Vote: Quick "Was this helpful?" Yes/No after using a step
• Written Review: Optional text feedback (max 500 chars)
• One rating per user per step (can update later)

Rating Rules:

• Only users who have actually used the step can rate it ("Verified Use" badge)
• Step author cannot rate their own step
• Ratings update the step's average in real-time
• Steps with <5 ratings show "Not enough ratings" instead of average
• Admin can remove abusive reviews

Admin Controls:

• Approve/reject community step submissions
• Curate "Admin Curated" collection
• Manage categories (create, rename, archive)
• Remove inappropriate content/reviews
• Set default visibility for new steps

---

12. Personal Tree Management (Phase 2.5)

Description: Users can save, organize, and share their customized tree versions.

Features:

• My Trees Dashboard:
  • List of user's forked/custom trees
  • Reference to original tree (if forked)
  • Last used date and usage count
  • Quick actions: start session, edit, share, delete
• Tree Forking:
  • Fork from any tree user has access to
  • Fork from another user's shared tree (fork of fork)
  • Maintain lineage tracking for analytics
• Sharing Options:
  • 🔒 Private - Only creator can access
  • 🔗 Link sharing - Anyone with link, no login required
  • 👥 Team - All team members can use
  • 🌍 Public - Submitted to community library
• Version Awareness:
  • Notification when original tree is updated
  • Option to view changes (basic diff)
  • Manual merge in future phase

Forking Behavior:

• Deep copy of entire tree structure
• User becomes owner of the copy
• Original tree reference preserved
• Changes to original don't affect fork (until user chooses to merge)
• Fork count tracked on original tree (analytics)

Sharing Permissions:

• Owner can change visibility at any time
• "Allow forking" toggle controls whether others can fork
• "Show author" toggle controls name visibility
• Revoking link sharing invalidates existing links

---

Feature Priority Matrix

Feature	MVP	Phase 2	Phase 2.5	Phase 3	Phase 4
Tree Navigation	✓
Basic Export	✓
User Auth	✓
User Preferences	✓
5 Starter Trees	✓
Team Management		✓
Tree Editor		✓
Mobile Responsive		✓
Basic Custom Branches		✓
Step Library			✓
Categories & Tags			✓
Ratings & Reviews			✓
Personal Tree Branching			✓
Tree Forking & Sharing			✓
File Attachments				✓
Offline Mode				✓
Advanced Export (PDF)				✓
Client Context				✓
Send to Engineer				✓
Analytics Dashboard				✓
Documentation Links	✓	Enhanced
API					✓
Automation Integration					✓
PSA Integrations					✓
Marketplace					Later

---

User Stories

Michael (Senior Engineer)

• "I need to quickly document my troubleshooting steps for a ticket"
• "I want to reuse proven troubleshooting paths instead of reinventing"
• "I need to attach screenshots to show what I found"
• "I want to create custom trees for our specific environment"
• "I need this to work when I'm on-site with poor connectivity"

Junior Engineer

• "I need guidance on how to troubleshoot issues I'm not familiar with"
• "I want to know what commands to run and what results to expect"
• "I need links to documentation when I get stuck"
• "I want to learn from what senior engineers do"

Onsite Technician

• "I need simple, step-by-step instructions I can follow"
• "I want a checklist I can print and bring to the server room"
• "I need to report back results to the remote engineer"

MSP Manager

• "I need to see what my team is working on"
• "I want to ensure we're following consistent procedures"
• "I need metrics on troubleshooting time and success rates"
• "I want to identify training gaps based on common issues"

Phase 2.5 User Story Additions

Michael (Senior Engineer):

• "I want to add a client-specific step without changing the official tree"
• "I want to save my modified tree so I can reuse it for this client"
• "I want to share a troubleshooting approach with a colleague via link"
• "I want to build a library of steps I commonly use across different trees"
• "I want to rate steps that helped me so others can find them"

Junior Engineer:

• "I want to see what custom steps senior engineers have created"
• "I want to use proven steps from the team library instead of creating my own"
• "I want to fork a senior engineer's tree and learn from their approach"
• "I want to filter steps by rating to find the best ones"
• "I want to see reviews from others who used a step"

MSP Manager:

• "I want to curate a set of approved steps for my team"
• "I want to see which custom steps are being used most"
• "I want to approve steps before they're shared publicly"
• "I want to manage categories to keep the step library organized"
• "I want to moderate reviews for inappropriate content"