UX Reference: LLM Chat Assistant for Project Operations

Feature Branch: 021-llm-project-assistant Created: 2026-02-23
Status: Draft

1. User Persona & Context

Who is the user?: Platform operator, dashboard engineer, or admin managing Superset operations.
What is their goal?: Execute routine and critical project operations quickly via natural language with safe controls.
Context: User is already in ss-tools web interface and wants to avoid jumping between Git, migration, backup, and task pages.

2. The "Happy Path" Narrative

The user opens assistant chat from the main interface and enters a natural command to run an operation. Assistant immediately recognizes intent, validates permissions, and either executes directly or asks for confirmation if operation is risky. For long-running actions, assistant responds instantly with task_id and where to track progress. User can ask follow-up status questions in the same chat and receives concise operational answers.

3. Interface Mockups

UI Layout & Flow (if applicable)

Screen/Component: Assistant Chat Panel

Layout:
- Right-side drawer or modal panel with message history.
- Input area at bottom with send action and command examples shortcut.
- Message cards with role (User/Assistant), timestamp, state badge.
Key Elements:
- Chat Input: Supports free-text commands in RU/EN.
- State Badge: started, success, failed, needs_confirmation, denied.
- Confirmation Card: Explicit confirm/cancel buttons for risky actions.
- Task Link Chip: task_id chip with quick open in Task Drawer.
- Suggestions Block: "Try command" examples for supported domains.
States:
- Default: Empty or recent history shown, examples visible.
- Parsing: Inline "Analyzing command..." loading state.
- Needs Confirmation: Warning card with operation summary and target environment.
- Started: Immediate message with task_id and tracking hint.
- Error: Error card with reason and recovery suggestion.

Interaction Examples

User: запусти миграцию с dev на prod для дашборда 42
Assistant: Операция рискованная (target=production). Подтвердите запуск.
[Confirm] [Cancel]

User: confirm
Assistant: Миграция запущена. task_id=task-8f13. Прогресс: Task Drawer / Reports.

4. The "Error" Experience

Philosophy: Never silently fail. Show what happened, why, and what to do next.

Scenario A: Ambiguous Command

User Action: "сделай задачу для дашборда 42"
System Response:
- Assistant does not execute immediately.
- Returns clarification question with options (Git branch / migration / backup / analysis).
Recovery: User selects one option or reformulates command.

Scenario B: Permission Denied

User Action: Non-admin requests production deploy.
System Response:
- Assistant returns denied state with minimal permission reason.
- No task is created.
Recovery: User requests access or uses allowed operation.

Scenario C: Confirmation Timeout

System Response: "Confirmation expired. Operation was not executed."
Recovery: User reissues command.

Scenario D: Downstream Failure After Start

System Response: Assistant returns task_id and indicates task moved to failed state with short error summary.
Recovery: Open task logs/reports using provided link/action.

5. Tone & Voice

Style: Operational, concise, explicit.
Terminology: Use "command", "task", "confirmation", "status", "task_id"; avoid vague wording.

3.6 KiB Raw Blame History Unescape Escape