# 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

```text
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.