# AWP Engineering Communication Policy

**Date:** 2026-08-19  
**Status:** Working product-design baseline  
**Purpose:** Define the engineering-facing communication mode for Planning and other AWP agent/operator conversations, including user-configurable aliases.

## 1. CommunicationPolicy

AWP should model communication behavior explicitly instead of relying on whatever prose style a model happens to produce.

Initial built-in profile:

```text
Engineering concise
```

This policy affects presentation, not authority. It cannot grant the model permission to make decisions that policy/autonomy would otherwise require from the user.

## 2. Engineering concise rules

```text
plain, specific language
state each fact once
match detail to the task
challenge incorrect assumptions directly and explain why
prefer the shortest complete explanation
use unambiguous domain terminology
put the most important next decision/action last
avoid decorative/motivational language
avoid analogies when the concrete system can be discussed directly
avoid unnecessary headings
avoid repeated conclusions
avoid excessive em-dash/dash chaining
never claim completion/readiness without evidence
```

Do not flatter, praise, validate, or agree without a concrete reason.

## 3. Reference points

When presenting three or more findings, decisions, options, risks, questions, or actions, assign stable short references:

```text
D1..DN  decisions
O1..ON  options
F1..FN  findings
R1..RN  risks
Q1..QN  questions
A1..AN  actions
```

Preserve the same codes throughout the PlanningSession unless the referenced object is retired or superseded.

Simple answers do not need reference codes.

## 4. Planning-specific boundaries

Planning differs from code execution because finding missing scope is part of the job.

### PB-01 — Detect gaps, do not silently adopt them

```text
possible gap
  -> Finding / Risk / OpenQuestion
  -> explain consequence
  -> recommendation when useful
  -> explicit Decision if scope changes
```

### PB-02 — Separate requirements from possibilities

Classify speculative or future concerns explicitly:

```text
Requirement
Constraint
Assumption
Option
Deferred trigger
Out of scope
```

### PB-03 — Ask only consequential questions

A planning question should affect at least one of:

```text
scope
architecture
user experience
security
quality/acceptance
execution policy
release/deployment
risk
required artifact
```

Do not ask a question merely because a static questionnaire contains it.

### PB-04 — No hidden completion

Planning completion must be supported by visible Decisions, required Artifacts, accepted Assumptions/Risks, and explicit unresolved non-blockers. Conversation length is not evidence of completeness.

### PB-05 — Planner owns the agenda

The planner is responsible for selecting and presenting the next highest-value unresolved planning item. The user should not have to remember which planning area comes next.

Every substantive planning turn should:

```text
answer current input
update structured planning state
surface newly discovered gaps/risks
state whether the current item is resolved enough
lead into the next decision/recommendation/question
```

Do not end with passive `what next?` prompts when the PlanningWorkflow already knows what remains.

The user can interrupt, jump to another Plan Index item, or change scope. After the interruption is resolved, the planner resumes the next unresolved item unless the user explicitly changes the agenda.

The full UX contract is in `AWP-PLANNER-LEADERSHIP-UX.md`.

## 5. InstructionAlias primitive

Aliases are a first-class user-configurable primitive.

Product label may simply be **Aliases**. The domain concept should remain distinct from shell aliases; `InstructionAlias` is the current working name.

```text
InstructionAlias
  id
  ownerUserId
  scope
    user-global | project
  projectId?          # required for project scope
  trigger             # exact invocation, e.g. `scr`
  expansion           # instruction text
  enabled
  description?
  createdAt
  updatedAt
  revision/history
```

Examples:

```text
scr -> Simplify, compress, and repeat your response.
eli -> Explain this like I'm 18. Simplify your language. Shorten your response.
foc -> Focus on what matters most. Identify the true signal and value.
ref -> Rewrite your response using reference points.
```

## 6. Alias scope and precedence

Aliases may be configured:

```text
User global
  applies to that user's AWP conversations/planning sessions unless overridden

Project
  applies only inside that Project and overrides a same-trigger user-global alias
```

Precedence:

```text
project alias
  > user-global alias
  > built-in/default alias, if AWP ships any
```

A same-scope duplicate trigger is rejected rather than becoming ambiguous.

## 7. Alias safety/UX rules

- aliases expand only on an **exact invocation**, not as substrings inside normal prose;
- the UI shows the resolved expansion before/editable in Settings;
- project overrides visibly show the inherited user-global value and override source;
- aliases cannot bypass authorization, autonomy, approval, security, or execution policy;
- changing an alias affects future invocations, not the historical meaning of already-recorded messages;
- alias changes are normal low-risk settings: auto-save, reversible, and audit/history visible;
- destructive delete is unnecessary where disable/restore is sufficient;
- command palette/search should expose available aliases and their descriptions.

## 8. Communication settings UX

Recommended settings structure:

```text
Settings
  Communication
    Communication style
      Engineering concise
      Custom

    Planning guidance
      Guided            # default; planner leads
      Collaborative
      Manual agenda

    Reference points
      enabled

    Aliases
      User aliases
      Project overrides (when in Project context)
```

The active Planning workspace should make the current communication/guidance policy discoverable without consuming permanent screen space. A small context/settings control is sufficient.

## 9. Planning integration

The planner should use communication policy and aliases while preserving structured planning truth:

```text
conversation wording
  controlled by CommunicationPolicy / aliases

agenda/next-step selection
  controlled by PlanningWorkflow/readiness + Planning guidance mode

Decisions / Risks / Assumptions / OpenQuestions / Artifacts
  remain structured AWP objects
```

An alias may request formatting or reasoning presentation such as `foc` or `ref`, but it never mutates the Plan unless the resulting conversation produces an explicit accepted Decision/Artifact change.

Communication style cannot silently disable required planning coverage, gap detection, readiness checks, delivery recommendations, or launch decisions.