# AWP Planning Module — Product Design Direction

**Date:** 2026-08-19  
**Status:** Working product-design baseline; approved direction, not yet an implementation-grade spec.  
**Purpose:** Preserve the Planning-module product/UX direction before page mockups or implementation freeze accidental assumptions.

## 1. Product purpose

AWP Planning must not be reduced to "chat with an AI and generate PLAN.md".

Its job is to know:

> what decisions this kind of software requires, which have been answered, which remain uncertain, which artifacts those answers affect, and whether enough is known to proceed safely.

Planning produces both human-readable artifacts and structured AWP state that Factory, CI, delivery and future planning revisions can consume.

## 2. Recommended software-creation pipeline

There is no single mandatory industry process. AWP should support a structured, iterative product-development pipeline whose stages can loop when new evidence changes earlier assumptions.

```text
1. Discovery
   problem / users / goals / constraints / existing system

2. Product Definition
   vision / scope / non-goals / requirements / success criteria

3. Experience Definition
   user roles / jobs-to-be-done / journeys / information architecture / workflows

4. Architecture
   domain model / boundaries / data / security / deployment / technology decisions

5. Specification
   domain specs / workflow specs / APIs/contracts / page specs / acceptance criteria

6. Design
   low-fidelity wireframes / interaction design / mockups / prototype / usability review

7. Delivery + Quality Planning
   increments / dependencies / work-management method
   quality strategy / test strategy / CI plan
   execution topology / release / deployment strategy

8. Implementation
   build / review / focused verification

9. Qualification
   required completion gates / release qualification / acceptance

10. Release / Operate / Learn
```

Stages 3–7 are intentionally iterative. Low-fidelity design may expose missing requirements. Quality planning may expose architecture or testability gaps. High-fidelity mockups should not become canonical before the relevant journeys, states, permissions, failure modes, actions and acceptance criteria are sufficiently understood.

## 3. Primitive model

A static template is not the primary primitive.

Recommended model:

```text
PlanningSession
  |
  +-- PlanningWorkflow
  |     +-- Stage
  |     +-- Question / Investigation
  |     +-- ArtifactRequirement
  |     +-- Decision
  |     +-- Gate
  |
  +-- Context
  +-- Decisions
  +-- Artifacts
  +-- OpenQuestions
  +-- Risks
  +-- Assumptions
```

A `PlanningSession` is the concrete planning effort for one Project or major Plan. A `PlanningWorkflow` defines ordered and conditional stages. A Stage is not merely a wizard page: it can contain conversational investigation, structured decisions, research, artifact production, validation and gates.

## 4. Planning Profiles, not rigid templates

The reusable preset should be a **Planning Profile**: a starting configuration over a PlanningWorkflow.

Profiles describe **what is being created**, not the software-delivery methodology.

Initial profile candidates:

```text
New software product
Existing-product feature
Existing-system modernization
Library / SDK / API
CLI / developer tool
Infrastructure / platform system
UI-heavy application
Small / quick project
Custom
```

Scrum, Kanban, Scrumban, predictive, incremental, continuous delivery and similar choices belong later inside Delivery Planning. They should not determine which discovery, UX, security, architecture or quality questions are required.

## 5. Planning participation modes

Planning has two user-participation modes. They change **which decisions become conversational agenda items**, not what AWP plans or which authorization/security rules apply.

```text
Simple
  user participates primarily in decisions only the user can legitimately own
  AWP resolves delegable expert decisions from evidence, project defaults and recommendations
  expert decisions remain visible and editable in the structured UI
  technical choices do not become chat questions merely because they exist

Expert
  planner actively discusses technical decisions as part of the normal interview
  architecture, quality, CI/CD, deployment, execution and similar decisions can be reviewed/refuted in depth
  recommendations still come first; the user is not forced to construct every answer from scratch
```

`PlanningParticipationMode = Simple | Expert` is a session/plan interaction policy. It does **not** weaken approval, security, credential, budget, production-launch, or autonomy boundaries.

### Decision participation classes

Each planning DecisionRequirement should resolve to a participation class rather than relying on topic names alone:

```text
OwnerRequired
  product direction
  user experience/taste where preference is authoritative
  scope/non-goals
  pricing/commercial policy
  business policy
  customer commitments
  budget/risk acceptance
  other choices where AWP cannot legitimately invent the owner's intent

DelegableExpert
  architecture implementation
  libraries/frameworks
  test/verification design
  CI/CD mechanics
  deployment technique
  execution topology/concurrency
  technical integration details
  other expert choices with a safe project-consistent recommendation

PolicyRequired
  explicit consent/authorization required by product/security policy
  provider OAuth/account authorization
  destructive or irreversible commitments
  production launch/approval where policy requires it
  capability/security boundary changes
```

Simple mode delegates `DelegableExpert` items. It never auto-decides `OwnerRequired`, and it never bypasses `PolicyRequired` gates.

### Escalation rule in Simple mode

A technical issue is promoted into the conversation only when the unresolved consequence crosses into a user-owned or policy-required decision.

Ask about the consequence, not implementation jargon.

```text
Bad
  Which cloud region strategy do you want?

Better
  Do you need customer data to remain in the EU from the first release?
```

A low-confidence technical decision that does not cross that boundary can still be resolved by AWP, but must remain visibly marked with confidence/basis and be easy to inspect or change.

## 6. Project technical defaults and first-plan setup

A Project should accumulate reusable expert defaults so users do not repeat the same technical interview on every Plan.

Working concept: `ProjectPlanningDefaults` (exact aggregate/schema belongs in the Planning spec).

Potential reusable dimensions include:

```text
architecture conventions
quality/testing philosophy
CI provider/runner policy
release/deployment defaults
connection/provider roles
work-management defaults
execution/concurrency policy ceilings
security/approval conventions
research/validation policy
```

Not every Plan decision is eligible to become a Project default. AWP must distinguish generalizable project policy from plan-specific choices.

Recommended first-project flow:

```text
first substantial Plan
  -> user may choose Expert mode
  -> planner reviews/recommends technical decisions deeply
  -> plan becomes ready
  -> AWP proposes only default-eligible decisions as Project defaults
  -> user explicitly accepts/reviews the default set

later Plans
  -> Simple may be the normal mode
  -> AWP inherits Project defaults
  -> only deltas/new technical facts are resolved
  -> user can inspect/change any expert decision
```

AWP does not silently mutate Project defaults because one Plan needed an exception. A materially useful new default is proposed explicitly as `Update project defaults`.

## 7. Conditional planning

The workflow branches from discovered product facts instead of forcing every project through the same questionnaire.

Examples:

```text
Does this have a user-facing UI?
  yes -> user journeys / IA / page inventory / interaction design / mockups / accessibility / CUJ verification

Does this execute untrusted code?
  yes -> threat model / isolation / credential boundary / failure containment / security verification

Does this store customer data?
  yes -> privacy / retention / backup / authorization / data lifecycle / recovery tests

Does this deploy to production infrastructure?
  yes -> release / environment / rollback / health / incident planning / deployment verification

Does this expose stable APIs/contracts?
  yes -> compatibility / contract testing requirements
```

Skipped stages are explicit and explainable rather than silently absent.

## 8. Conditional Research & Validation

User research/validation is a conditional planning requirement, not a mandatory universal stage.

Trigger it from uncertainty and consequence:

```text
new user-facing product + unvalidated user assumptions
  -> recommend user/problem validation

new interaction model / high-risk workflow
  -> recommend low-fi usability validation

existing product with analytics/support/research evidence
  -> inspect evidence first; research only the gaps

internal tool for one known team
  -> lightweight research or explicit skip may be sufficient

critical accessibility workflow
  -> include representative accessibility validation
```

Recommended placement:

```text
DEFINE
  Users / jobs
  Research needs          conditional

DESIGN
  Journeys
  Validation              conditional
  Information architecture
  Interaction design
```

Avoid a large research ontology initially. Planning can use `ResearchQuestion`, `ResearchRequest`, `ResearchFinding`, `Evidence`, `Artifact`, `Decision`, and `Risk`; `UserSegment` and `Journey` are candidates for first-class identity because they feed UX, quality and analytics.

Research recommendations follow the same progressive-disclosure rule as other expert planning. In Simple mode, AWP may establish the validation approach from project defaults/evidence unless it requires owner budget, external participant policy, risk acceptance, or another OwnerRequired/PolicyRequired choice.

## 9. Planning UX direction

The primary UX is **planner-led conversation + structured planning state**, not a large multi-page form.

Stable landmarks:

```text
DEFINE
DESIGN
SPECIFY
DELIVER
LAUNCH
```

The Plan Index exposes user-owned decisions prominently and lets expert planning build visibly alongside them.

In Simple mode, technical detail is progressively grouped rather than converted into chat questions:

```text
DESIGN
  ✓ Product experience
  ▸ Technical design             7 decisions · 1 changed

DELIVER
  ▸ Quality / CI / CD            9 decisions · project defaults
  ! Connection required          before production
```

Expanding the group shows each technical decision, source/default, confidence, consequence and `Review/Change` path.

In Expert mode, those same structured decisions can become active interview agenda items. Switching modes changes participation, not the underlying Plan state.

The agent asks because a required user decision is missing or Expert mode makes an expert decision conversational, not because a fixed questionnaire has another row.

## 10. Interaction principles

1. **Consequence-first questions.** Ask in product/human language before exposing methodology or implementation labels.
2. **One meaningful question at a time.** Batch only tightly related low-risk facts.
3. **Explain why on demand.** The user can inspect why a question matters and which decision/artifact depends on it.
4. **Structured decisions behind conversation.** Important answers become typed Decisions, constraints, assumptions or artifact changes instead of disappearing into chat history.
5. **Visible completeness.** Show complete, unresolved, blocked, deferred and intentionally skipped planning requirements.
6. **Uncertainty is first-class.** `unknown`, `assumed`, `needs research`, confidence and evidence state are preferable to false certainty.
7. **Revisitable decisions.** Earlier answers may be reopened; AWP shows downstream impact before applying the change.
8. **No giant wizard.** The system should feel like an intelligent planning partner with a visible state model, not a 70-field questionnaire.
9. **Artifacts remain editable.** Generated VISION/spec/decision/workflow artifacts are outputs of the structured plan, not opaque summaries.
10. **Planning has a readiness gate.** AWP distinguishes `enough to continue` from `everything imaginable has been discussed`.
11. **Recommendation first.** Expert areas are industry-grounded recommendations, not blank technical questionnaires.
12. **Recommendation provenance.** Material recommendations carry confidence, basis, consequences and what would cause AWP to recommend differently.
13. **Observed is not intended.** Existing projects distinguish observed current state, documented intended state, user desired state and AWP recommendation when they disagree.
14. **Planner owns next-step leadership.** The user may interrupt, but AWP resumes the highest-value unresolved item afterward.
15. **Mode does not hide state.** Simple reduces conversational burden, not visibility or editability.

## 11. Design and mockup rule

For UI-bearing products, the planning workflow should normally move through:

```text
user goals / roles
  -> journeys
  -> information architecture
  -> page inventory
  -> page behavior/spec
  -> low-fidelity wireframe
  -> validation when warranted
  -> visual mockup
  -> usability/consistency review
  -> approved canonical mockup
```

Low-fidelity wireframes can be produced before every detail is frozen because they are discovery tools. High-fidelity mockups should be approved only after the page's purpose, users, states, permissions, data, actions, failure modes and responsive/accessibility expectations are known and the low-fi interaction has received the required validation.

For AWP specifically, the existing ASCII atlas is low-fidelity input. The first generated Overview image is exploratory only until the Overview page spec is written and approved.

## 12. Planning outputs

A PlanningSession should be capable of producing or updating, depending on profile and project needs:

```text
VISION / product brief
scope + non-goals
user roles / jobs / journeys
research/validation plan and findings where required
requirements
risk / assumption register
architecture decisions / ADRs
architecture specs
security/threat decisions
page inventory
page specs
wireframes/mockups
API/domain/workflow specs
QualityStrategy
CIPlan / verification policy
delivery strategy
work-management policy
ExecutionPolicy
release/deployment strategy
quality/acceptance gates
implementation plan
open-decision register
ProjectPlanningDefaults candidates/changes
```

The user should always be able to see which planning inputs generated or constrained each output.

## 13. Quality and CI planning

Quality and CI are planning concerns, not an implementation afterthought.

AWP synthesizes a default recommendation from user journeys, architecture, risks, security requirements, repository structure, dependency graph, delivery model and Project defaults.

The detailed design is maintained in `AWP-QUALITY-CI-PLANNING-DESIGN.md`.

Core rule:

```text
Use the smallest test/check that can meaningfully falsify the implementation.
Broaden only when risk, blast radius, evidence failure, or a required gate justifies it.
Stop when sufficient evidence exists.
```

The rule must be enforced by AWP through change classification, affected-scope planning, evidence tracking and explicit broadening reasons. It is not merely advice placed in an agent prompt.

For user-facing products, critical user journeys are the default source for selective E2E coverage. Smoke tests remain narrow operability checks and do not substitute for feature-correctness evidence.

In Simple mode the Quality/CI plan builds visibly as delegated expert state and does not become a chat choice unless its consequences cross into OwnerRequired/PolicyRequired territory. In Expert mode the full recommendation/customization conversation is available.

## 14. Planning readiness

Planning completion is gate-based, not a percentage derived from question count.

Suggested states:

```text
Not started
Discovering
Needs decisions
Needs research
Ready for architecture
Ready for specification
Ready for design
Ready for quality/CI planning
Ready for delivery planning
Ready for implementation
Blocked
```

When gaps are deferred, readiness copy must state both what can happen now and what remains consequential later:

```text
Ready for specification
You can continue now.
Before production you still need:
  Cloudflare connection
  production approval policy
```

A project may move backward when a material decision invalidates downstream work. AWP shows the impact rather than silently rewriting everything.

## 15. Next phase

Planning product behavior is now defined enough to enter implementation-grade specification while preserving a low-fi research loop.

Next:

```text
1. Specify PlanningParticipationMode, decision participation/authority, ProjectPlanningDefaults, research/validation, readiness and mode switching.
2. Write interactive-planning and project-onboarding workflow specs.
3. Produce the low-fidelity Planning prototype from the canonical UX diagrams.
4. Run the first lean usability round, including both Simple and Expert journeys.
5. Fix evidence-backed usability defects before freezing high-fidelity Planning mockups.
```