> **RETRACTED (2026-09).** This recommendation was reviewed and not adopted: the harness is the first user by design, and a full user-workflow document was judged premature before there is a product workflow to document (`report-research-synthesis.md`). The durable successor is
> [self-host.md Phase 5: Run Entry Point](../self-host.md#phase-5-run-entry-point), which carries the operator workflow as a roadmap phase with an exit gate. This document is retained only as a research artifact; do not follow it.

# User Workflow Documentation: Recommendation Report

## Executive Summary

**Recommendation: Write the user workflow document NOW, before implementation starts, and evolve it alongside implementation.**

This document should describe the expected user workflows for two scenarios:
1. Starting a project from scratch
2. Working on an existing project

It should be treated as a living design artifact that evolves with the implementation, not a post-hoc documentation exercise.

---

## Current Project State

The Autonomous Project Orchestrator is at the **design baseline** stage:

- **Normative specifications exist** for architecture, control plane, work graph, executors, validation, budgets, integration/conflicts, and experiments
- **No implementation code exists** yet (roadmap shows 32 implementation steps, starting with schema definitions)
- **No user-facing interface, CLI, or API has been designed**
- **Experiment procedure** (`docs/experiment.md`) describes evaluation methodology but not user interaction

---

## Why Write It Now (Before Implementation)

### 1. Clarifies the User-Facing Contract

The current documents are **internal system specifications** (state machines, event protocols, reducer logic). They answer "how does the system work internally?" but not "how does a user use this system?"

A user workflow document forces explicit decisions on:
- What the user provides as input (project kernel, task statement, budgets, policies)
- What the user observes during execution (progress, costs, conflicts, decisions)
- What the user receives as output (accepted artefacts, run outcome, evidence, audit trail)
- How the user intervenes (approval gates, replanning triggers, budget adjustments)

### 2. Drives Implementation Priorities

The roadmap (`docs/roadmap.md`) lists 32 implementation steps but doesn't prioritize by user value. A workflow document reveals:
- Which steps are on the critical path to a usable MVP
- Which deferred decisions (multi-model routing, human approval, observability) affect early adopters
- What minimal interface is needed for the first experimental runs

### 3. Exposes Design Gaps Early

Reading the normative documents reveals several user-facing questions with no current answer:

| Gap | Example Questions |
|-----|-------------------|
| **Input format** | How does a user express "project kernel" (purpose, constraints, risks)? YAML? Markdown? API? |
| **Policy configuration** | How are evidence policies, budget limits, risk classifications configured? |
| **Progress visibility** | What does the user see during a 1-hour run? Streaming logs? Dashboard? Periodic summaries? |
| **Intervention points** | Can a user pause, inspect, redirect, or cancel mid-run? How? |
| **Result consumption** | How does a user retrieve integrated code, test results, evidence packages? |
| **Failure diagnosis** | What artefacts help a user understand why a run ended in `INFEASIBLE` vs `BUDGET_EXHAUSTED`? |

### 4. Serves as a Communication Tool

- **For implementers**: Shared understanding of "done" for each feature
- **For reviewers**: Concrete scenarios to evaluate design decisions against
- **For future users**: Onboarding material that doesn't require reading 10+ normative specs
- **For experiment designers**: The `experiment.md` manifest requires a "project kernel" but doesn't specify its schema — a workflow doc would define this

### 5. Enables "Documentation-Driven Development"

Writing workflows first (like README-driven development) ensures:
- The CLI/API is designed for usability, not just internal convenience
- Error messages, progress indicators, and help text are considered early
- The experiment harness (`experiment.md`) and user CLI share consistent concepts

---

## Why Not Wait Until After Implementation

| Reason | Counterargument |
|--------|-----------------|
| "We don't know the final API yet" | The workflow describes *intent*, not implementation details. It can specify "user provides X" without dictating the exact CLI flags. |
| "It will become outdated" | Treat it as a living document. Version it alongside the normative specs. The `scripts/check-docs` framework already supports generated content — add workflow validation. |
| "Implementation reveals the real UX" | Implementation without a user model tends to optimize for internal elegance over user utility. The first user *is* the experiment harness — design for it. |
| "Specs are the documentation" | Normative specs are for implementers and auditors. Users need task-oriented guidance. These are different audiences. |

---

## Recommended Document Structure

Create `docs/user-workflows.md` (normative for harness, informative for users) with:

### Part 1: Scenario — Starting from Scratch
- User creates a project kernel (purpose, target users, outcomes, constraints, risks)
- User defines initial root node contract (goal, acceptance criteria, budget)
- User configures evidence policy, resource limits, model adapter
- User starts run; observes progress; receives outcome
- User retrieves accepted artefacts and evidence package

### Part 2: Scenario — Working on Existing Project
- User points to existing repository + base commit
- User defines task statement (what to change, acceptance criteria)
- User declares owned scopes, integration dependencies, hidden test mapping
- User starts run; handles conflicts/replans; retrieves integrated changes
- User merges or publishes results

### Part 3: Common Interaction Patterns
- Run monitoring (what's visible, refresh rates, aggregation)
- Intervention (pause, cancel, adjust budget, force replan, approve alternative)
- Result inspection (accepted tree, evidence, costs, audit trail)
- Failure diagnosis (termination reason, failed checks, conflict reports, stale results)

### Part 4: Interface Contracts (for harness compatibility)
- Project kernel schema (matches `experiment.md` manifest)
- Run configuration schema (budgets, limits, policies, model adapter)
- Progress event stream (for dashboard/logging)
- Result artefact schema (accepted tree, evidence package, run summary)

---

## Integration with Existing Documentation Process

1. **Add to `docs/tables/`** — Define workflow steps, user actions, and system responses as canonical tables
2. **Generate Markdown** — Use `scripts/tables.py --write` to render into `docs/user-workflows.md`
3. **Validate** — Extend `scripts/check-docs` to verify workflow completeness (every action type has a user-visible representation, every run outcome has a user-facing explanation)
4. **Version** — Track alongside `control-plane.md` and `experiment.md` versions

---

## Conclusion

The orchestrator's complexity (24 safety invariants, 3 independent lifecycle machines, 11 relation types, 13 conflict types, 8 run outcomes, 4 experimental arms) demands a clear user model **before** code is written. The experiment harness is the first "user" — its manifest requirements (`experiment.md:163-175`) are effectively the first user workflow.

**Write `docs/user-workflows.md` now. Treat it as a normative design input, not an informative output.**
