# Advisory Conversation Workflow

**Status:** Approved target-state baseline  
**First product realization:** I3 Project Manager; I4 AWP Advisor

## Target State

A user can ask a project/system management question from any relevant AWP page, receive a grounded answer with explicit scope/context/sources, and deliberately promote recommendations into canonical AWP actions without hidden mutations.

```text
open Advisor
  -> resolve persona + explicit scope
  -> capture visible page context
  -> user asks question
  -> authorize/query canonical AWP sources
  -> model reasons over grounded context
  -> answer + source refs + freshness
  -> optional proposal/action cards
  -> user accepts one
  -> canonical application command / PolicyEvaluation / Approval
  -> durable result + audit
```

## Entry Points

```text
Project-scoped floating launcher
Home / Ask AWP
Cmd/Ctrl+K command
saved AdvisorThread
contextual “Ask Project Manager” action from a primitive
```

Entry determines a default persona/scope, never an unreviewed privilege increase.

## Resolve Persona / Scope

Project route default:

```text
persona Project Manager
scope   ProjectScoped(projectId)
```

Home/global default:

```text
persona AWP Advisor
scope   SystemScoped(current Principal authorization)
```

The user can deliberately switch persona/scope if that persona allows it. The header updates before the next turn.

## Capture Page Context

Before sending, UI presents/remembers deterministic context such as:

```text
Project
route/page
selected primitive(s)
selected tab/filter/time range
explicitly attached objects
```

Context can be removed/changed. Unsaved secret/input fields are never automatically attached.

## Ask / Ground

### Step 1 — classify informational need

Examples:

```text
status/progress
bottleneck/slow work
plan gap
risk
cross-plan consistency
resource/capacity
Decision history
CI/delivery reliability
portfolio priority
```

Classification only guides queries/tools; it is not a new canonical user Decision.

### Step 2 — authorize and query

The application/query layer fetches current accessible primitives/read models. Every query respects current Principal and Advisor scope.

Partial source failure is recorded explicitly.

### Step 3 — reason

Model receives persona instructions + thread context + current context envelope + authorized source data. Hidden provider session memory cannot replace these inputs.

### Step 4 — answer

Answer should distinguish:

```text
current facts/status
inference/recommendation
uncertainty/freshness
material gaps
next suggested action
```

Material facts link to source primitives where practical.

## Example: Project Progress

```text
User: What is the current project progress?

Query:
  ProjectVision
  GOLIVE
  active Plans
  Task topology/status
  current Factory/Review/CI/Delivery states
  Needs Attention

Answer:
  outcome/readiness summary
  active work
  blocking/waiting items
  likely schedule/risk observations
  2–4 highest-value next management actions
  source links
```

Do not fabricate a completion percentage if underlying project readiness is gate-based.

## Example: Tasks Taking Too Long

```text
User: What tasks are taking too long?

Query:
  current/historical Task duration
  waiting duration/reasons
  dependencies
  FactoryRun/AgentRun attempts
  Review/CI waits
  Project delivery expectations where defined
```

Advisor distinguishes:

```text
long because expected/complex
long because blocked
long because repeated retries
long because resource/provider capacity
long relative to historical/project baseline
unknown because no baseline/evidence
```

No unsupported “late” label.

## Example: Planning Gap Analysis

```text
ProjectVision
  + active/ready/scheduled Plans
  + Decisions
  + Findings/Risks/Deferrals
  + GOLIVE
  + recent outcomes/incidents
 -> compare intended outcomes/constraints against planned work
 -> surface candidate gaps/overlap/stale assumptions
```

Advisor can offer:

```text
[Open affected Plans]
[Draft Decision]
[Open Planning]
[Draft Plan improvements]
```

## Proposal Promotion

Advisor proposals are not canonical mutations until explicitly accepted.

Pattern:

```text
recommendation
 -> user chooses action
 -> exact proposed target/action preview
 -> canonical command
 -> PolicyEvaluation / Approval if required
 -> success/failure
 -> thread links to created/updated primitive
```

If underlying state changed after the recommendation, action revalidates and may require refreshed proposal.

## Saved Threads / Resume

On resume:

```text
load thread + persona version + scope
show last message/time
refresh current relevant sources when user asks current-state question
mark old source-based claims historical if source changed
```

Thread title/history supports project-management continuity without pretending all old answers are still current.

## Persona Switch

If switching persona while keeping the thread would create ambiguous authority/scope/history, default to:

```text
Start new thread with <persona>
```

A deliberate `Continue this thread with...` may be supported only if every subsequent turn records new persona/version/scope clearly.

## Failure / Recovery

### Model/provider unavailable

- preserve draft and thread;
- show provider/model failure reason category where safe;
- retry/fallback according to persona model policy;
- do not display a fabricated partial answer as complete.

### Source query partial failure

- answer only from available sources if still useful;
- label missing source/freshness;
- offer retry/open affected source.

### Permission denied

- do not reveal hidden entity titles/snippets;
- explain that requested information is outside current authorized scope;
- offer explicit scope change only when user actually has that capability.

### Disconnect

- unsent draft can be preserved;
- completed thread remains readable;
- new authoritative action proposals cannot execute until live state/policy can be revalidated.

## User Journeys

### J1 — Page-context question

```text
FactoryRun page
 -> Ask Project Manager
 -> context shows current FactoryRun/Task
 -> “Why is this task waiting?”
 -> grounded answer + Review/Task links
 -> close drawer
 -> page context remains unchanged
```

### J2 — Cross-Plan management question

```text
Project page
 -> Ask Project Manager
 -> “What gaps exist across our Plans?”
 -> Vision/Plans/Decisions analysis
 -> candidate gaps + evidence
 -> Draft Decision / Open Planning
 -> accepted action uses canonical workflow
```

### J3 — Portfolio question

```text
Home
 -> Ask AWP
 -> system scope visible
 -> “Which Project needs me most?”
 -> cross-project Attention/readiness/health analysis
 -> source Project links
 -> user opens selected Project
```

### J4 — Custom expert

```text
Advisor switcher
 -> CI Expert
 -> explicit Project scope
 -> “Why is our CI getting slower?”
 -> current/historical CI evidence
 -> recommendation
 -> proposal goes through normal Decision/CI change workflow
```

## Invariants

- explicit persona/scope before each turn;
- current page context visible and removable;
- data access re-authorized server-side;
- source/freshness visible for consequential facts;
- recommendation does not mutate state;
- accepted advisor action uses existing command/policy/audit path;
- thread survives refresh/provider failure;
- historical answers are not silently reinterpreted as current state.

## Increment Realization

| Increment | Workflow realization |
|---|---|
| I1 | not active. |
| I2 | no generic advisor UX; underlying ProjectVision/query seams exist. |
| I3 | Project Manager workflow + stored personas/threads + proposal/Decision integration. |
| I4 | Home/AWP system-wide workflow and operational cross-project questions. |
| I5–I8 | expert personas gain sources/actions as domains activate. |
| I9 | organization/tenant scope/share governance. |

## Current Implementation State

Target workflow only.

## Deferred Realization

Scheduled autonomous advisor briefings/monitoring are separate future workflows; this spec covers interactive conversations.

## UI / Acceptance

A project/product manager can ask a management question without reconstructing IDs or navigating several dashboards, can see what scope/evidence the answer used, and can turn a recommendation into a protected canonical action without hidden side effects.