# UX Reference: Unified Task Reports by Type

**Feature Branch**: `020-task-reports-design`
**Created**: 2026-02-22  
**Status**: Draft

## 1. User Persona & Context

* **Who is the user?**: Operations engineer or analytics platform administrator who monitors task outcomes.
* **What is their goal?**: Quickly understand results across all task categories and identify items that require action.
* **Context**: Working in the web interface during daily operational checks, often under time pressure and with mixed task activity (LLM checks, backups, migrations, documentation jobs).

## 2. The "Happy Path" Narrative

The user opens Reports and immediately sees a unified stream of all task outcomes. Each report card is visually distinct by task type, so the user can scan and recognize categories without reading everything line by line. They apply a status filter to find only failed items, open one report, and instantly understand what happened and what to do next. The page feels organized, predictable, and fast to scan even with many entries. The user resolves priorities without switching across multiple sections.

## 3. Interface Mockups

### UI Layout & Flow (if applicable)

**Screen/Component**: Unified Reports Dashboard

* **Layout**:  
  - Header row with page title, summary counters, and last update timestamp.  
  - Filter toolbar below header (Type, Status, Time Range, Search).  
  - Main content area with report cards/list rows sorted by latest update.  
  - Optional right-side detail panel or drill-in page for selected report.
* **Key Elements**:
  * **Type Filter**: Multi-select control with options: LLM documentation/verification, Backup, Migration, Documentation.
  * **Status Filter**: Values: Success, Failed, In Progress, Partial.
  * **Report Card / Row**: Shows type badge, title, short summary, status indicator, timestamp, and quick action "View details".
  * **Type Badge**: Explicit textual label + visual style (color/icon/pattern) unique per task type.
  * **Empty State Block**: Guidance text and reset-filters action when no reports match current filters.
* **States**:
  * **Default**: Mixed reports displayed with clear type distinctions and latest-first ordering.
  * **Loading**: Skeleton placeholders in report list area; filters remain visible.
  * **Success**: Updated reports appear with subtle confirmation cue ("Reports updated").
  * **No Data**: Friendly empty state, explains there are no reports yet for selected scope.
  * **Filtered Empty**: "No reports match your filters" with one-click clear filter action.

### Visual Language by Report Type

1. **LLM Documentation/Verification**
   - Emphasis: Review and validation.
   - Visual cues: Analysis-style badge and prominent summary snippet with confidence/verification context.
   - Reading focus: Findings, checks performed, verification result.

2. **Backup**
   - Emphasis: Safety and recoverability.
   - Visual cues: Protection-style badge and quick visibility of snapshot/time/coverage outcomes.
   - Reading focus: Completion confirmation, backup scope, recoverability notes.

3. **Migration**
   - Emphasis: Change progression and risk.
   - Visual cues: Transition-style badge and timeline/progress context.
   - Reading focus: Objects moved, status by stage, blockers or rollback guidance.

4. **Documentation**
   - Emphasis: Content updates and clarity.
   - Visual cues: Document-style badge and concise change summary.
   - Reading focus: What was updated, affected sections, quality/review notes.

## 4. The "Error" Experience

**Philosophy**: Show what went wrong in plain language, preserve user context, and provide immediate next steps.

### Scenario A: Partial or Missing Report Data

* **User Action**: Opens a report where some expected fields are absent.
* **System Response**:
  * Missing values are shown as explicit placeholders (e.g., "Not provided") instead of blank spaces.
  * An inline notice explains that report data is incomplete but still viewable.
* **Recovery**: User can continue reviewing available data and use suggested follow-up action (e.g., retry load or inspect source task).

### Scenario B: Unknown Task Type

* **System Response**:
  * Report remains visible using a neutral fallback style labeled "Other / Unknown Type".
  * A short note indicates this type is not yet mapped to a dedicated design profile.
* **Recovery**: User can still read status/details and proceed; no data is hidden or blocked.

### Scenario C: No Reports Match Filters

* **User Action**: Applies strict type + status filters and gets empty results.
* **System Response**:
  * Clear empty-filter message in the content area.
  * One-click actions: "Clear filters" and "Show all recent reports".
* **Recovery**: User restores broader scope without reloading the page.

### Scenario D: Failed Report

* **System Response**:
  * Failure status is explicit and visually prominent.
  * Detail view includes brief reason, impact summary, and recommended next action.
* **Recovery**: User can quickly decide whether to rerun, escalate, or investigate.

## 5. Tone & Voice

* **Style**: Concise, operational, confidence-building.
* **Terminology**: Use "Report", "Task Type", "Status", "Details", "Next Action"; avoid ambiguous shorthand.