# Advisor Chat UI **Status:** Approved target-state behavior **First realization:** I3 Project Manager; I4 AWP Advisor **Vision:** `../../VISION-EXTENSIONS-2026-08-20.md` ## Page / Surface Job Let a project/product manager ask contextual questions about the current Project or AWP overall without leaving the work they are inspecting, while keeping scope, evidence, recommendations and canonical actions unambiguous. Primary questions: ```text What is happening? Why? What is taking too long? What should I pay attention to? What gaps exist in our Plans? What should we improve next? What evidence supports that recommendation? Can you help me turn this into a Decision/Plan improvement? ``` ## Target State One reusable `AdvisorShell` serves all advisor personas. ```text Project pages floating Ask Project Manager launcher -> right-side advisor drawer desktop -> full-height surface small screen Home/global visible Ask AWP affordance -> same AdvisorShell in system scope AdvisorShell persona + scope page-context chips thread selector/history conversation grounded source links proposal/action cards composer ``` Do not create separate chat products for Project Manager, AWP Advisor and future DBA/CI experts. ## Primary Users / Jobs - project/product manager: understand Project progress, bottlenecks, risks and cross-Plan gaps; - owner/operator: ask portfolio/system questions across authorized Projects; - expert user: switch to a specialized advisor such as CI/DBA later without losing AWP context/authority semantics. ## Entry / Exit Points Entry: ```text Project-scoped floating launcher Home `Ask AWP` Cmd/Ctrl+K `Ask Project Manager` / `Ask AWP` contextual Ask action from Project/Plan/Factory/CI/etc. saved AdvisorThread history ``` Exit: ```text Close/Back to unchanged source page Open cited Project/Plan/Task/Run/Decision/etc. Open Planning Open/draft canonical Decision or Task flow Switch persona/scope intentionally ``` Closing the drawer never discards the thread or an autosaved long draft where policy permits. ## Desktop Project Launcher Use a persistent bottom/end floating functional launcher: ```text [ Ask Project Manager ] ``` Requirements: - minimum 44x44 interaction target; - icon + short text when space permits; icon-only state requires accessible name/tooltip; - does not overlap the page's primary action, toast region or destructive controls; - remains visually secondary until invoked; - opening the advisor should not navigate away from the current page by default. A functional floating launcher is allowed; decorative floating chat-card styling is not. ## Home / Global Entry Home should expose system advice visibly near the command-center header rather than relying only on a floating bubble: ```text Search… ⌘K [ Ask AWP ] ``` The global advisor may also be reachable from the common launcher/command palette, but Home's first-class affordance reflects that portfolio/system help is a primary job. ## Advisor Drawer Layout ```text ┌─────────────────────────────────────┐ │ Project Manager │ │ Project: Press.Zone [Change] │ │ Context: FactoryRun 5j13mlx [×] │ ├─────────────────────────────────────┤ │ Thread title / history │ │ │ │ User │ │ Why is PG-11 taking so long? │ │ │ │ Advisor │ │ It has spent 3h 18m waiting on... │ │ [Task PG-11] [Review R-812] │ │ freshness: now │ │ │ │ Recommendation │ │ ... │ │ [Open Review] [Draft Decision] │ │ │ ├─────────────────────────────────────┤ │ Ask about this Project... [Send]│ └─────────────────────────────────────┘ ``` The active Project/page stays visible behind the drawer on wide screens. ## Persona / Scope Header Always visible near top. Examples: ```text Project Manager Project: Press.Zone ``` ```text AWP Advisor Scope: All accessible Projects ``` ```text CI Expert Project: AWP ``` Switching scope/persona is deliberate. If thread semantics would become ambiguous, start a new thread by default rather than silently rebinding old history. ## Page Context Show current contextual inputs as removable chips/summary: ```text FactoryRun 5j13mlx Task PG-11 Waiting 7d ``` User can: ```text Remove page context Add another visible primitive Change time range/filter Use Project-only context ``` Never auto-attach unsaved secrets/forms/raw credentials. ## Answer Structure Do not force every answer into a rigid template, but management answers should normally make these distinguishable: ```text Current state / finding Evidence/source Why it matters Recommendation Next action ``` Material source links are compact chips/rows with primitive type/title/status/freshness, not citation IDs that require decoding. For uncertain analysis say so explicitly rather than projecting confidence from prose style. ## Recommendations / Action Cards Advisor can propose actions such as: ```text Open affected Plans Open Review / CI / Incident Draft Decision Draft Plan improvements Open Planning Create investigation Task ``` Exactly one proposal/action is visually primary per response context when a clear recommendation exists. Other actions are secondary/tertiary. Selecting an action opens/previews the canonical workflow. Advisor response does not silently mutate state. ## Saved Threads Thread history is organized by persona/scope and recent activity. Desktop can use a lightweight history panel/popover/drawer section rather than permanently consuming horizontal space. Show: ```text thread title persona Project/system scope last activity last known context summary archived/pinned state if supported ``` Historical answers can show old source observation time. Current-state questions refresh sources rather than trusting old answer text. ## Starter Prompts Empty thread can show 3–5 context-specific starters, for example Project Manager: ```text What needs my attention? Which tasks are taking too long? What are the biggest planning gaps? Which Decisions may be stale? How can we improve the current Plans? ``` Home/AWP: ```text Which Project needs me most? Where are the biggest bottlenecks? Which Projects have recurring CI failures? How healthy is AWP overall? ``` These are suggestions, not a bento-card dashboard. One composer remains the main action. ## Complete States ### Empty One concise explanation + context-aware starter prompts + composer. No decorative illustration. ### Loading context Shell opens immediately; source/context region shows skeleton/`Loading project context…`. Composer may remain disabled only when sending would produce misleading ungrounded answer. ### Answer generating Send action locks against duplicate submit. Show in-thread progress/state; page behind remains usable. Streaming text is permitted with restrained live-region behavior. ### Populated Normal conversation with source/proposal links. ### Partial source failure Answer only from reliable available sources if useful; show `Could not read CI history` or equivalent and offer retry/open source. ### Provider/model error Preserve user message/draft, show actionable retry/switch route according to policy. No lost turn. ### Permission denied Do not reveal inaccessible entity names/snippets. Explain scope/access limitation and possible explicit scope/action. ### Stale Show `Sources last checked ...` / changed-source notice where material. Current actions revalidate. ### Disconnected Existing thread readable. Unsent draft retained. New consequential action/send can be disabled if authoritative grounding cannot be obtained. ## User Journeys ### J1 — Ask about current page ```text FactoryRun -> Ask Project Manager -> context chips show FactoryRun + Task -> ask why waiting -> grounded response with Task/Review sources -> open Review or close advisor -> FactoryRun page state preserved ``` ### J2 — Cross-Plan optimization ```text Project page -> Ask Project Manager -> “How can we improve our Plans?” -> Vision/Plans/Decisions analysis -> candidate improvements + evidence -> Draft Decision / Open Planning -> explicit canonical workflow ``` ### J3 — System portfolio advice ```text Home -> Ask AWP -> system scope explicit -> “Which Project needs me most?” -> ranked explanation with Project/Attention links -> open Project ``` ### J4 — Switch advisor persona ```text Project Manager thread -> persona selector -> choose CI Expert -> new thread confirmation/default -> Project scope retained explicitly -> CI-specific question ``` ### J5 — Resume later ```text open saved thread -> persona/scope/history restored -> old answer source time visible -> ask “what changed?” -> advisor refreshes current canonical sources -> compares with prior state ``` ## Data / Source of Truth `AdvisorPersona`, `AdvisorThread`, turns/context snapshots are canonical conversation state. Product facts come from the referenced AWP domains/read models. Advisor output does not override ProjectVision/Plan/Decision/Task/etc. ## Authorization / Mutation Safety Every source query uses current Principal and scope. Every proposal action invokes the existing application command/PolicyEvaluation/Approval path. Sending a turn uses idempotency protection. Duplicate Send cannot create duplicate turns. Stale target revisions invalidate proposal execution rather than applying to changed state. ## Responsive Behavior Wide: ```text page remains visible advisor 360–480px-equivalent contextual side surface based on final tokens ``` Do not freeze a magic width in implementation; use design tokens/responsive constraints. Medium: drawer may cover more page but preserves explicit Close. Small: full-height advisor route/sheet; source links and proposals stack; composer remains reachable above keyboard/safe area. ## Accessibility - semantic launcher/button/dialog/drawer; - visible focus; - focus enters advisor on open and returns to opener on close; - context chips have accessible remove labels; - message/source/action reading order is logical; - streaming updates announced politely, not token-by-token; - scope/persona never communicated by color alone; - touch targets meet 44x44 minimum. ## URL Truth The floating drawer open state need not be in the URL. A dedicated saved-thread route may use: ```text /advisors/threads/:threadId ``` Opening source primitives uses their stable route. Project page route/filter state remains intact when advisor opens/closes. ## Invariants From Day 1 - one reusable AdvisorShell; - persona/scope visible on every thread; - page context visible/removable; - Search and Advisor remain distinct surfaces; - factual management claims can be traced to product sources/freshness; - recommendations are not hidden mutations; - high-risk actions use canonical friction/Approval; - thread survives page navigation/provider failure; - no secret values in context or transcript UI. ## Increment Realization | Increment | UI realization | |---|---| | I1 | not shown; U1–U6 only avoid future overlay collisions. | | I2 | no generic advisor product surface required. | | I3 | Project Manager launcher/drawer, personas/threads, proposal actions. | | I4 | Home `Ask AWP`, SystemScoped advisor, richer cross-project analytics answers. | | I5–I8 | specialized expert personas gain domain-aware source/action blocks. | | I9 | organization/tenant persona management/history governance. | ## Current Implementation State Target spec only. ## Deferred Realization Voice input, proactive autonomous briefings, always-on advisor monitoring and multi-party shared chat are separate future product decisions. ## Temporary Dogfood Behavior Do not ship an ungrounded generic AI bubble before I3. If internal debugging needs a chat earlier, it is not exposed as the Project Manager product surface. ## Related Contracts / Decisions - `../domains/advisory-personas.md` - `../architecture/advisory-agents.md` - `../workflows/advisory-conversation.md` - `project.md`, `home-work-command-center.md`, `planning.md`, `decision-log.md`, `approval.md` - model/provider/credential semantics from Accounts/Connections - supplied UX-designer/researcher rules constrain state completeness, action hierarchy, progressive disclosure and validation. ## Visual Mockup Authority No advisor high-fi is approved yet. Before I3: Project launcher closed/open, grounded populated answer, proposal action, persona/scope switch, saved-thread resume, Empty/Loading/Error/Partial/Stale and small-screen states. Before I4: Home `Ask AWP` + cross-project answer state. ## Acceptance A project/product manager can ask a contextual Project/system question, understand exactly what scope and sources were used, verify the answer, and deliberately turn a recommendation into canonical AWP work/Decision without leaving the surrounding management context.