---
name: ui-ux-application-planning
description: Interviews and audits product slices with codebase-grounded UI/UX and agent interaction planning until decisions are explicit. Use when planning TalentCo or multi-tenant flows, slice-by-slice current-vs-target gaps, holistic layout patterns, or how agent capabilities influence the Labs UI.
---

# UI/UX & application planning

## Principles

1. **Codebase first:** Before asking the user, read `labs/src/components/routes/*-routes.tsx`, `labs/src/components/app-sidebar.tsx`, relevant pages, `api/client-config.json` for the tenant, and backend APIs/models when flows depend on data.
2. **Relentless clarification:** Pursue branches until persona → journey → screen → states (including empty/error) are clear. Offer **constructive pushback** on weak or contradictory assumptions — do not default to agreement.
3. **Options every time:** Each planning question should include **recommended answers (A/B/C)** or a short option list.
4. **External docs once per session:** Ask for PRDs, Figma, Linear exports, gists, or constraints if not already provided.
5. **Record outcomes:** End with bullets — **decisions**, **non-goals**, **open questions**, and **next slice** if applicable.
6. **Pattern vocabulary:** Align with [docs/TALENTCO_UI_PATTERNS.md](../../../docs/TALENTCO_UI_PATTERNS.md) (artifact **A**, queue **B**, settings **C**, peek **D**). Same classes apply to other clients unless a tenant has documented exceptions.

## Phases: audit first, write when asked

- **“Look at” / explore a slice** means: **codebase-grounded audit**, **questions**, **options (A/B/C)**, and **discussion** in the thread — **not** automatically creating or editing files under `docs/` or elsewhere.
- **Write / persist** (e.g. `docs/planning/talentco-*-slice.md`, updates to `TALENTCO_UI_PATTERNS.md`) only when the user **explicitly** asks to add or update documentation after the audit.

## Workflow

1. Confirm **client/tenant** (e.g. `talentco`) and **personas** in scope for this pass.
2. Map **existing routes and surfaces** from Labs routes and nav; note **agent on/off** and **toolMappings** in `client-config.json` when relevant.
3. **Per slice** (or feature area): **goal → primary user → entry → happy path → edge cases → responsive**. Split **refinement** (shell/pattern) from **net-new functionality**.
4. **Agent / UI contract:** For each slice, note how the agent should influence UI (tools, navigation, diff/apply, gates) and where the agent must **not** appear (e.g. settings-class surfaces).
5. Cross-check with **backend reality** (Django Ninja routes, models) when the plan assumes data or APIs.
6. Close with a **decision list** and **open questions**. Optionally suggest **Linear-ready** titles — do not block on process.

## Optional passes

- **Holistic UX:** Periodically reconcile slices (navigation model, drawer stack, focus mode, agent panel) so individual slice plans do not drift.
- **Slice audit table:** For each slice — **what exists**, **target pattern (A/B/C/D)**, **gap**, **new capability vs UI migration**.

## Anti-patterns

- Inventing APIs or screens without checking the repo when planning is meant to be codebase-grounded.
- Stopping at feature titles without **screen-level** and **state-level** clarity.
- Treating the patterns doc as finished product spec — it is a **reference**; slices may expose new exceptions (document them).
- **Writing planning docs unprompted** after a “look at” / slice audit — wait for the user to request persistence.