# AWP UX Research + Design Polish — Round 2 **Date:** 2026-08-19 **Status:** Recommended UX baseline before further page design or architecture deepening **Inputs:** Current `AWP-UI-SCREEN-ATLAS.md`, current AWP planning/architecture baseline, `ux-researcher` role, `ux-designer` anti-slop directives, and the established AWP product goal of making work state understandable in seconds. --- ## 1. Executive verdict The current UI atlas is substantially better than a generic DevOps dashboard, but its information architecture is still too heavily shaped by the **internal domain model**. AWP's backend needs Projects, Plans, FactoryRuns, AgentRuns, CI, Releases, Deployments, Incidents, Accounts, Providers, Configuration, Audit, and Cluster as distinct domains. The user should **not have to navigate that ontology as the normal way to understand work**. The core UX should instead be organized around five questions: 1. What did I ask for? 2. Where is it now? 3. What happened last? 4. What happens next? 5. Do I need to act? The next UX revision should therefore move from: > **domain-first navigation + dashboard pages** to: > **work-first navigation + context-preserving drill-down** The system can remain architecturally deep while presenting a much smaller mental model. --- # 2. Research method and evidence level This is a **heuristic / workflow research round**, not claimed empirical user research. No live analytics, interviews, session recordings, task-completion measurements, or support-ticket corpus were available. Therefore: - findings based on the existing product model and screen atlas are **design findings**; - behavioral claims are framed as **hypotheses to validate**; - no synthetic persona is treated as factual user evidence; - the recommended validation plan uses short task-based usability studies before implementation freezes. The appropriate behavioral roles for testing are: - **Owner / project manager** — asks for work, needs rapid status comprehension, makes high-impact decisions. - **Technical operator** — diagnoses CI, execution, deployment, and cluster failures. - **Approver** — enters only when a decision is required and needs enough evidence to act safely. - **Auditor / reviewer** — reconstructs what happened and why. These are testing roles, not demographic personas. --- # 3. Highest-priority findings ## P0 — The shell has too many equal-weight destinations Current top-level navigation exposes approximately a dozen product domains: - Overview - Projects - Plans - Factory - Agents - CI - Releases - Deployments - Cluster - Incidents - Approvals - Accounts - Settings This makes the user translate a human question such as: > "What happened to the SEO rollback work?" into an implementation-domain question: > "Is that under Plans, Factory, Agents, CI, Reviews, or Deployments?" That translation is unnecessary cognitive work. ### Decision Reduce normal top-level navigation to: ```text HOME WORK EXECUTION DELIVERY OPERATIONS SETTINGS ``` with: ```text HOME Work command center Needs your attention WORK Projects Plans Requests / Work Items Saved views EXECUTION Factory Runs Agents CI DELIVERY Reviews Releases Deployments OPERATIONS Incidents Cluster Queues Health SETTINGS Accounts / Models Providers Configuration Security Integrations Audit ``` `Needs your attention` remains globally accessible as a badge/drawer and has a full-page route, but should not compete visually with lifecycle navigation. Global search / command palette remains available everywhere. --- ## P0 — Home should be a work command center, not a dashboard of domains The current global Overview is metric-heavy and splits attention between infrastructure, projects, approvals, and factory activity. The primary user job is not "inspect a dashboard." It is: > "Show me what I asked for, what is moving, what is stuck, and whether I need to intervene." ### Decision Replace `UI-OVERVIEW-01` with `UI-OVERVIEW-01 v2`: ```text +--------------------------------------------------------------------------------------------------+ | Work Search... Project: All Updated 4s | +--------------------------------------------------------------------------------------------------+ | IN FLIGHT QUEUED NEEDS YOU SHIPPED TODAY | | 4 / 5 lanes 7 3 6 | +--------------------------------------------------------------------------------------------------+ | Asked | In progress | Waiting | Done | |---------------------------+----------------------------+---------------------------+--------------| | Request / task card | Request / task card | Request / task card | ... | | human-readable title | current owner | WAITING FOR: CI-208 | | | project + age | latest meaningful update | WHY: integration tests | | | | next expected action | NEXT: auto-continue | | |---------------------------+----------------------------+---------------------------+--------------| | ... independent column scroll; visible WIP where applicable ... | +--------------------------------------------------------------------------------------------------+ | RECENT REQUESTS — last 5 | | Asked 18m ago "Fix SEO rollback symmetry" In progress latest update 2m ago | | ... | +--------------------------------------------------------------------------------------------------+ ``` Rules: - The board is the dominant vertical region. - `Asked / In progress / Waiting / Done` is the default owner-facing lifecycle. - "Ready" can exist as a planning/workflow state without requiring a permanent owner-facing column. - Project chips / filters update the same board rather than opening a separate dashboard. - Each card answers **current state + last meaningful update + next step** without opening it. - Waiting cards always show the reason. - Done is visually quieter than active work. - The request log is limited to five rows and does not compete with the board. --- ## P0 — Preserve one continuous story from request to deployment The atlas correctly models provenance, but the UX still requires many page changes to reconstruct the story: ```text Task -> FactoryRun -> AgentRun -> ChangeSet -> Review -> CI -> Release -> Deployment ``` The user should be able to follow this relationship chain without repeatedly returning to global navigation. ### Decision Every work item/detail screen gets a persistent **Lifecycle Rail**: ```text Asked -> Planned -> In Factory -> Change produced -> Review -> CI -> Merged -> Released -> Deployed ``` The current stage is visually dominant. Completed stages are compact. Future stages are subdued. Clicking a stage opens its detail in-place or in the context inspector while preserving the current work item. IDs remain available, but human-readable context stays primary. --- ## P0 — Planning is still methodology-first in places The current onboarding and Delivery Design screens expose: ```text Predictive / Iterative / Incremental / Continuous Flow Scrum / Kanban / Scrumban / Custom ``` as primary decisions. These are implementation/planning vocabulary. They force the user to understand methodology before understanding consequences. ### Decision Planning becomes **configuration-first, methodology-second**. The primary screen asks consequence questions: ```text How should work enter execution? [Start when ready] [Start in planned batches] How much may run at once? [ 4 ] When priorities change during active work: [Allow immediately] [After current work finishes] [Require approval] Review cadence: [Each task] [Each wave] [Before release] Release cadence: [After each accepted change] [After each wave] [At end of plan] ``` Then show: ```text Preset match: Scrumban ``` or: ```text Preset match: Custom ``` as a secondary interpretation. The user may deliberately choose a preset first, but presets should fill settings rather than become mutually exclusive product modes. --- ## P0 — Approval pages need a decision brief, not an architecture dump Current approval pages are already structured, but they still resemble a technical comparison sheet. A user entering through "Needs your attention" needs to know: ```text What am I deciding? Why now? What is the recommendation? What is the impact? What happens if I approve? What happens if I reject? Can this be reversed? What evidence supports the recommendation? ``` ### Decision `UI-APPROVAL-01 v2`: ```text +--------------------------------------------------------------------------------------------------+ | Decision needed Architecture • waiting 23m | | AWP / Foundation / Cluster identity model [x] | +--------------------------------------------------------------------------------------------------+ | DECIDE | | How should ephemeral agent workloads receive cluster identity? | +--------------------------------------------------------------------------------------------------+ | RECOMMENDED: ServiceAccount per AgentRun | | Why: smallest blast radius; identity expires with the run | | | | Impact: affects all new AgentRuns | | Reversible: yes, configuration change | | Blocking: 2 tasks / 1 factory run | +--------------------------------------------------------------------------------------------------+ | Alternative: shared factory identity [Compare details] | +--------------------------------------------------------------------------------------------------+ | Evidence: security model • K3s capability test • affected policy [Open evidence] | +--------------------------------------------------------------------------------------------------+ | [Request changes] [Reject] [Approve recommendation] | +--------------------------------------------------------------------------------------------------+ ``` Rules: - Exactly one primary action. - Recommendation is explicit. - Impact and reversibility are visible before action. - Technical detail is progressively disclosed. - Production/destructive decisions receive risk-appropriate confirmation. - Routine reversible decisions should prefer undo/reversal over excessive confirmation. --- # 4. Secondary findings ## P1 — Factory should start with the human narrative, not the graph The execution graph is useful for diagnosis, but it is not the first thing an owner needs. `UI-FACTORY-02 v2` first screen should present: ```text Requested work Current stage Latest meaningful result Current owner Why anything is waiting Next expected transition Need for human action ``` The graph remains a first-class secondary tab. --- ## P1 — Agent pages currently expose too much tool noise by default Agent chat is useful because it supports steering, but tool calls should not dominate the default reading experience. Default Agent view: ```text Current objective Current state Latest meaningful finding Current action Pending question / blocker Steer agent ``` Tool activity, files, command output, raw events, and full diff remain one click away. A collapsed "technical activity" stream may show meaningful milestones without inserting every tool invocation into the conversation. --- ## P1 — Configuration should be human-readable before key-readable Current matrix rows expose identifiers such as: ```text factory.maxAgents ci.changeImpact autonomy.merge ``` These are useful to engineers and support, but are not ideal primary labels. Use: ```text Maximum parallel agents Change-impact CI Merge approval ``` with the canonical key shown as secondary metadata or in Advanced mode. The strong existing provenance model should remain: ```text effective value defined at inherited from why read-only history ``` --- ## P1 — List pages need one reusable interaction model Projects, Plans, Factory Runs, Agents, CI, Releases, Deployments, Incidents, Reviews, Accounts, Models, Audit, and queues should not each invent their own controls. Create one collection pattern: ```text Search Filter Sort Group Board/List where meaningful Saved views Pagination / load-more for large sets Keyboard row navigation Bulk selection only where safe URL-persisted view state ``` The user should learn the collection interaction once. --- ## P1 — Waiting is a first-class user state The existing `Explain Waiting` pattern is one of the strongest pieces in the atlas. Promote it from a pattern used selectively to an invariant: Every `WAITING`, `QUEUED`, `BLOCKED`, `PAUSED`, or `PENDING APPROVAL` state must expose: ```text waiting for since when why required current owner latest progress timeout / escalation where applicable what happens next whether the user can or should act ``` --- ## P1 — Failure/recovery is also a first-class narrative The existing deployment recovery screen establishes the right structure: ```text What failed Why What AWP already tried What is happening now What happens next ``` Use this same structure for: - Factory failure - Agent failure - CI failure - Merge failure - Release failure - Deployment failure - Cluster failure - Provider degradation Do not make the user infer this from logs. --- # 5. Global design rules to add to the canonical atlas ## UI-PATTERN-06 — Complete Data States Every data-driven page has: ```text Loading Empty Error Populated Stale / disconnected where applicable ``` Loading uses geometry-compatible skeletons with reserved space. No shimmer is required. Empty state: one human sentence + one useful action. Error state: explain what failed and what the user can do. No page may be specified only in its populated state. --- ## UI-PATTERN-07 — Action Hierarchy Per view/section: ```text Primary one Secondary limited Tertiary text / ghost / context menu Destructive separated physically and visually ``` High-frequency, low-risk actions should be direct. High-impact actions should expose consequences before confirmation. --- ## UI-PATTERN-08 — Context Inspector Operational collections and graphs may open a right-hand inspector rather than forcing immediate page navigation. Inspector contains: ```text human-readable identity state relationship context last meaningful event why next attention/action open full detail ``` Opening/closing it must preserve board/table position. --- ## UI-PATTERN-09 — URL Truth The URL must reproduce meaningful view state: ```text project view tab search filters sort page selected item where practical ``` Refresh or sharing the URL must not silently reset the user's investigation. --- ## UI-PATTERN-10 — Keyboard and Command Model Desktop UX supports: ```text Cmd/Ctrl+K command palette / global search J/K or arrows move through rows/cards where applicable Enter open selected item Esc close inspector/modal/clear transient selection ? shortcut reference ``` Shortcuts supplement, never replace, visible controls. --- ## UI-PATTERN-11 — Long-running Mutation Feedback For start, retry, cancel, deploy, rollback, enrollment, and similar actions: ```text 1. Trigger acknowledges immediately. 2. Duplicate mutation is prevented. 3. User sees current phase. 4. User can leave the page safely. 5. Returning restores progress. 6. Completion/failure produces an explicit result. ``` A long-running button must never appear to do nothing. --- ## UI-PATTERN-12 — Offline / Stale Safety Cached data may remain readable when the control plane is disconnected. Safe drafts/preferences may be queued. **Do not queue high-impact control-plane commands** such as: - approval - merge - production deployment - rollback - credential/security changes For those, require a live authoritative connection and explain why the action is unavailable. --- ## UI-PATTERN-13 — Accessibility and Focus Contract All implementation specs must require: - semantic controls; - visible keyboard focus; - predictable tab order; - modal focus trap and focus return; - no critical information encoded only by color; - at least 44×44 touch/click targets for compact controls where applicable; - live regions for async result/status announcements; - no hover-only critical actions. --- # 6. Screen-by-screen change register | Screen | Decision | |---|---| | `UI-SHELL-01` | **Major revision.** Collapse navigation into six goal-oriented groups. | | `UI-SHELL-02` | Keep; expand into navigation + action command palette. | | `UI-SHELL-03` | Keep; evolve into full attention inbox with prioritization/snooze where appropriate. | | `UI-OVERVIEW-01` | **Replace with board-dominant Work Command Center.** | | `UI-OVERVIEW-02` | Keep, but offer create/import as one primary path with secondary alternative. | | `UI-PROJECT-01` | Reduce dashboard density; project board/activity should dominate over KPI tiles. | | `UI-ONBOARD-01..07` | Keep sequence but make existing-repo onboarding adopt-first and diff-before-write; reduce methodology jargon. | | `UI-PLAN-01` | Keep summary; emphasize current work + blockers over progress percentage. | | `UI-PLAN-02` | **Major revision.** Default owner lifecycle: Asked / In progress / Waiting / Done. | | `UI-PLAN-03` | Keep as power-user hierarchy view. | | `UI-PLAN-04` | Keep as secondary timeline, not default. | | `UI-PLAN-05` | Add lifecycle rail + last/next/attention summary. | | `UI-PLANNING-01` | Simplify to "What do you want done?" plus optional context controls. | | `UI-PLANNING-02` | Keep split conversation/structured-draft model; auto-save. | | `UI-PLANNING-03` | **Major revision.** Consequence-first settings; methodology shown as preset interpretation. | | `UI-PLANNING-04` | Keep; add change summary versus current project defaults. | | `UI-FACTORY-02` | Human narrative first; graph second. | | `UI-FACTORY-03..07` | Keep as diagnostic/power views under Factory Run. | | `UI-AGENT-01` | Reduce default tool noise; make current objective/finding/steering dominant. | | `UI-APPROVALS-01` | Keep as attention-focused decision inbox; keyboard navigation. | | `UI-APPROVAL-01` | **Major revision.** Decision brief with impact/reversibility/recommendation. | | `UI-AUTONOMY-01` | Keep slider only as policy preset generator; show semantic preset name and rule delta. | | `UI-AUTONOMY-02` | Advanced only. | | `UI-CI-01..05` | Strong direction; add consistent list controls and failure narrative. | | `UI-RELEASE-01` | Add next transition and blocking approval in lifecycle rail. | | `UI-DEPLOYMENT-01..02` | Strong; use failure/recovery structure as canonical pattern elsewhere. | | `UI-CLUSTER-01..02` | Keep as Operations, not primary owner navigation. | | `UI-MACHINE-02..06` | Keep; make long-running enrollment resumable and leave-page-safe. | | `UI-INCIDENT-01` | Strong; surface current hypothesis + next action above raw timeline. | | `UI-RESOLVER-01` | Approval layout should inherit decision-brief pattern. | | `UI-CONFIG-01` | Human labels primary; raw keys secondary. | | `UI-AUDIT-01..02` | Keep as deep evidence layer; never primary operational UX. | | Collection screens | Adopt one canonical search/filter/sort/group/saved-view/URL-state interaction. | --- # 7. Proposed product navigation v2 ```text AWP | +-- HOME | +-- Work command center | +-- Needs your attention | +-- WORK | +-- Projects | +-- Plans | +-- Requests / Work Items | +-- Saved views | +-- EXECUTION | +-- Factory Runs | +-- Agents | +-- CI | +-- DELIVERY | +-- Reviews | +-- Releases | +-- Deployments | +-- OPERATIONS | +-- Incidents | +-- Cluster | +-- Queues | +-- Health | +-- SETTINGS +-- Accounts & Models +-- Providers +-- Configuration +-- Security +-- Integrations / Communications +-- Audit ``` The architecture keeps its richer domain map. The normal user navigation does not need to mirror it. --- # 8. Core journey tests before UI freeze Run a small usability study around real tasks, not preference questions. ## Test A — Recover an old request Prompt: > "You asked AWP to fix SEO rollback behavior yesterday. Find out what is happening." Success target: - user identifies the request; - current state understood; - last meaningful event identified; - next step identified; - human action requirement identified. Target time: **under 5 seconds for state comprehension after locating the item**. --- ## Test B — Explain waiting Prompt: > "This work has not moved for several minutes. Find out why." Success: - user can name what it is waiting for; - can explain why the dependency exists; - knows whether the system will continue automatically; - does not need logs. --- ## Test C — Make a production decision Prompt: > "AWP needs your approval before production. Decide whether to proceed." Success: - user can state impact; - understands recommendation; - understands reversibility; - opens evidence only if needed; - does not confuse Reject with Cancel/Close. --- ## Test D — Steer a running agent Prompt: > "The agent is solving the wrong part of the task. Correct it." Success: - finds current AgentRun from the work item; - understands current objective; - sends steering message; - sees immediate acknowledgement; - does not mistake the message for a new task. --- ## Test E — Recover a failed deployment Prompt: > "Production failed. Determine what AWP has tried and what will happen next." Success: - user sees failure reason; - sees attempted deterministic recovery; - sees active resolver state; - understands available rollback; - does not need to interpret raw Kubernetes/provider output. --- # 9. Metrics for the next research round Track: ```text Task success rate Time to locate target work Time to answer the five core questions Wrong-navigation count Backtracking count Approval decision confidence Accidental/high-risk action rate Search usage Command-palette usage Attention-inbox resolution time Waiting-state open-to-understanding time ``` Also record search queries that return no useful result: those reveal where the product's language and the user's language differ. --- # 10. What should not be designed yet Do not spend detailed visual-design effort on every existing atlas screen before validating the revised mental model. First freeze and test: 1. `UI-SHELL-01 v2` 2. `UI-OVERVIEW-01 v2` 3. `UI-PLAN-02 v2` 4. `UI-PLAN-05 v2` 5. `UI-PLANNING-02/03 v2` 6. `UI-FACTORY-02 v2` 7. `UI-AGENT-01 v2` 8. `UI-APPROVAL-01 v2` 9. `UI-DEPLOYMENT-02` as the recovery reference 10. global collection / state / action / focus patterns These screens establish the mental model for almost every later screen. --- # 11. UX freeze recommendations before architecture continues Treat the following as product-level UX constraints: ```text UX-001 User navigation does not mirror backend module decomposition. UX-002 The default home surface is work-first and board-dominant. UX-003 Owner-facing default lifecycle is Asked / In progress / Waiting / Done. UX-004 Every operational object exposes last / current / next / attention. UX-005 Waiting always explains itself. UX-006 Failure always tells a recovery story before exposing logs. UX-007 Relationship/provenance context survives drill-down. UX-008 Planning settings expose consequences before methodology labels. UX-009 Approval screens are decision briefs with impact and reversibility. UX-010 One primary action per view/section. UX-011 Every data view specifies loading / empty / error / populated states. UX-012 View state survives refresh/share through URL truth. UX-013 High-impact commands require live authoritative connectivity. UX-014 Keyboard/focus/accessibility behavior is part of the page contract. UX-015 Raw IDs, config keys, provider JSON, logs, and Kubernetes details are evidence layers, not the primary UX. ``` These are sufficiently cross-cutting that architecture and domain design should respect them rather than treating them as late visual polish. --- # 12. Recommended next sequence ```text Round 2 UX findings ↓ Revise canonical UI atlas around v2 mental model ↓ Create 8–10 high-value page mockups ↓ Run the five task-based usability tests ↓ Correct interaction model ↓ Freeze canonical page contracts ↓ Continue architecture/spec deepening ``` The highest-value change is not visual styling. It is **reducing the amount of AWP's internal ontology the user has to understand**.