# requirements-discovery process

## Index

- [1. Purpose](#1-purpose)
- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
- [3. prepare_task_bundle handling](#3-prepare_task_bundle-handling)
- [4. lead execution flow](#4-lead-execution-flow)
- [5. Deliverables and routing](#5-deliverables-and-routing)
- [6. Code reviewed](#6-code-reviewed)

## 1. Purpose

`requirements-discovery` classifies the request before implementation. It determines which of bugfix, feature, improvement, refactor, or ops it is, and chooses whether the next safe phase is `error-analysis` or `implementation-option-selection`. Going directly to planning or implementation is not valid for a new direction. Implementation can only start once a selected direction has been expanded into a separately approved `implementation-planning` report.

## 2. okstra-run wizard flow

```mermaid
flowchart TD
    Start[/okstra-run/] --> Check[ensure-installed / paths / check-project]
    Check --> Pick{new task or existing task?}
    Pick -->|new| Brief[brief path]
    Brief --> Suggest{brief frontmatter suggestions?}
    Suggest -->|yes| GroupPick[task-group pick]
    Suggest -->|no| GroupText[task-group text]
    GroupPick --> Id
    GroupText --> Id
    Id[task-id pick/text] --> Type[task-type = requirements-discovery]
    Pick -->|existing| Type
    Type --> Keep{existing brief?}
    Keep -->|keep| Base
    Keep -->|change/no brief| Brief
    Type --> Base{active task worktree?}
    Base -->|yes| RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
    Base -->|no| BaseRef[base-ref pick/text]
    BaseRef --> RoleCount
    RoleCount --> RoleModel[role-model provider/model per slot]
    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
    RoleAdd --> Extras[directive, related tasks, clarification]
    Extras --> Confirm
    Confirm --> Render[render-bundle]
```

Launch selection uses role slots and model refs only: current-session lead is this session (listed on the confirmation summary), then each static role's count in `min..max` (default **recommended**; the count step is skipped when `min == max`), then one `provider/model` per slot. Roles with `min = 0` stay closed unless the user opens them with role-add (default skip). Duplicate model refs in the same role are rejected. There is no provider roster multi-pick and no `Use defaults / Customize` fork. Dynamic verifiers are not chosen at launch. `--workers` is a CLI compatibility input only, not a launch picker.

## 3. prepare_task_bundle handling

```mermaid
sequenceDiagram
    participant W as wizard/render-bundle
    participant P as prepare_task_bundle
    participant Prof as requirements-discovery.md
    participant Git as worktree registry
    participant FS as task artifacts

    W->>P: task-type=requirements-discovery, brief, base-ref, workers
    P->>Prof: profile exists, Required workers parsed
    P->>P: verify installation, upsert project.json
    P->>P: resolve workers from profile + override
    P->>Git: create or reuse task worktree
    P->>P: expand _common-contract include
    P->>FS: write instruction-set and manifests
    P->>FS: render workflow currentPhase=requirements-discovery
    P-->>W: prepared lead prompt
```

There is no additional hard gate in the runtime for this phase alone. The important gates are: the profile file exists, the brief file exists, the worktree gate requiring base-ref to be resolvable at the first phase, and the gate requiring worker overrides to stay within the profile roster range.

## 4. lead execution flow

```mermaid
flowchart TD
    P1[Phase 1 intake<br/>manifest, brief, profile, run manifest, team-state] --> P2[Phase 2 prompts]
    P2 --> P3[Phase 3 TeamCreate]
    P3 --> P4[Phase 4/5 dispatch analysers<br/>claude/codex + optional antigravity]
    P4 --> C[Phase 5.5 convergence<br/>default maxRounds = 1]
    C --> R[Phase 6 report-writer authors final report]
    R --> P7[Phase 7 token usage, validate, persist]
```

`requirements-discovery` has a convergence default of 1 round. This exception is stated in both `render._build_convergence_block()` and `prompts/lead/okstra-lead-contract.md`.

## 5. Deliverables and routing

```mermaid
flowchart LR
    RD[requirements-discovery final report] --> Class[work-category classification]
    RD --> Missing[missing materials / clarification items]
    RD --> Domain[Domain Alignment<br/>terminology resolution]
    RD --> Route{next safe phase}
    Route --> EA[error-analysis]
    Route --> IOS[implementation-option-selection]
    Route -. invalid .-> Impl[implementation<br/>not allowed directly]
```

The final report emphasizes the following in particular.

- evidence-backed routing decision
- missing input and uncertainty boundary
- the next phase and safe resume guidance
- canonical term resolution for `terminology:*` brief items
- if there is blocking input, `Blocks=next-phase` in the `## 1. Clarification Items` unified table

Non-goals are source edit, plan authoring, build, and deployment.

## 6. Code reviewed

- [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
- [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
- [`prompts/profiles/requirements-discovery.md`](../../prompts/profiles/requirements-discovery.md)
- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)