# AWP Planning UX Design **Date:** 2026-08-19 **Status:** Working product-design baseline; C1/C2, D1-D6, UXR-01..07 direction, and Simple/Expert participation model accepted. **Purpose:** Define the human planning experience, plan-to-execution handoff, and UX invariants before high-fidelity page mockups. ## 1. Core UX model Planning is a **planner-led workspace**, not a chat transcript and not a form wizard. It continuously answers: ```text What did I ask for? -> Plan Index What are you doing now? -> Current workspace Why / what changed? -> Context What is left / next? -> planner-led agenda + remaining work ``` Desktop baseline: ```text +----------------------------------------------------------------------------------------------------------------+ | Project / Plan / PlanningSession Mode: Simple [Change] Saved now Ready for specification | +----------------------------+------------------------------------------------------+----------------------------+ | PLAN INDEX | CURRENT | CONTEXT | | What did I ask for? | What are we doing now? | Why / impact / next? | | | | | | DEFINE | Current: Pricing policy | Current decision | | ✓ Intent | | Pricing | | ✓ Users | Recommended: usage-based + minimum monthly floor | | | ● Pricing | Why: aligns cost with customer usage... | Recommendation | | | | usage-based + floor | | DESIGN | [ Accept recommendation ] | confidence: medium | | ✓ Product experience | Compare options | basis: business goals | | ▸ Technical design 7 | | | | Architecture inherited| -------------------------------------------------- | Consequences | | Data inferred | Technical plan updated | revenue predictability | | Security project | 3 expert decisions resolved from project defaults. | customer simplicity | | | They are visible at left; no action required. | | | SPECIFY | | What changes recommendation| | ○ Domain/API | Planner | enterprise billing need | | ○ Pages | Next I will finish product scope, then continue | | | | technical planning automatically. | Agenda | | DELIVER | | Now: Pricing | | ▸ Quality / CI / CD 9 | | Next: Scope boundary | | ! Connection required | | Later: Deployment setup | | | | | | LAUNCH | | | | ○ Readiness | | | | ○ Start/Schedule/Park | | | | Search plan... | | | +----------------------------+------------------------------------------------------+----------------------------+ | Composer: answer, correct, refute, inspect, or interrupt the plan... [ Send ] | +----------------------------------------------------------------------------------------------------------------+ ``` The center is conversational but current work remains above the fold. The Plan Index is durable planning memory. The Context rail is evidence/consequence context, not another navigation tree. ## 2. Simple and Expert participation modes Planning has two modes: ### Simple The user is actively asked only about decisions AWP cannot legitimately make for them, such as: ```text product direction scope/non-goals user experience/taste/preferences pricing/commercial policy business/customer policy budget/risk acceptance material customer commitments ``` AWP resolves delegable expert decisions from project defaults, repository evidence, industry-grounded recommendations and current planning context. Those technical decisions **build visibly in the UI**. They are not hidden and are not turned into chat questions by default. The user can expand, inspect, challenge or change any of them at any time. ### Expert The same Plan state exists, but technical decisions can become first-class conversational agenda items: ```text architecture security design quality/testing CI/CD release/deployment provider choices execution topology/concurrency technical tradeoffs ``` The planner still recommends first. Expert mode means deeper participation, not blank questionnaires. ### Mode invariant Mode changes conversational participation, not authority or safety. Simple mode cannot bypass: ```text explicit user-owned decisions OAuth/provider consent security/capability boundaries required approvals production launch rules destructive/irreversible actions budget/policy ceilings ``` A technical issue is escalated in Simple mode only when its consequence becomes user-owned or policy-required. Ask about the consequence rather than implementation jargon. ## 3. Mode selection and project defaults Normal entry behavior: ```text Planning mode: Simple You decide product/business choices. AWP handles technical planning visibly. [ Change to Expert ] ``` For a first substantial Plan with no established project technical defaults, Expert mode is presented as useful for users who want to establish them, but it is not required. Simple remains a complete path. At the end of an Expert Plan, AWP identifies which accepted expert decisions are reusable project defaults: ```text Project defaults 12 technical decisions can be reused on future Plans. 3 decisions were plan-specific and will not be saved as defaults. [ Use as project defaults ] Review ``` Project defaults are never silently rewritten because one Plan used an exception. A future Plan may propose `Update project defaults` separately. Switching Simple -> Expert surfaces unresolved/delegated expert decisions in the agenda. Switching Expert -> Simple preserves all work and delegates remaining technical decisions to AWP. ## 4. Plan Index behavior Stable top-level landmarks remain: ```text DEFINE DESIGN SPECIFY DELIVER LAUNCH ``` Children are generated from Planning Profile/project facts. ### Progressive disclosure — UXR-03 Default behavior: ```text current group expanded next unresolved group partially visible completed groups collapsed to summary blocked/deferred items surfaced even when parent is collapsed search/filter available for large plans ``` Do not let the Plan Index become a hundred-row tree. ### Simple-mode technical visibility Delegable expert decisions are grouped into readable summary nodes rather than flooding the rail: ```text DESIGN ✓ Product experience ▸ Technical design 7 decisions · 1 changed DELIVER ▸ Quality / CI / CD 9 decisions · project defaults ! Connection required before production ``` Expansion shows concise rows: ```text Architecture modular monolith project default Data PostgreSQL inferred · high confidence CI GitHub Actions + ARC inherited Deployment Cloudflare Workers inferred · medium confidence ``` Each row supports `Review/Change`; important changed/low-confidence/deferred states are text-labelled, not color-only. ### Status vocabulary ```text ready in progress needs user decision needs research blocked deferred expert decision resolved intentionally skipped stale / impacted ``` Readiness counts are preferred over fake percentages. ## 5. Conversation behavior and planner leadership Conversation is an interaction surface, not source of truth. Material content becomes structured state: ```text Decision Constraint Assumption OpenQuestion Risk ResearchRequest ResearchFinding ArtifactChange DecisionDeferral ConnectionRequirement ``` Every substantive planner turn: ```text resolve current input update structured state/artifacts surface new gaps/risks recompute readiness/dependencies select highest-value unresolved agenda item lead into it according to participation mode ``` ### Simple-mode turn rule ```text if next item is OwnerRequired -> recommend if useful -> ask one consequential user question if next item is DelegableExpert -> resolve from evidence/defaults/research -> record visibly -> optionally show concise "technical plan updated" notice -> do not ask user to choose in chat if next item is PolicyRequired -> surface the required consent/action at the correct lifecycle point ``` ### Expert-mode turn rule Delegable expert items may be discussed with recommendation, evidence, alternatives and focused user confirmation/refutation. Do not end with `what would you like to discuss next?` when PlanningWorkflow knows the agenda. ## 6. Visible agenda — UXR-02 The planner leads, but the agenda is legible: ```text Now Pricing policy Next Scope boundary Later Production connection ``` The user can reorder or park a non-blocking item without switching into a fully manual planning mode. The Context rail may show this agenda compactly. The Plan Index remains the authoritative structure. ## 7. Recommendation confidence and provenance — UXR-01 Every material recommendation carries structured metadata: ```text recommendation confidence: high | medium | low basis: repository evidence project default accepted decision industry-standard practice research evidence model inference material consequences what would make AWP recommend differently ``` Progressive disclosure controls density. The normal view may show only recommendation + confidence + one-line basis; Context expands the rest. Low confidence does not automatically mean a user question in Simple mode. It does mean visibility, and if the choice materially changes a user-owned/business/policy consequence it is promoted appropriately. ## 8. Context rail — approved C1, amended by research review The Context rail follows the current decision automatically. Default content: ```text Current decision Recommendation/current position Confidence + basis Why/evidence Consequences/impact Affected artifacts Open risk/question Agenda: now / next / later ``` Keep roughly 5-7 major groups visible per glance. Secondary detail drills down. A user may pin an item. Full collections remain accessible through dedicated collection views/search, not permanent competing tabs. For first-time/simple users, Context can start visually quiet and populate as evidence/impact exists; do not solve comprehension problems with mandatory onboarding tours before usability testing. ## 9. Alternatives — approved C2 When 2-4 credible alternatives exist, compare only material consequences. Recommend one only when evidence supports it. ```text Recommended: Continuous delivery with production approval confidence: high Alternative Main tradeoff Continuous deployment faster promotion; higher autonomy/risk Scheduled release simpler cadence; slower feedback Manual deployment lowest automation; highest toil ``` In Simple mode this detailed comparison appears when the user opens/changes an expert decision or when a user-owned consequence requires a choice. It is not injected into chat for every technical decision. ## 10. Inferred Planning Profile — approved D1 AWP auto-applies the inferred Planning Profile with visible `Change`. ```text high/normal confidence -> auto-apply low confidence + materially different planning workflow -> show recommendation + 1-2 alternatives ``` Profile changes preview added/removed/retained planning requirements and never silently delete accepted decisions/artifacts. Planning Profile and Planning participation mode are separate concepts. ## 11. Readiness and deferral — D2 + UXR-04 Readiness is gate-based: ```text Ready Ready with accepted/deferred gaps Blocked ``` Whenever gaps are deferred, copy must answer both: ```text Can I continue now? What remains consequential later? ``` Example: ```text Ready for specification You can continue now. Before production you still need: Cloudflare connection production approval policy ``` `Decide later` creates structured deferral with owner, reason, future blocking point, consequence and optional revisit trigger/date. The planner stops interrogating a section when current-gate requirements are satisfied and remaining uncertainty is accepted/bounded/deferred/irrelevant. ## 12. Existing-project truth model — UXR-06 Do not collapse conflicting evidence into one inferred truth. When relevant distinguish: ```text Observed current state Documented intended state User-stated desired state AWP recommendation ``` A conflict becomes a visible Finding/Decision. This matters especially for architecture, CI/CD, deployment and migration planning where repository mechanics may be historical rather than desired. ## 13. Integrated Delivery & execution recommendation — D3 + UXR-05 Quality, CI, release/CD, deployment, execution and connections remain one integrated planning area, but the UI uses compact summary rows rather than a mega-summary. ```text Delivery & execution Quality CUJ-first + affected verification resolved CI GitHub Actions + ARC inherited Delivery staging auto / production approval resolved Execution dependency-aware / 3 lanes inferred Connections 1 deferred attention ``` Only the active/reviewed section expands. ### Simple mode These rows build automatically from Project defaults/evidence. No `Use recommended setup` chat question is required for every Plan. The user sees them, can expand them and can change any item. If no Project default exists, AWP still resolves safe technical defaults and labels their basis/confidence. ### Expert mode The integrated recommendation becomes an explicit conversational review. The user may accept the whole recommendation or open only a section to refute/customize it. ## 14. Connection interruption UX — approved D4 Connections remain structured `ConnectionRequirement` state. When actual user authorization is required: ```text preserve PlanningSession + active Decision + draft -> focused auth/account/resource flow -> least-privilege ProjectConnectionBinding -> health verification -> return to exact planning context -> re-evaluate requirement -> planner resumes automatically ``` `Set up later` records future blocking gate and consequence. Connection flow analytics must distinguish: ```text started provider auth complete resource selected binding complete returned to PlanningSession interrupted decision resumed ``` Success means resuming the planning journey, not merely OAuth success. ## 15. Conditional Research & Validation — UXR-07 Research is conditional, not a universal top-level stage. Recommended placement: ```text DEFINE Users / jobs Research needs conditional DESIGN Journeys Validation conditional IA / interaction ``` The planner recommends lean validation when uncertainty/consequence justifies it. Example: ```text Validation recommendation Before visual polish, validate this workflow with representative users. Why new interaction model long multi-session workflow high automation/recommendation trust Suggested 5-user moderated low-fi usability round [ Use validation plan ] Review or skip with risk ``` In Simple mode, validation mechanics are delegable expert decisions unless budget, external participant policy, customer contact, risk acceptance or another owner/policy decision is required. Synthetic personas/model assumptions are never presented as research evidence. ## 16. Planning persistence and complete states Planning sessions auto-save and restore exact context. Safe drafts may survive temporary disconnection; high-impact approval/security/execution actions never silently queue offline. All planning surfaces implement: ```text Empty Loading Error Populated Stale/disconnected where applicable ``` Mode switching, sidebar expansion, active decision, pinned Context item, plan search/filter and relevant view state are URL-restorable where practical. ## 17. Plan is separate from execution Keep distinct: ```text PlanningSession Plan / PlanRevision ExecutionPolicy PlanLaunch ``` A material edit to an approved/started Plan produces/proposes a PlanRevision and impact analysis. Runtime work does not silently rewrite Plan truth. ## 18. Delivery planning versus execution design versus launch Do not conflate: ```text delivery/work method predictive / iterative / incremental / continuous Scrum / Kanban / Scrumban / Custom execution topology sequential / phase-wave parallel / dependency DAG / custom concurrency limits / synchronization / failure policy launch Start now / Schedule / Park ``` Project defaults may cover normal choices, but each Plan resolves an effective configuration. ## 19. Final Ready-to-launch review — approved D5 Every Plan ends with an explicit review and launch disposition. ```text Ready to launch Scope / important non-goals User-owned decisions Technical plan summary Quality / CI / CD / deployment ExecutionPolicy Connections / deferred setup Approvals Accepted risks/gaps Preflight When should this Plan start? ( ) Start now ( ) Schedule ( ) Park until later [ Confirm ] ``` Even in Simple mode, the technical setup remains visible in this final summary. The user is not required to re-approve each delegated technical decision, but can open any row before launch. `Start/Schedule/Park` remains explicit; Planning mode does not change this contract. ## 20. UX safety / designer invariants - exactly one primary action per section; - progressive disclosure limits normal-glance density to roughly 5-7 major data/action groups; - no technical "button soup" in Simple mode; - every async action gives immediate feedback and prevents duplicate mutation; - destructive/high-risk actions receive proportionate friction; - low-risk planning edits auto-save; - cancelling/parking/scheduling are reversible with comparable effort; - semantic controls, visible focus, logical tab order and usable targets are mandatory; - state never depends on color alone; - narrow screens convert Context/Plan Index to drawers rather than squeezing three columns; - realistic domain copy is used in prototypes; - current group/decision remains above the fold where practical; - raw provider JSON/logs/IDs remain evidence layers, not normal planning UX. ## 21. Research validation before high-fidelity freeze The Planning interaction remains an expert-designed hypothesis until tested. First low-fi study should test both Simple and Expert paths with representative behavioral segments. Core questions include: ```text Can users explain Simple vs Expert without confusing it with project type? Can Simple users see that technical decisions are being made without feeling forced to review them? Can they find/change a technical decision when they choose? Do Expert users understand when accepted decisions become Project defaults? Can users distinguish inherited/default/inferred/changed technical decisions? Does the Plan Index remain legible as expert state grows? Can users resume after interruption and know what is next? Can users understand readiness and Start/Schedule/Park? ``` Primary product promise remains: ```text Users should not need to ask what remains when structured Planning state already knows. ``` ## 22. Next phase Planning UX behavior is closed enough to write implementation-grade specs and build a low-fi validation prototype. Next: ```text 1. Planning/domain/workflow specs, including Simple/Expert, decision participation classes and Project defaults. 2. Low-fi interactive Planning prototype from this contract. 3. Lean usability round across Simple and Expert journeys. 4. Evidence-backed corrections. 5. Page behavior specs. 6. Dark-mode high-fidelity mockups page by page. ```