# AWP Advisory Personas + Advanced Search Product Design **Date:** 2026-08-20 **Status:** **TARGET PRODUCT DESIGN APPROVED AS OWNER DIRECTION; high-fi/usability validation later** **Vision authority:** [`../VISION-EXTENSIONS-2026-08-20.md`](../VISION-EXTENSIONS-2026-08-20.md) ## 1. Clarification: U1–U6 are not architecture The current batch: ```text U1 Project + minimal Plan/Task U2 FactoryRun active U3 Waiting/failure/retry + WIP safety U4 ChangeSet / Review U5 Ready to merge U6 Merged / completed ``` means **high-fidelity product/interaction design for the I1 user-visible states**. Architecture/domain/workflow target design is already the semantic authority. For each U-state we produce the polished page/state mockup that implementation must match, with realistic data and the relevant responsive/error/waiting behavior. ```text Architecture / domain / workflow specs already define what exists and how it behaves U1–U6 define what the first complete lifecycle looks/feels like in the UI Implementation follows only after explicit high-fi approval ``` The new advisor/search requirements are later target capabilities. They must be specified now so the final product does not drift, but they do **not** enlarge U1–U6 or I1. ## 2. UX Research / Designer Inputs Used The UX-researcher guidance prioritizes journey mapping, behavioral mental models, task completion, learnability, analytics/search-query evidence and concise Findings -> Evidence -> Impact -> Recommendation -> Effort synthesis. The UX-designer guidance requires complete Empty/Loading/Error/Populated states, one primary action, proportional friction, progressive disclosure, visible wayfinding, immediate async feedback, URL truth, 44x44 targets and a Cmd/Ctrl+K command palette for SaaS-like products. Applied consequence: do not create two unrelated floating AI widgets plus a separate hidden search experience. Use one consistent advisor shell with explicit persona/scope, and a separate command/search layer whose mental model is retrieval/navigation rather than conversation. ## 3. Product Mental Model AWP now has three distinct conversational/product surfaces: ```text Planning “Help me define and launch this Plan.” bounded Plan scope Advisor “Help me understand/manage this Project or AWP overall.” cross-Plan Project/system scope Execution Agent “Show me what this coding/review AgentRun is doing.” one AgentRun/Attempt execution scope ``` These must look related enough to feel like one product but must not be confused semantically. ## 4. Recommended Advisor UX ### 4.1 One advisor shell, different explicit scopes Do not create separate chat implementations for `Project Manager` and `AWP Advisor`. Use one reusable `AdvisorShell` with: ```text persona scope thread current page context conversation source/evidence links proposal/action cards ``` Built-in personas: ```text Project Manager scope: one Project by default AWP Advisor scope: all Projects/resources visible to current Principal ``` Future DBA/CI/Security/etc. use the same shell and persona contract. ### 4.2 Project-scoped launcher On a Project-scoped route, show one persistent functional launcher at the bottom/end edge: ```text [ Ask Project Manager ] ``` Wide/medium desktop: - compact floating action, not a decorative bubble; - opens a right-side drawer so the page remains visible; - minimum 44x44 interaction target; - never covers the page's primary action or bottom-right destructive controls; - remembered open/closed state is optional convenience, not URL authority. Small screens: - launcher remains reachable; - conversation becomes full-height sheet/page; - explicit Close/Back; focus returns to launcher. ### 4.3 Home / system-wide advisor On Home, global scope is more important than a floating affordance. Recommendation: ```text Home header / command-center region Search… ⌘K [ Ask AWP ] ``` `Ask AWP` opens the same AdvisorShell in system scope. A global floating launcher may still exist for consistency, but Home should expose `Ask AWP` visibly because portfolio/system questions are a primary job there. ### 4.4 Scope/persona visibility Advisor header must always show something equivalent to: ```text Project Manager Project: Press.Zone Using page context: Plan “Launch governance” [Change] [Remove page context] ``` or: ```text AWP Advisor Scope: All accessible Projects Page context: Home / 30d [Change] ``` Switching from Project to system scope is explicit. Current page never silently broadens the query boundary. ### 4.5 Context chips Every turn can include a deterministic `AdvisorContextEnvelope` surfaced as chips/summary: ```text Project current route/page selected primitive IDs selected tab filters / time range pinned comparison entities explicit attachments ``` Examples: ```text Press.Zone FactoryRun 5j13mlx Task PG-11 Waiting AWP Home All Projects Last 30 days Needs attention only ``` The user can remove page context while retaining Project/system scope. ### 4.6 Answers must be inspectable For project-management questions, important assertions should link back to canonical AWP objects: ```text “Task PG-11 has been waiting 3h 18m on Review changes.” [Open Task] [Open Review] “Two active Plans still assume the superseded deployment policy.” [Open Decision] [Open affected Plans] ``` Advisor response can contain concise reasoning, but exact progress/status claims should expose underlying primitive/evidence and freshness. ### 4.7 Recommendation vs mutation Advisor may recommend: ```text Draft Decision Draft Plan improvement Open Planning Create investigation Task Compare affected Plans Open CI evidence ``` The answer itself does not mutate canonical state. A visible action invokes the normal application command, policy and Approval path. This keeps advisor convenience without a hidden second authority system. ## 5. Advisor Persona Model Product/API name: `AdvisorPersona`. UI language can primarily say **Advisor** or **Expert** to avoid confusing these configurable AI roles with UX-research user personas. ### 5.1 Persona fields ```text id name role / purpose description scopePolicy instructionTemplate modelSelectionPolicy allowedQueryCapabilities allowedCommandCapabilities defaultContextPolicy threadRetentionPolicy status version createdBy / updatedBy ``` Optional later fields: ```text starter questions icon/avatar metadata display order organization sharing policy preferred response format ``` No raw secret/token lives on persona. ### 5.2 Scope classes Target minimum: ```text ProjectScoped SystemScoped ``` Future persona may support `ProjectOrSystem` where the user chooses explicitly. Plan-specific assistance remains Planning by default rather than creating a third overlapping advisor scope. ### 5.3 Built-in personas ```text Project Manager reads one Project comprehensively project/product management language project-wide recommendations AWP Advisor reads all authorized Projects + AWP health/capacity portfolio/system management language ``` Future examples: ```text DBA CI Expert Release Expert Security Advisor Architecture Advisor ``` Persona templates can be cloned/customized without changing the domain model. ## 6. Conversation / Memory Model ### 6.1 Durable threads `AdvisorThread` is durable and belongs to: ```text Principal AdvisorPersona version scope Project? when ProjectScoped created/current timestamps status ``` Turns store: ```text message/content resolved persona version context snapshot source/evidence refs used model/account/provider Attempt-like provenance where applicable proposal/action references timestamps ``` ### 6.2 No hidden project truth Thread history is useful conversation memory, not canonical Project memory. If the advisor/user establishes something material, promote it into: ```text ProjectVision revision Decision PlanRevision ProjectPlanningDefaults Policy / Configuration Task Finding/Risk/OpenQuestion ``` A thread can link to that primitive afterward. ### 6.3 Long-thread compaction Conversation compaction/summarization is allowed for model context, but: - raw historical turns remain retrievable under retention policy; - generated summary is marked as a derived thread artifact; - summary cannot replace source primitive truth; - important current answers refresh canonical state rather than relying solely on old summary. ## 7. Advisor Context / Query Architecture ### 7.1 Context is not authorization ```text Page context tells advisor what the user is looking at Principal + capability/policy determines what advisor can actually read/do ``` Never implement `projectId from route -> unrestricted database query`. ### 7.2 Query-first answers Each material management question should query current AWP read models through the application/query layer. Examples: ```text progress question -> ProjectVision + GOLIVE + Plans + Tasks + current delivery state slow task question -> Task durations/waits + dependencies + Factory/Agent/Review/CI state planning gap question -> ProjectVision + current Plans + Decisions + blockers/deferrals/risks/evidence portfolio question -> authorized cross-Project projections + freshness ``` Telemetry enriches analysis but cannot override canonical lifecycle state. ### 7.3 Advisor cannot bypass the control plane Any write-like tool is an existing AWP application command. Same IDs, Principal, PolicyEvaluation, Approval, idempotency and audit apply. ## 8. Search / Command Palette Recommendation ### 8.1 Use `cmdk` for interaction, not search authority `dip/cmdk` is a good fit for the React command palette because it is unstyled/composable, supports accessible combobox/menu behavior, keyboard dialog use, custom filtering, async loading and disabling internal filtering for externally ranked results. AWP should style it with Astryx/AWP tokens and preferably embed `Command` inside the chosen AWP/Astryx dialog primitive rather than allowing a second visual design system to emerge. ### 8.2 Backend reuse Current `@platform-modules/search` already exposes a generic grouped entity-search seam: ```text SearchProvider SearchRegistry searchEntities(...) entityType / id / rank / title / snippetHtml cursor/pagination ``` It sanitizes the text query before provider calls. Therefore AWP must test/reuse this package before writing its own generic search registry. ### 8.3 Do not preload the entire product into cmdk For static navigation/command entries, cmdk's local filtering is fine. For global AWP entity search, use the AWP/Platform backend and: ```text Command shouldFilter={false} ``` then render server-ranked results. This avoids making a DOM-resident command component the datastore for potentially thousands of Projects/Plans/Tasks/Runs. ### 8.4 Quick palette IA Empty query: ```text Recent Press.Zone AWP Plan: I0/I1 Commands New Plan Needs Your Attention Ask AWP Settings Go to Projects Agents CI ``` Typed query: ```text Projects Plans Tasks Runs / Agents Decisions Other matches [View all results for “translation”] ``` Project route may additionally prioritize current-Project matches without hiding global results. ### 8.5 Full Search page For large result sets/advanced filtering, palette exits to stable: ```text /search?q=translation&type=task,plan&project=... ``` Full page supports: ```text entity type Project status attention owner/agent where relevant time range sort pagination/cursor ``` A copied URL reproduces the search view. ### 8.6 Search vs Ask Advisor Do not overload Enter on every search query into AI. Mental model: ```text Search find/open exact object or command Advisor analyze/explain/recommend using product context ``` Optional command item can say: ```text Ask AWP about “why is PG-11 slow?” ``` but it is visually/action-wise distinct from entity results. ## 9. Complete UI States ### Advisor launcher/shell ```text Empty/new thread Loading context Answer streaming/loading Populated conversation Context source partially unavailable Permission denied for requested source Model/provider unavailable Stale source/freshness warning Disconnected Thread history loading/error Action proposal pending/succeeded/failed ``` The page behind the drawer remains usable where safe. ### Search palette ```text Empty query / recent commands Typing / debounce Loading remote results Populated grouped results No results Partial source failure Offline/stale cached navigation-only state Permission-filtered result set ``` No-results copy should offer a useful next action such as broaden scope, clear filters or open full Search—not decorative filler. ## 10. Accessibility / Keyboard Advisor: - launcher 44x44 minimum; - semantic button/dialog/drawer; - focus moves into shell and returns to launcher; - streaming updates use restrained polite announcements; - evidence/actions keyboard reachable; - no essential context communicated only through color/chips. Search: - `Cmd+K` / `Ctrl+K` opens globally; - visible shell affordance advertises shortcut; - arrows navigate, Enter selects, Escape closes/steps back predictably; - result counts/loading updates use polite live region; - nested command pages preserve clear Back/Escape mental model. ## 11. Privacy / Security ```text Advisor only sees resources current Principal can query cross-Project AWP scope is explicit page context cannot broaden resource access secret/token values never enter advisor context sensitive logs/diffs follow existing redaction/classification policy stored threads inherit retention/access policy custom persona instructions cannot grant capability search provider filters authorization before returning title/snippet ``` Search must not fetch broad unauthorized rows then filter only in the browser. ## 12. UX Research Plan Research methodology follows the supplied UX-researcher guidance: lean, representative, focused on task completion, time, errors, learnability and behavioral mental models. ### Research questions ```text RQ1 Can users explain the difference between Planning, Project Manager and AWP Advisor? RQ2 Can users always tell advisor scope? RQ3 Do visible page-context chips create trust or clutter? RQ4 Can users verify a management answer through source links? RQ5 Do users mistake advisor proposals for already-applied project changes? RQ6 Is the floating launcher discoverable without blocking primary work? RQ7 Can Cmd/Ctrl+K users find exact work faster than navigation? RQ8 Can non-keyboard users discover the same search capability? RQ9 Do users confuse Search with Ask Advisor? RQ10 Can users recover efficiently from zero/partial search results? ``` ### Representative tasks ```text Project Manager “Tell me the current project progress.” “Which tasks are taking too long and why?” “Find gaps across our active Plans.” “Recommend a planning change but do not apply it.” “Turn this recommendation into a draft Decision.” AWP Advisor “Which Project needs me most?” “Which Projects have recurring CI problems?” “Where is agent capacity being consumed?” Search find a Plan by partial title find a failed FactoryRun find a Decision using a keyword from its rationale open Needs Your Attention without mouse navigation recover from a query with zero results ``` ### Measures ```text task success time on task wrong-scope errors unintended-mutation attempts source-verification rate query reformulation rate zero-result rate search -> successful destination rate advisor launcher discovery rate Search-vs-Advisor confusion incidents learnability across second attempt ``` ### Synthesis For each issue: ```text Finding Evidence Impact Recommendation Effort ``` A first focused round can use roughly five representative participants; repeat after material changes. Design hypotheses are not promoted to findings without observed evidence. ## 13. Increment Realization ```text I1 NOT ACTIVE U1–U6 do not gain advisor/search product behavior visual layouts should merely avoid future overlay collisions I2 context/query seams can support Planning ProjectVision/Planning data makes later advisor useful I3 AdvisorPersona / AdvisorThread Project Manager advisor Search backend product seam Cmd/Ctrl+K palette proposal -> Decision/Approval integration I4 AWP Advisor across all accessible Projects richer Factory/Agent operational analytics/questions I5 CI Expert persona can use CI domain I6 Release/Deployment expert persona can use delivery domain I7 Cluster expert persona can use Cluster domain I8 Incident/Resolver advisory context deepens I9 organization persona sharing/governance + tenant-scoped search ``` ## 14. Design Decision Recommendation to adopt: ```text ONE reusable AdvisorShell Project pages default -> Project Manager Home/global default -> AWP Advisor explicit persona + scope selector contextual page chips persistent threads evidence-linked answers proposals, not hidden mutations ONE global Search/Command system Cmd/Ctrl+K + visible affordance cmdk UI @platform-modules/search reuse-first backend quick palette + URL-restorable full Search page ``` This keeps the project-manager mental model coherent, makes later expert personas cheap to add and prevents Search/AI/context/authorization from becoming duplicated subsystems.