# AWP Planning UX Decision Bundle — D1–D6 **Date:** 2026-08-19 **Status:** **PROPOSED FOR SINGLE USER APPROVAL** **Purpose:** Close the remaining Planning-workspace product/UX decisions as one coherent bundle before Planning specs and high-fidelity mockups. This document is intentionally decision-oriented. If approved, these decisions should be folded into the canonical Planning UX/spec documents without reopening them as separate generic design debates. ## UX constraints applied This bundle follows the active UX design rules: ```text one primary action per view/section progressive disclosure instead of control walls complete Empty / Loading / Error / Populated states immediate action feedback friction proportional to risk URL-restorable navigation/state auto-save and recovery for long planning sessions keyboard/focus accessibility no dead ends human, specific microcopy ``` The planner remains agent-led by default. The user may interrupt or override the agenda, but AWP is responsible for selecting and presenting the next unresolved planning item. ## Pre-decision C1 — Context rail **Recommendation: ACCEPT as baseline.** The right Context rail follows the current planning decision instead of becoming a second fixed navigation tree. Default content is limited to the most useful current context: ```text Current decision Recommendation / current position Why / evidence Impact Affected artifacts Open risk/question, when relevant Next / remaining ``` Rules: - `Plan Index` remains the primary navigation/structure surface. - The Context rail follows the current decision automatically. - A user may **Pin** a context item so it remains visible while discussing another subject. - Full collections such as all Decisions, Risks, Artifacts, Evidence, or Open Questions remain reachable through dedicated collection views/drawers/search, not permanent competing tabs in the default rail. - The rail must not exceed roughly 5–7 major information groups at one glance. Secondary detail drills down. - Context selection, pinned item, and active planning item are URL-restorable where practical. - On narrower screens the Context rail becomes a drawer/overlay rather than squeezing the center planning surface. ## Pre-decision C2 — Comparing credible alternatives **Recommendation: ACCEPT as baseline.** AWP should not dump generic pros/cons lists. When there are 2–4 credible alternatives, the planner presents one recommended option when evidence supports one, then compares alternatives only on dimensions that materially affect the current project. Normal shape: ```text Deployment strategy Recommended: Continuous delivery with production approval Why fast staging feedback production remains an explicit decision lower operational complexity than progressive delivery Alternative Main tradeoff Continuous deployment faster promotion; higher autonomy/risk Scheduled release simpler cadence; slower feedback Manual deployment lowest automation; highest operator toil [ Accept recommendation ] Compare in detail Propose another option ``` Rules: - Do not manufacture a recommendation when evidence is weak. Say `No strong recommendation` and present the smallest useful comparison. - Do not present more than four normal-path alternatives. Additional possibilities belong under `More options` or research. - Comparison dimensions come from actual consequences: reliability, complexity, cost, latency, portability, security, operability, migration impact, user experience, etc. - Do not repeat the same claim in prose and comparison rows. - `Accept recommendation` is the primary action. Comparison/customization remains secondary. - A rejected recommendation opens a focused conversation about that decision only. --- # D1 — Inferred Planning Profile ## Decision AWP **auto-applies an inferred Planning Profile and shows it visibly with `Change`**. It does not normally stop onboarding to ask the user to classify the project first. Example: ```text Planning profile Infrastructure / platform system inferred Based on Kubernetes execution requirement control-plane architecture external provider integrations [ Change ] ``` ## Behavior For an existing project, profile inference uses repository/project evidence first. For a new project, it uses the user's description and decisions already made during discovery. The Planning Profile is a workflow preset, not authoritative product taxonomy. AWP may infer additional conditional traits independently, for example: ```text has user-facing UI executes untrusted code stores customer data publishes a package requires production deployment has stable public API/contracts ``` Those traits add/remove planning requirements without forcing profile stacking. ## Confidence handling ```text high/normal confidence -> auto-apply -> visible `inferred` label + Change low confidence with materially different workflow consequences -> planner presents recommended profile + 1–2 alternatives -> user resolves the decision before affected downstream planning ``` Do not ask for confirmation merely because inference occurred. ## Changing profile Changing the profile must preview consequences before applying: ```text Adds Threat model Deployment planning Removes Package publication planning Keeps Architecture Quality & CI ``` A profile change never deletes accepted Decisions/Artifacts silently. Items that become non-required remain preserved and explicitly marked no-longer-required or intentionally retained. ## Why This reduces onboarding friction and avoids making users understand AWP's internal planning taxonomy before AWP understands their project. --- # D2 — `Enough to proceed` and uncertainty ## Decision Planning readiness is **gate-based**, not percentage-based and not based on exhausting every possible question. AWP distinguishes: ```text Ready Ready with accepted/deferred gaps Blocked ``` for the current planning stage and, separately, for final Plan launch. ## A planning item is blocking when At least one of these is true: ```text required Decision has no usable answer known contradiction affects downstream work required Artifact/evidence is missing unbounded assumption could materially invalidate the next stage security/trust requirement cannot be resolved or explicitly accepted a downstream required choice cannot be made without it ``` ## A planning item may be deferred when ```text its impact is bounded and understood it is not required by the current readiness gate there is a known lifecycle point by which it must be resolved its owner/status is explicit its downstream consequences are visible ``` Example: ```text Cloudflare production connection Status: Deferred Required by: Deployment preflight Blocks planning now: No ``` ## Deferral is structured `Decide later` creates explicit planning state, not a forgotten chat promise: ```text DecisionDeferral item reason blockingAt owner consequence revisit trigger/date if applicable ``` ## Planner stopping rule The planner stops interrogating a planning area when required decisions/artifacts for that readiness gate are satisfied and remaining uncertainty is explicitly accepted, bounded, deferred, or irrelevant. Then it automatically advances to the highest-value next area. ## Final Plan readiness requires ```text scope and non-goals sufficiently explicit required architecture/security decisions resolved required specs/acceptance expectations present for intended work QualityStrategy presented and accepted/customized Effective CI/CD/deployment setup presented and accepted/customized ExecutionPolicy resolved required approvals/gates known connection requirements satisfied or deferred to explicit later gates no unresolved blocker that makes execution unsafe/undefined remaining accepted risks/assumptions visible ``` Do not display arbitrary `87% complete`. Prefer: ```text Ready for delivery planning 2 non-blocking decisions deferred 1 connection required before production ``` --- # D3 — Recommendation/customization for Quality, CI, CD, and execution ## Decision AWP presents **one integrated Delivery & execution recommendation** rather than separately interrogating the user about testing, CI, release, deployment, concurrency, and accounts. The recommendation is composed of distinct underlying decisions, so accepting one surface does not collapse the domain model into one opaque setting. ## Normal recommendation ```text Delivery & execution recommendation Quality Critical user journeys for end-to-end correctness Focused regression/integration tests by affected behavior Narrowest meaningful verification first CI GitHub Actions on ARC-managed ephemeral K3s runners Affected checks during iteration Repository completion gate before merge Release / CD Incremental releases from main Continuous delivery: staging automatically, production by approval Promote the same immutable artifact between environments Deployment Kubernetes rolling deployment via Helm + Server-Side Apply Health gate + rollback to previous known-good release Execution Dependency-aware parallel work 3 normal coding lanes integration gates at identified dependency boundaries Connections GitHub / work connected Production Kubernetes connected [ Use recommended setup ] Review or customize ``` ## Existing project behavior If repository evidence shows an existing delivery setup, AWP distinguishes **Current** from **Recommended** when they differ. Example: ```text Current production deploys manually from a local script Recommended preserve script initially behind DeploymentProvider move production execution into trusted AWP delivery path Migration impact no application code change one project connection + deployment adapter required ``` AWP must not silently replace current delivery mechanics merely because a cleaner default exists. ## Customization `Review or customize` opens only the relevant dimensions: ```text Quality & testing CI Release/CD Deployment Execution Connections ``` The user can reject one section without reopening accepted sections. The planner recomputes downstream consequences after each material change. ## Recommendation rules - infer defaults from project evidence and planning context; - explain the minimum useful `why`; - present industry-standard practice when applicable, but do not label one context-specific choice as universally standard; - expose cost/runtime/risk/operational consequences where they can change the decision; - progressive delivery, giant test suites, complex DAGs, and extra infrastructure are never treated as inherently more mature; - use the least complex method that satisfies the project's actual constraints. --- # D4 — Connection/setup interruption without losing planning context ## Decision External setup is represented by `ConnectionRequirement` and handled **in context**, without breaking the PlanningSession or forcing premature account setup. Example: ```text Deployment Recommended: Cloudflare Workers Setup required Cloudflare connection is missing. Needed by: Deployment preflight [ Connect Cloudflare ] Set up later ``` ## Inline setup behavior When the user chooses `Connect`: ```text preserve exact PlanningSession + active Decision + draft state -> open focused connection flow -> authenticate provider -> choose identity/account if needed -> choose permitted resource(s) -> bind only required capability/resource scope to Project -> verify connection health -> return to exact planning context -> mark/re-evaluate ConnectionRequirement -> planner resumes the interrupted decision automatically ``` OAuth/external redirects must have a durable return target. Closing/cancelling the connection flow returns to planning without losing work. ## `Set up later` This does not mean ignore. AWP records: ```text status: deferred requiredBy: consequence: ``` The requirement remains visible in the Plan Index/Context rail and becomes blocking at the declared gate. ## Global and project scope ```text User Connections reusable authenticated identities multiple per provider allowed ProjectConnectionBinding explicit project permission to use one Connection narrow capability/resource scope ``` A Plan may select among project-permitted bindings. It cannot silently use another global connection. ## Setup UX requirements - show human-readable account/identity and target resource; - show requested capabilities before binding; - default to least privilege; - distinguish missing auth, missing permission, missing resource selection, re-auth required, provider outage, and unsupported adapter; - never expose raw tokens as normal configuration; - when provider setup is impossible because no adapter exists, surface an explicit implementation/integration requirement rather than pretending it is an account problem. --- # D5 — Final plan review and Start / Schedule / Park ## Decision Every Plan ends with one **Ready to launch** review. Planning never silently starts execution. The final review is a decision brief, not a dump of generated documents. ## Review content ```text Ready to launch Plan PlanRevision 7 Build AWP Planning module foundation 18 WorkItems Scope Non-goals: Delivery Quality strategy accepted CI GitHub Actions + ARC Release/CD continuous delivery Deployment staging auto / production approval Execution dependency-aware DAG max 3 coding lanes architecture + integration gates Connections GitHub ready Cloudflare production deferred until deployment preflight Approvals architecture deviation human production human Accepted gaps / risks 2 non-blocking Preflight PlanRevision ready repository ready cluster ready required-now connections ready When should this plan start? (•) Start now ( ) Schedule ( ) Park until later [ Confirm ] ``` Each summary links back to its source Decision/Artifact. The user does not reread the whole plan to understand launch consequences. ## Launch choices ### Start now AWP performs/revalidates preflight. If successful, creates the execution run. If a new blocker is found, launch intent is preserved and the plan becomes `Waiting / Needs attention` with one clear next action. ### Schedule Capture date/time/timezone. The scheduled launch is durable. AWP re-runs relevant preflight at activation time because credentials, branches, capacity, approvals, and environments may have changed. ### Park until later Parking is intentional ready state, not failure. Resuming later performs freshness/preflight checks before execution. ## Mutation safety - one primary `Confirm` action; - selection is reversible until execution starts; - schedule/reschedule/cancel/park use symmetrical effort; - high-impact launch receives clear immediate feedback and duplicate submission protection; - material changes after approval create/propose a new PlanRevision rather than silently changing the launched revision. --- # D6 — Planning workspace low-fidelity behavior/wireframe ## Decision Use a **three-area desktop Planning workspace** with progressive collapse on smaller screens. ```text +----------------------------------------------------------------------------------------------------------------+ | AWP / Project: AWP / Plan: Planning module Saved now Guided Needs 2 decisions | +---------------------------+------------------------------------------------------+-----------------------------+ | PLAN INDEX | CURRENT | CONTEXT | | What did I ask for? | What are we doing now? | Why / impact / what next? | | | | | | DEFINE | Delivery & execution recommendation | Current decision | | ✓ Intent | | Delivery setup | | ✓ Users | Quality | | | ✓ Scope | CUJ-first E2E + focused regression | Recommendation | | | | Continuous delivery | | DESIGN | CI | + production approval | | ✓ Journeys | GitHub Actions + ARC | | | ✓ Architecture | | Why | | ✓ Security | Deployment | Fast staging feedback | | | staging automatic / production approval | Lower prod risk | | SPECIFY | | | | ✓ Domain | Execution | Impact | | ● Pages | dependency-aware / 3 lanes | Creates production gate | | | | | | DELIVER | Connections | Affected artifacts | | ✓ Quality & testing | GitHub / work connected | CIPlan | | ● CI / CD | Cloudflare production set up later | DeploymentStrategy | | ○ Execution design | | | | | [ Use recommended setup ] | Open | | LAUNCH | Review or customize | Cloudflare connection | | ○ Readiness | | required by deploy preflight| | ○ Start/Schedule/Park | ---------------------------------------------------- | | | | Planner | Next | | Search plan... | "This resolves delivery defaults. Next I will verify | Resolve ExecutionPolicy | | | the execution topology and concurrency boundaries." | | +---------------------------+------------------------------------------------------+-----------------------------+ | Composer: Ask, correct, refute, or interrupt the plan... [ Send ] | +----------------------------------------------------------------------------------------------------------------+ ``` ## Area responsibilities ### Left — Plan Index Answers **what did I ask for / what exists in the plan?** ```text stable landmarks: DEFINE / DESIGN / SPECIFY / DELIVER / LAUNCH dynamic children from profile/project facts status + unresolved counts search/filter for large plans clicking an item restores that item's current context ``` It is navigation and durable planning memory, not a chat outline. ### Center — Current Answers **what is being worked on now?** Contains: ```text current question / recommendation / comparison / artifact review one primary action secondary customize/evidence controls focused planner explanation conversation timeline available but not visually dominant over current decision composer for correction/interruption ``` The center should not become an endless chat transcript where current work is lost above the fold. ### Right — Context Answers **why does this matter / what does it affect / what happens next?** Follows the current decision by default. Pinning is optional. Full global collections live elsewhere. ## Planner leadership in the layout Every resolved turn updates all three areas: ```text Plan Index status changes Current decision advances Context rail recomputes impact/next ``` The planner's response ends by leading into the next unresolved item. The user does not need a `Next` button in ordinary guided mode. ## Responsive behavior ```text wide desktop Plan Index + Current + Context visible medium width Plan Index remains visible or compact Context becomes toggleable drawer small/tablet/mobile Current is primary surface Plan Index and Context open as explicit drawers/sheets opening/closing returns focus correctly ``` Do not preserve three tiny squeezed columns on narrow screens. ## Complete states The workspace must define at least: ```text Empty no Plan yet -> one sentence + Create/Start planning action Loading preserve pane geometry with skeleton blocks; planning draft stays interactive when possible Error identify failed research/inspection/save operation + Retry without losing PlanningSession Populated normal workspace Stale/disconnected cached planning remains readable; safe draft edits may persist locally; approvals/launch/security mutations require authoritative connectivity ``` ## Interaction/accessibility requirements - one primary action per current decision; - 44x44 minimum practical interactive targets; - full keyboard navigation and visible focus; - dynamic planning status announcements use accessible live regions where appropriate; - active Plan Index item and URL identify current planning location; - plan search/filter state is restorable where useful; - async actions disable duplicate submission and show immediate state; - destructive/irreversible actions are spatially separated from progression actions; - planning drafts auto-save and recover; - realistic domain text is used in mockups so density/wrapping is tested honestly. --- # Single-approval consequence If the user approves **D1–D6** as a bundle: ```text 1. Mark D1–D6 accepted. 2. Fold them into AWP-PLANNING-UX-DESIGN.md and related delivery/connection docs. 3. Update AWP-DESIGN-PROGRESS.md to close Planning workspace product-level decisions. 4. Move next to implementation-grade Planning/domain/workflow architecture specs. 5. After the relevant page behavior specs exist, refine low-fi screens and create dark-mode high-fidelity mockups page by page. ``` Approval does not freeze visual styling. It freezes the Planning interaction model and behavior sufficiently to write specs without rediscovering the UX.