mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
* [50e80c55] docs(design): create Prompter interaction design directory and main spec * [50e80c55] docs(design): add confirmation interstitial spec with un-bypassable guardrails * [50e80c55] docs(design): add model-selector drawer UX with Recommended default and complexity mapping * [50e80c55] docs(design): add naming and navigation spec with sidebar placement and Task Assistant recommendation --------- Co-authored-by: UX/UI Developer 1 <ux-dev-1@agents.roboco.dev>
This commit is contained in:
Renzo F
co-authored by
UX/UI Developer 1
UX/UI Developer 1
parent
199169ef0e
commit
d5cbbf49ee
@@ -0,0 +1,182 @@
|
||||
# Prompter — Interaction Specification
|
||||
|
||||
## Overview
|
||||
|
||||
The Prompter is a first-class Panel page that lets users author tasks via conversational LLM assistance rather than hand-writing specs. The journey is intentionally linear and un-bypassable:
|
||||
|
||||
```
|
||||
Chat → Draft → Review → Confirm → Launch → Success
|
||||
```
|
||||
|
||||
Each transition is explicit. There is no hidden auto-launch; the human is always the final gate before a task enters the system.
|
||||
|
||||
---
|
||||
|
||||
## Screen States
|
||||
|
||||
### 1. Chat Screen (Default)
|
||||
|
||||
**Purpose**: The user describes what they need in natural language. The LLM responds with clarifying questions and, when enough context is gathered, offers to generate a draft.
|
||||
|
||||
**Layout** (mapped to existing components):
|
||||
- **Container**: Full page inside the dashboard layout (`(dashboard)/layout.tsx`)
|
||||
- **Header row**:
|
||||
- Page title (H1): see [`04-naming-and-navigation.md`](04-naming-and-navigation.md)
|
||||
- Subtitle: "Describe what you need. The assistant will ask questions and draft a task for your team."
|
||||
- **Chat area** (`Card` + custom flex column):
|
||||
- **Message list** (`ScrollArea`): user messages right-aligned, assistant messages left-aligned.
|
||||
- **Message bubbles**: `Card` with `py-3 px-4` and subtle background differentiation:
|
||||
- User: `bg-primary/10`
|
||||
- Assistant: `bg-muted`
|
||||
- **Typing indicator**: `Skeleton` pulse (3 lines) when assistant is generating.
|
||||
- **Composer bar** (fixed to bottom of chat area):
|
||||
- `Textarea` (auto-resize, max 4 lines) with placeholder: "Describe the task you want to create..."
|
||||
- `Button` (primary, icon `Send`) labeled "Send"
|
||||
- Keyboard: `Enter` sends; `Shift+Enter` adds newline.
|
||||
- **Empty state** (first visit):
|
||||
- Centered `Card` with illustration placeholder + suggested prompts:
|
||||
- "Add a dark-mode toggle to the panel"
|
||||
- "Write a design spec for a confirmation flow"
|
||||
- "Create a backend task to add OAuth2 login"
|
||||
|
||||
**Component references**:
|
||||
- `panel/src/components/ui/card.tsx` — message bubbles
|
||||
- `panel/src/components/ui/textarea.tsx` — composer input
|
||||
- `panel/src/components/ui/button.tsx` — send button
|
||||
- `panel/src/components/ui/scroll-area.tsx` — scrollable message list
|
||||
- `panel/src/components/ui/skeleton.tsx` — typing indicator
|
||||
|
||||
**Accessibility**:
|
||||
- `aria-live="polite"` on the message list so screen readers announce new assistant messages.
|
||||
- Composer `Textarea` has `aria-label="Task description"`.
|
||||
|
||||
**Error states**:
|
||||
- LLM error: assistant message styled as `Alert` variant `destructive` with text: "Something went wrong. Try rephrasing or try again later."
|
||||
- Network error: toast via `sonner` (already in panel globals).
|
||||
|
||||
---
|
||||
|
||||
### 2. Draft Preview (Inline Transition)
|
||||
|
||||
**Purpose**: Once the LLM has enough context, it generates a structured task draft. The draft is presented inline in the chat as a special "proposal" message, not a separate page. This preserves conversational context.
|
||||
|
||||
**Trigger**: Assistant message ends with: *"I can draft a task based on what we discussed. Would you like to review it?"* + two quick actions.
|
||||
|
||||
**Layout**:
|
||||
- **Proposal card** (full-width, `Card` with `border-primary`):
|
||||
- Header: `CardHeader` with `CardTitle` "Draft Task" and `Badge` showing suggested team.
|
||||
- Body (`CardContent`):
|
||||
- **Title** (bold, `text-lg`)
|
||||
- **Description** (truncated to 4 lines with fade-out; `Button` "Expand" to show full text in a `Dialog`)
|
||||
- **Acceptance criteria** (`ScrollArea`, max height 160px):
|
||||
- Numbered list using `Badge` variant `outline` for each item number.
|
||||
- **Metadata row** (flex, gap-4, `text-sm text-muted-foreground`):
|
||||
- Team: `Badge`
|
||||
- Complexity: `Badge` variant `secondary`
|
||||
- Nature: `Badge` variant `secondary`
|
||||
- Footer (`CardFooter`, justify-between):
|
||||
- `Button` variant `outline`: "Keep Chatting" (returns to free chat)
|
||||
- `Button` (primary): "Review & Confirm" (advances to confirmation interstitial)
|
||||
|
||||
**Component references**:
|
||||
- `panel/src/components/ui/card.tsx` — proposal card
|
||||
- `panel/src/components/ui/badge.tsx` — team, complexity, nature labels
|
||||
- `panel/src/components/ui/dialog.tsx` — expand description
|
||||
- `panel/src/components/ui/scroll-area.tsx` — criteria list
|
||||
|
||||
**Accessibility**:
|
||||
- Proposal card is focusable (`tabIndex={0}`) and announces via `aria-live`.
|
||||
- "Review & Confirm" button has `aria-describedby` pointing to a hidden span summarizing the draft title.
|
||||
|
||||
---
|
||||
|
||||
### 3. Confirmation Interstitial (Modal)
|
||||
|
||||
**Purpose**: The un-bypassable human gate. The user sees the full draft, can edit fields inline, and must explicitly confirm before the task is created.
|
||||
|
||||
**Behavior**: Opens as a **full-size Dialog** (`DialogContent` with `sm:max-w-3xl lg:max-w-4xl max-h-[90vh]`) so the user cannot miss it. This is not a sidebar or inline form; it interrupts the flow by design.
|
||||
|
||||
**Detailed spec**: see [`02-confirmation-interstitial.md`](02-confirmation-interstitial.md).
|
||||
|
||||
---
|
||||
|
||||
### 4. Launch / Success
|
||||
|
||||
**Purpose**: Provide clear feedback that the task has entered the system and give the user a next step.
|
||||
|
||||
**Layout** (inline in chat, replacing the proposal card):
|
||||
- **Success card** (`Card` with `border-green-600` or `border-success` token if available):
|
||||
- Header: `CardHeader` with `CardTitle` "Task launched" + `Badge` "Pending"
|
||||
- Body: one-sentence summary: "Your task '*{title}*' has been created and routed to the **{team}** cell."
|
||||
- Footer (`CardFooter`, gap-2):
|
||||
- `Button` variant `ghost` + `Link` to `/tasks/{taskId}`: "View Task →"
|
||||
- `Button` variant `outline`: "Start Another" (resets chat to empty state)
|
||||
|
||||
**Component references**:
|
||||
- `panel/src/components/ui/card.tsx`
|
||||
- `panel/src/components/ui/badge.tsx`
|
||||
- `panel/src/components/ui/button.tsx`
|
||||
|
||||
---
|
||||
|
||||
## State Machine
|
||||
|
||||
```text
|
||||
[Empty] --user types--> [Chatting]
|
||||
|
||||
[Chatting] --assistant offers draft--> [DraftPreview]
|
||||
[Chatting] --user keeps typing--> [Chatting]
|
||||
[Chatting] --LLM error--> [Chatting] (error bubble appended)
|
||||
|
||||
[DraftPreview] --"Keep Chatting"--> [Chatting]
|
||||
[DraftPreview] --"Review & Confirm"--> [ReviewModal]
|
||||
|
||||
[ReviewModal] --"Cancel"--> [DraftPreview] (modal closes, chat scrolls to proposal)
|
||||
[ReviewModal] --user edits fields--> [ReviewModal] (dirty state)
|
||||
[ReviewModal] --"Confirm & Launch"--> [Launching] (button loading)
|
||||
|
||||
[Launching] --API success--> [Success]
|
||||
[Launching] --API error--> [ReviewModal] (error banner + button enabled)
|
||||
|
||||
[Success] --"Start Another"--> [Empty]
|
||||
[Success] --"View Task"--> (navigate away)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Loading Patterns
|
||||
|
||||
| State | Visual |
|
||||
|-------|--------|
|
||||
| Assistant thinking | `Skeleton` 3-line pulse inside assistant bubble |
|
||||
| Draft generating | `Skeleton` card (title + 4 lines + criteria placeholder) |
|
||||
| Launching | Primary button shows spinner + "Launching..." text |
|
||||
| Navigating to task | Page transition handled by Next.js; no extra UX needed |
|
||||
|
||||
---
|
||||
|
||||
## Error Patterns
|
||||
|
||||
| Scenario | UI | Copy |
|
||||
|----------|-----|------|
|
||||
| LLM stream fails mid-chat | Toast + inline retry button | " assistant had a hiccup. [Retry]" |
|
||||
| Draft generation fails | Inline alert inside chat | "Couldn’t draft a task right now. Keep chatting or try again." |
|
||||
| Confirm & Launch API fails | Banner inside review modal | "We couldn’t create the task. Check your connection and try again." |
|
||||
| Validation error (e.g. title too short) | Field-level error text | Same rules as `CreateTaskDialog` |
|
||||
|
||||
---
|
||||
|
||||
## Responsive Behavior
|
||||
|
||||
- **Desktop (>= 1024px)**: Chat and composer are centered in a max-width 880px column inside the dashboard layout.
|
||||
- **Tablet (768–1023px)**: Same, max-width 720px.
|
||||
- **Mobile (< 768px)**: Composer bar becomes sticky at bottom of viewport; chat scrolls above it. Review modal becomes bottom sheet (`Sheet` component) instead of center Dialog if needed, but since this is a dashboard application primarily used on desktop, Dialog is acceptable for MVP.
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope (Phase 2)
|
||||
|
||||
- Conversation history / "My Prompts" list
|
||||
- Persistent drafts across sessions
|
||||
- Advanced model comparison side-by-side
|
||||
- Rich media uploads in chat
|
||||
@@ -0,0 +1,206 @@
|
||||
# Prompter — Confirmation Interstitial Specification
|
||||
|
||||
## Principle
|
||||
|
||||
> **You decide what gets sent to the team.**
|
||||
|
||||
The confirmation interstitial is the un-bypassable human gate before any Prompter-generated task enters the RoboCo system. It must be impossible to skip by accident, by keyboard shortcut, or by API manipulation. The user must read, review, and explicitly confirm.
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Review & Confirm Dialog
|
||||
|
||||
### Component
|
||||
|
||||
`Dialog` from `panel/src/components/ui/dialog.tsx` — **not** `AlertDialog`. We need the full content flexibility of `Dialog` (close button, scrollable body, custom footer) rather than the simplified action/cancel binary of `AlertDialog`.
|
||||
|
||||
**Size**: `DialogContent` with classes `sm:max-w-3xl lg:max-w-4xl max-h-[90vh] overflow-y-auto`.
|
||||
|
||||
This is the same large-dialog pattern used by `CreateTaskDialog` in `panel/src/components/tasks/create-task-dialog.tsx`.
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Review & Confirm Task [×] │
|
||||
│ You decide what gets sent to the team. │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Title * │
|
||||
│ [________________________________________] │
|
||||
│ │
|
||||
│ Description * │
|
||||
│ [ ] │
|
||||
│ [ Markdown editor with preview toggle ] │
|
||||
│ [ ] │
|
||||
│ │
|
||||
│ Acceptance Criteria * │
|
||||
│ ┌────────────────────────────────────────┐ │
|
||||
│ │ 1. [Criterion text………] [×] │ │
|
||||
│ │ 2. [Criterion text………] [×] │ │
|
||||
│ │ 3. [Criterion text………] [×] │ │
|
||||
│ │ [+ Add Criterion] │ │
|
||||
│ └────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────┬──────────┬──────────┬──────────┐ │
|
||||
│ │ Team │ Status │ Priority │ Complex. │ │
|
||||
│ │ [Select] │ [Select] │ [Select] │ [Select] │ │
|
||||
│ └──────────┴──────────┴──────────┴──────────┘ │
|
||||
│ │
|
||||
│ ┌─ Advanced Options ──────────────────────┐ │
|
||||
│ │ Model selector (see model-selector-ux.md) │ │
|
||||
│ │ Assign to, Parent task, Project, Product │ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ ⚠️ This will create a real task and notify the team. │ │
|
||||
│ │ It cannot be undone from this screen. │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ [Cancel] [Confirm & Launch]│
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sections (Detailed)
|
||||
|
||||
### 1. Dialog Header
|
||||
|
||||
- **Title**: `DialogTitle` — "Review & Confirm Task"
|
||||
- **Description**: `DialogDescription` — "You decide what gets sent to the team."
|
||||
|
||||
Both are required and always visible. The description is the human-agency anchor copy mandated by the Head of Marketing.
|
||||
|
||||
### 2. Title Field
|
||||
|
||||
- `Label` + `Input`
|
||||
- Required (`*` indicator, `text-destructive` color)
|
||||
- Validation: 5–200 characters (same rule as `CreateTaskDialog`)
|
||||
- Error state: `border-destructive` + `text-xs text-destructive` message
|
||||
- Pre-filled by LLM draft; user can edit inline.
|
||||
|
||||
### 3. Description Field
|
||||
|
||||
- Reuse `MarkdownEditor` from `panel/src/components/tasks/markdown-editor.tsx`
|
||||
- Required, min 20 characters
|
||||
- Preview toggle (Edit / Preview tabs using `Tabs` component)
|
||||
- Pre-filled by LLM draft; user can edit inline.
|
||||
|
||||
### 4. Acceptance Criteria
|
||||
|
||||
- Reuse `AcceptanceCriteriaEditor` from `panel/src/components/tasks/acceptance-criteria-editor.tsx`
|
||||
- Required, at least one criterion
|
||||
- Numbered list with drag handles (if the existing editor supports reordering) or simple add/remove
|
||||
- Pre-filled by LLM draft; user can add, edit, remove.
|
||||
|
||||
### 5. Metadata Grid
|
||||
|
||||
A 4-column grid (`grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4`) using `Select` components:
|
||||
|
||||
| Field | Component | Options | Default (from draft) |
|
||||
|-------|-----------|---------|----------------------|
|
||||
| Team | `Select` | `Object.values(Team)` | LLM suggestion |
|
||||
| Status | `Select` | `PENDING`, `BACKLOG` | `PENDING` |
|
||||
| Priority | `Select` | `P0`–`P3` | `P2` (Medium) |
|
||||
| Complexity | `Select` | `LOW`, `MEDIUM`, `HIGH` | LLM suggestion |
|
||||
|
||||
All wrapped in `Label` + `SelectTrigger` + `SelectContent` + `SelectItem`.
|
||||
|
||||
### 6. Advanced Options Drawer
|
||||
|
||||
- `Collapsible` from `panel/src/components/ui/collapsible.tsx`
|
||||
- Trigger: `Button` variant `ghost` with `ChevronRight` / `ChevronDown` icons
|
||||
- Contents:
|
||||
- **Model selector** — see [`03-model-selector-ux.md`](03-model-selector-ux.md)
|
||||
- **Assign To** — `AgentSelector` (`panel/src/components/agents/agent-selector.tsx`)
|
||||
- **Parent Task** — `TaskSelector` (`panel/src/components/tasks/task-selector.tsx`)
|
||||
- **Project** — `ProjectSelector` (`panel/src/components/projects/project-selector.tsx`)
|
||||
- **Product** — `Select` from `CreateTaskDialog` product list
|
||||
|
||||
### 7. Warning Banner
|
||||
|
||||
A full-width `Alert` (if available; otherwise a `Card` with `border-destructive` or `bg-destructive/10`):
|
||||
|
||||
- Icon: `AlertTriangle` from `lucide-react`
|
||||
- Text: "This will create a real task and notify the team. It cannot be undone from this screen."
|
||||
- Purpose: prevents the "I thought this was just a preview" error.
|
||||
|
||||
### 8. Footer Actions
|
||||
|
||||
- `DialogFooter` with `flex-col-reverse sm:flex-row sm:justify-end gap-2`
|
||||
- **Cancel** (`Button` variant `outline`): closes dialog, returns to chat draft preview. Does **not** discard the draft.
|
||||
- **Confirm & Launch** (`Button` primary): submits to the task-creation API.
|
||||
- On click: button enters `disabled` state, text changes to "Launching…", spinner (use `Loader2` icon with `animate-spin`)
|
||||
- On success: dialog closes, chat shows success card
|
||||
- On error: button re-enables, error banner appears above footer
|
||||
|
||||
---
|
||||
|
||||
## Un-bypassable Guardrails
|
||||
|
||||
### UI Guardrails
|
||||
|
||||
1. **No keyboard shortcut** launches the task. `Enter` inside any field does **not** submit the form; only the explicit footer button does.
|
||||
2. **No click-outside dismissal** when dirty. If the user has edited any field, clicking the overlay shows a secondary confirmation: "You have unsaved changes. Discard them?" (`AlertDialog` with "Keep Editing" / "Discard").
|
||||
3. **Scroll requirement**: The dialog is tall enough that the footer may be below the fold on small screens. The warning banner is positioned **above** the footer so the user must scroll past it to reach the confirm button.
|
||||
|
||||
### API Guardrails (Frontend Contract)
|
||||
|
||||
- The frontend must **not** call the task-creation endpoint directly from the chat state. The only valid call path is:
|
||||
```
|
||||
Chat → Review Modal (user opens) → Confirm Button (user clicks) → POST /tasks
|
||||
```
|
||||
- There is no `?skip_review=true` query param, no hidden route, and no keyboard bypass.
|
||||
- Backend should reject any Prompter-originated task creation that does not include a `confirmed_by_human: true` flag in the payload (enforced by the Backend Cell; noted here for cross-cell alignment).
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- Focus trap: when dialog opens, focus moves to the Title `Input`.
|
||||
- `aria-describedby` on the Confirm button pointing to the warning banner text.
|
||||
- All `Select` triggers have visible `Label` associations (`htmlFor` + `id`).
|
||||
- Error messages use `aria-live="assertive"` so screen readers announce validation failures immediately.
|
||||
|
||||
---
|
||||
|
||||
## Copy Reference
|
||||
|
||||
| Element | Copy |
|
||||
|---------|------|
|
||||
| Dialog title | "Review & Confirm Task" |
|
||||
| Dialog subtitle | "You decide what gets sent to the team." |
|
||||
| Warning banner | "This will create a real task and notify the team. It cannot be undone from this screen." |
|
||||
| Cancel button | "Cancel" |
|
||||
| Confirm button (idle) | "Confirm & Launch" |
|
||||
| Confirm button (loading) | "Launching…" |
|
||||
| Dirty-state discard prompt title | "Discard changes?" |
|
||||
| Dirty-state discard prompt body | "You have unsaved changes. If you cancel, your edits will be lost." |
|
||||
| Dirty-state keep button | "Keep Editing" |
|
||||
| Dirty-state discard button | "Discard" |
|
||||
|
||||
---
|
||||
|
||||
## Component Inventory
|
||||
|
||||
| UI Element | File Path |
|
||||
|------------|-----------|
|
||||
| Dialog shell | `panel/src/components/ui/dialog.tsx` |
|
||||
| Alert (warning banner) | `panel/src/components/ui/alert-dialog.tsx` or custom `Card` |
|
||||
| Card | `panel/src/components/ui/card.tsx` |
|
||||
| Input | `panel/src/components/ui/input.tsx` |
|
||||
| Textarea / MarkdownEditor | `panel/src/components/tasks/markdown-editor.tsx` |
|
||||
| Select | `panel/src/components/ui/select.tsx` |
|
||||
| Label | `panel/src/components/ui/label.tsx` |
|
||||
| Button | `panel/src/components/ui/button.tsx` |
|
||||
| Collapsible | `panel/src/components/ui/collapsible.tsx` |
|
||||
| Badge | `panel/src/components/ui/badge.tsx` |
|
||||
| Tabs | `panel/src/components/ui/tabs.tsx` |
|
||||
| AcceptanceCriteriaEditor | `panel/src/components/tasks/acceptance-criteria-editor.tsx` |
|
||||
| AgentSelector | `panel/src/components/agents/agent-selector.tsx` |
|
||||
| TaskSelector | `panel/src/components/tasks/task-selector.tsx` |
|
||||
| ProjectSelector | `panel/src/components/projects/project-selector.tsx` |
|
||||
@@ -0,0 +1,141 @@
|
||||
# Prompter — Model Selector UX Specification
|
||||
|
||||
## Principle
|
||||
|
||||
Most users do not know which model drafts better tasks. The model selector should be available for power users but invisible for everyone else. The default must be safe, fast, and context-aware.
|
||||
|
||||
---
|
||||
|
||||
## Placement
|
||||
|
||||
**Inside the Advanced Options drawer** of the confirmation interstitial.
|
||||
|
||||
- `Collapsible` trigger label: "Advanced Options"
|
||||
- When expanded, the first item in the drawer is the model selector.
|
||||
|
||||
This follows the existing `CreateTaskDialog` pattern where advanced fields (parent task, assignee, git config) are tucked behind a `Collapsible` with `ChevronRight` / `ChevronDown` icons.
|
||||
|
||||
Rationale:
|
||||
- Reduces cognitive load on the primary review screen.
|
||||
- Prevents choice paralysis for users who don’t care about the model.
|
||||
- Aligns with the Head of Marketing directive: "most users don’t know which model drafts better tasks."
|
||||
|
||||
---
|
||||
|
||||
## Component
|
||||
|
||||
`Select` from `panel/src/components/ui/select.tsx`:
|
||||
|
||||
```tsx
|
||||
<Select value={model} onValueChange={setModel}>
|
||||
<SelectTrigger className="w-full">
|
||||
<SelectValue />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
<SelectItem value="recommended">
|
||||
⭐ Recommended — {dynamicLabel}
|
||||
</SelectItem>
|
||||
<SelectItem value="claude-sonnet-4">
|
||||
Claude Sonnet 4 — Balanced
|
||||
</SelectItem>
|
||||
<SelectItem value="gpt-4o">
|
||||
GPT-4o — Fast
|
||||
</SelectItem>
|
||||
<SelectItem value="claude-opus-4">
|
||||
Claude Opus 4 — Deep reasoning
|
||||
</SelectItem>
|
||||
</SelectContent>
|
||||
</Select>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Defaults
|
||||
|
||||
### Default Selection: "Recommended"
|
||||
|
||||
The `recommended` value is not a real model ID; it is a frontend alias that resolves to a model based on the draft's estimated complexity:
|
||||
|
||||
| Draft Complexity | Resolved Model | Rationale |
|
||||
|----------------|----------------|-----------|
|
||||
| `LOW` | `gpt-4o` or lightweight equivalent | Fast, cheap, good enough for simple tasks |
|
||||
| `MEDIUM` | `claude-sonnet-4` | Balanced quality and speed |
|
||||
| `HIGH` | `claude-opus-4` | Deep reasoning for complex specs |
|
||||
|
||||
**Dynamic label**: the Select trigger should display the resolved model name in the description:
|
||||
|
||||
> ⭐ Recommended — Claude Sonnet 4
|
||||
|
||||
This gives transparency without requiring the user to make a manual choice.
|
||||
|
||||
### How Complexity Is Determined
|
||||
|
||||
1. **LLM suggestion**: the drafting LLM outputs an `estimated_complexity` field as part of the structured draft.
|
||||
2. **User override**: if the user changes the Complexity `Select` in the review modal, the recommended model re-evaluates automatically.
|
||||
3. **No user model preference persistence in Phase 1** — each session starts fresh with `recommended`.
|
||||
|
||||
---
|
||||
|
||||
## Option Descriptions
|
||||
|
||||
Each `SelectItem` should have a one-line subtitle explaining when to choose it:
|
||||
|
||||
```
|
||||
⭐ Recommended — Claude Sonnet 4
|
||||
(Best balance for this task's complexity)
|
||||
|
||||
Claude Sonnet 4 — Balanced
|
||||
(Good for most tasks)
|
||||
|
||||
GPT-4o — Fast
|
||||
(Quick drafts, simpler specs)
|
||||
|
||||
Claude Opus 4 — Deep reasoning
|
||||
(Complex architecture or security tasks)
|
||||
```
|
||||
|
||||
Implementation note: if `SelectItem` does not natively support subtitles, append the subtitle as muted text inside the item using a nested `span` with `text-muted-foreground text-xs`.
|
||||
|
||||
---
|
||||
|
||||
## Visual Hierarchy
|
||||
|
||||
```
|
||||
┌─ Advanced Options ──────────────────────┐
|
||||
│ │
|
||||
│ Model │
|
||||
│ [⭐ Recommended — Claude Sonnet 4 ▼] │
|
||||
│ ├─ ⭐ Recommended — Claude Sonnet 4 │
|
||||
│ ├─ Claude Sonnet 4 — Balanced │
|
||||
│ ├─ GPT-4o — Fast │
|
||||
│ └─ Claude Opus 4 — Deep reasoning │
|
||||
│ │
|
||||
│ Assign To … │
|
||||
│ Parent Task … │
|
||||
│ … │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- `Label` with `htmlFor` tied to the `SelectTrigger` id.
|
||||
- `aria-describedby` on the trigger pointing to a helper paragraph: "The model used to draft this task. 'Recommended' picks the best fit automatically."
|
||||
- `SelectContent` should trap focus while open; `Esc` closes the dropdown.
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope (Phase 2)
|
||||
|
||||
- Model comparison side-by-side
|
||||
- User-level default model preference
|
||||
- Cost/usage indicators per model
|
||||
- Temperature / max-tokens sliders
|
||||
- Custom system prompt editing
|
||||
|
||||
---
|
||||
|
||||
## Cross-Cell Note
|
||||
|
||||
The frontend sends the resolved model ID (not the alias) to the backend chat endpoint. The backend endpoint in `roboco/services/llm.py` already handles multi-provider routing; the frontend only needs to pass the model string in the payload.
|
||||
@@ -0,0 +1,153 @@
|
||||
# Prompter — Naming & Navigation Specification
|
||||
|
||||
## Principle
|
||||
|
||||
The existing Panel uses plain, descriptive nouns for navigation:
|
||||
- "Overview", "Tasks", "Kanban"
|
||||
- "Projects", "Products", "Git"
|
||||
- "Agents", "Knowledge Base", "Auditor"
|
||||
|
||||
A branded product name like "Prompter" risks feeling like a third-party plugin. The name should fit the existing vocabulary and signal value immediately.
|
||||
|
||||
---
|
||||
|
||||
## Naming Options
|
||||
|
||||
### Option A: Task Assistant *(Recommended)*
|
||||
|
||||
- **Label**: "Task Assistant"
|
||||
- **Rationale**:
|
||||
- Plain noun + descriptor pattern (matches "Knowledge Base", "AI Providers")
|
||||
- Immediately communicates value: it helps you with tasks.
|
||||
- Does not over-promise autonomy — "assistant" implies human control.
|
||||
- Works in sentence case naturally: "Open the Task Assistant."
|
||||
- **Subtitle copy**: "Draft tasks with your AI teammate."
|
||||
- **Concerns**: Slightly longer than other nav items; may truncate in collapsed sidebar.
|
||||
- **Mitigation**: Collapsed sidebar uses icon + tooltip; length is fine in expanded view.
|
||||
|
||||
### Option B: Draft
|
||||
|
||||
- **Label**: "Draft"
|
||||
|
||||
- **Rationale**:
|
||||
- Single word, action-oriented, fits the existing terse style.
|
||||
- Signals the core output: a draft task.
|
||||
- Human-centric verb — you draft, the AI helps.
|
||||
- **Subtitle copy**: "Draft tasks with your AI teammate."
|
||||
- **Concerns**:
|
||||
- Ambiguous: could be confused with "draft tasks" as a filter state in the Tasks page.
|
||||
- Less discoverable for users who don’t already know the feature exists.
|
||||
|
||||
### Option C: Composer
|
||||
|
||||
- **Label**: "Composer"
|
||||
|
||||
- **Rationale**:
|
||||
- Evokes creation and authoring.
|
||||
- Familiar to developers (IDE composers, email composers).
|
||||
- **Subtitle copy**: "Compose tasks with your AI teammate."
|
||||
- **Concerns**:
|
||||
- Slightly more abstract than "Task Assistant".
|
||||
- May imply musical or creative composition rather than structured task specs.
|
||||
|
||||
### Internal Name
|
||||
|
||||
"Prompter" remains the **internal engineering and marketing codename**. It is acceptable in internal documentation, Slack, and code comments. The UI label is the user-facing name chosen above.
|
||||
|
||||
---
|
||||
|
||||
## Sidebar Placement
|
||||
|
||||
### Recommended Placement
|
||||
|
||||
Insert under the **Work Management** section, between "Kanban" and "Projects":
|
||||
|
||||
```typescript
|
||||
const navItems = [
|
||||
// Dashboard
|
||||
{ title: "Overview", href: "/overview", icon: LayoutDashboard },
|
||||
|
||||
// Work Management
|
||||
{ title: "Tasks", href: "/tasks", icon: ListTodo },
|
||||
{ title: "Kanban", href: "/kanban", icon: Kanban },
|
||||
{ title: "Task Assistant", href: "/prompter", icon: Sparkles }, // NEW
|
||||
|
||||
// Development
|
||||
{ title: "Projects", href: "/projects", icon: FolderGit2 },
|
||||
{ title: "Products", href: "/products", icon: Boxes },
|
||||
{ title: "Git", href: "/git", icon: GitBranch },
|
||||
|
||||
// ... rest unchanged
|
||||
];
|
||||
```
|
||||
|
||||
### Icon
|
||||
|
||||
Use `Sparkles` from `lucide-react` (not currently imported in `sidebar.tsx`).
|
||||
|
||||
- Rationale: universally understood as "AI / magic / assistance" without being overly literal.
|
||||
- Alternative: `MessageSquarePlus` — more literal (chat + create), but `Sparkles` is more distinctive among existing icons.
|
||||
|
||||
### Active State
|
||||
|
||||
Same as existing nav items:
|
||||
- Active: `bg-primary text-primary-foreground`
|
||||
- Inactive: `text-muted-foreground hover:bg-muted hover:text-foreground`
|
||||
|
||||
---
|
||||
|
||||
## Page Title & Meta
|
||||
|
||||
| Surface | Copy (Option A) |
|
||||
|---------|-----------------|
|
||||
| Sidebar nav item | "Task Assistant" |
|
||||
| Browser tab title | "Task Assistant — RoboCo Panel" |
|
||||
| Page H1 | "Task Assistant" |
|
||||
| Page subtitle | "Describe what you need. The assistant will ask questions and draft a task for your team." |
|
||||
| Empty-state heading | "What do you want to build?" |
|
||||
| Empty-state subtext | "Describe the task in plain language. The assistant will clarify and draft a spec you can review before sending it to the team." |
|
||||
|
||||
---
|
||||
|
||||
## URL
|
||||
|
||||
`/prompter` — keep the engineering slug regardless of display name. This avoids routing churn if the display name changes later.
|
||||
|
||||
- Redirects: none needed for MVP.
|
||||
- Deep-linking: `/prompter` always loads the empty/chat state; there is no persisted session ID in the URL for Phase 1.
|
||||
|
||||
---
|
||||
|
||||
## Discoverability
|
||||
|
||||
### Primary
|
||||
- Sidebar entry at all times (not hidden behind permissions or feature flags for Phase 1).
|
||||
|
||||
### Secondary
|
||||
- Quick Actions bar on Overview dashboard: add a "New Task (AI-assisted)" button that links to `/prompter`.
|
||||
- Uses existing `QuickActionsBar` pattern in `panel/src/components/dashboard/quick-actions-bar.tsx`.
|
||||
- Icon: `Sparkles` next to the existing "New Task" button.
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Criterion | Task Assistant | Draft | Composer |
|
||||
|-----------|---------------|-------|----------|
|
||||
| Fits existing panel vocabulary | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
|
||||
| Communicates value immediately | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
|
||||
| Does not over-promise autonomy | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
|
||||
| Short enough for sidebar | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
|
||||
| Distinct from other pages | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
|
||||
| Works in marketing copy | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
|
||||
| **Total** | **16** | **13** | **12** |
|
||||
|
||||
**UX/UI Cell recommendation**: **Task Assistant** (Option A).
|
||||
|
||||
---
|
||||
|
||||
## Cross-Cell Handoff
|
||||
|
||||
- **Frontend**: implement route `/prompter`, sidebar entry with `Sparkles`, page layout.
|
||||
- **Backend**: no API changes needed for naming; slug remains `prompter` in code.
|
||||
- **Marketing**: "Draft tasks with your AI teammate" is the recommended tagline; aligns with "Task Assistant" label.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Prompter — UX/UI Design Deliverables
|
||||
|
||||
This directory contains the interaction design and confirmation flow specification for the **Prompter** feature (Phase 1). All patterns are mapped to the existing Panel design system so the Frontend Cell can implement them in parallel without inventing new visual language.
|
||||
|
||||
## Contents
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| [`01-interaction-spec.md`](01-interaction-spec.md) | End-to-end chat → draft → review → confirm → launch flow, state machine, component mappings, error/loading patterns |
|
||||
| [`02-confirmation-interstitial.md`](02-confirmation-interstitial.md) | Mandatory human-in-the-loop review modal: layout, copy, actions, un-bypassable guardrails |
|
||||
| [`03-model-selector-ux.md`](03-model-selector-ux.md) | Model selector placement, defaults, and cognitive-load reduction |
|
||||
| [`04-naming-and-navigation.md`](04-naming-and-navigation.md) | Naming alternatives to "Prompter" and sidebar nav placement |
|
||||
|
||||
## Design System Baseline
|
||||
|
||||
All screens are built from components already present in `panel/src/components/ui/` and `panel/src/components/layout/`:
|
||||
|
||||
- **Dialog** — `panel/src/components/ui/dialog.tsx` (Radix-based, animates in/out)
|
||||
- **AlertDialog** — `panel/src/components/ui/alert-dialog.tsx` (for destructive/breaking confirmations)
|
||||
- **Card** — `panel/src/components/ui/card.tsx` (sections, draft preview)
|
||||
- **Tabs** — `panel/src/components/ui/tabs.tsx` (chat vs. draft review)
|
||||
- **Select** — `panel/src/components/ui/select.tsx` (team, model, status)
|
||||
- **Collapsible** — `panel/src/components/ui/collapsible.tsx` (advanced options drawer)
|
||||
- **Button** — `panel/src/components/ui/button.tsx` (primary, outline, ghost, destructive)
|
||||
- **Input / Textarea** — `panel/src/components/ui/input.tsx`, `panel/src/components/ui/textarea.tsx`
|
||||
- **Badge** — `panel/src/components/ui/badge.tsx` (team labels, complexity indicators)
|
||||
- **ScrollArea** — `panel/src/components/ui/scroll-area.tsx` (chat history, criteria list)
|
||||
- **Skeleton** — `panel/src/components/ui/skeleton.tsx` (loading states)
|
||||
- **Sidebar** — `panel/src/components/layout/sidebar.tsx` (navigation structure)
|
||||
|
||||
> **Rule**: No new visual language. Reuse existing tokens, spacing, and color variables (`bg-background`, `text-muted-foreground`, `border`, `shadow-sm`, etc.).
|
||||
|
||||
## Accessibility Baseline
|
||||
|
||||
- Focus trap inside dialogs on open (`focus-visible:ring-ring`)
|
||||
- `aria-live="polite"` on chat message list for screen-reader announcements
|
||||
- Keyboard: `Enter` to send, `Esc` to close modals, `Tab` cycles focus
|
||||
- All icon-only buttons need `sr-only` text labels
|
||||
|
||||
## Version
|
||||
|
||||
Phase 1 — chat + draft-review + create/launch (no persistence/history).
|
||||
Reference in New Issue
Block a user