# error-analysis 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 prohibitions](#5-deliverables-and-prohibitions)
- [6. Code reviewed](#6-code-reviewed)

## 1. Purpose

`error-analysis` analyzes a reported error or incident to organize the symptom, trigger, root-cause candidate, reproduction gap, and validation path. It is not the phase that produces the fix itself or an implementation design.

## 2. okstra-run wizard flow

```mermaid
flowchart TD
    Start[/okstra-run/] --> Common[common task identity flow]
    Common --> Type[task-type = error-analysis]
    Type --> Worktree{active worktree exists?}
    Worktree -->|yes| RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
    Worktree -->|no| BaseRef[base-ref pick/text<br/>main recommended]
    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 --render-only]
```

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 Skill as okstra-run
    participant Wizard as wizard.py
    participant Run as prepare_task_bundle
    participant WT as worktree.py
    participant Art as artifacts

    Skill->>Wizard: task-type error-analysis selected
    Wizard-->>Skill: workers/base-ref/model args
    Skill->>Run: render-bundle --render-only
    Run->>Run: canonical brief preflight
    Run->>Run: validate brief/profile
    Run->>Run: resolve worker roster
    Run->>WT: provision/reuse worktree
    Run->>Art: analysis-profile.md includes common contract
    Run->>Art: task-manifest workflow next=validated report route
```

For canonical briefs, preflight runs before worker resolution, worktree provisioning, or report creation. A brief whose `reporter-confirmations` status is `pending` stops at this point; legacy briefs keep the compatibility path.

The final report records its next phase in `errorAnalysis.routing.nextTaskType`. A credible cause uses `implementation-option-selection`; continued investigation uses `error-analysis`. When report validation passes, Phase 7 projects `workflow.nextRecommendedPhase` from that one field (`scripts/okstra_ctl/next_phase.py::project`) — a `ready` pointer naming it. A report that leaves the field empty leaves the pointer `pending`; there is no static fallback that supplies a phase the report did not author.

## 4. lead execution flow

```mermaid
flowchart TD
    Intake[Phase 1 intake] --> Prompts[Phase 2 worker prompts]
    Prompts --> Team[Phase 3 TeamCreate]
    Team --> Dispatch[Phase 4/5 dispatch analysers]
    Dispatch --> Evidence[worker outputs<br/>root-cause hypotheses]
    Evidence --> Conv[Phase 5.5 convergence<br/>default maxRounds = 2]
    Conv --> Report[Phase 6 report-writer final report]
    Report --> Persist[Phase 7 persist + validate]
```

The workers analyze the symptom and evidence independently. In adversarial mode, even a finding reported by multiple workers enters the verification queue instead of receiving automatic consensus. Evidence-backed counter-evidence remains in the finding's round history, so later agreement cannot turn it into full consensus. The report-writer does not analyze during Phase 4/5 but writes the final report in Phase 6.

## 5. Deliverables and prohibitions

```mermaid
flowchart LR
    Symptom[Symptom] --> Hyp[Root-cause candidates]
    Hyp --> Gap[Reproduction gaps]
    Gap --> Validate[Validation path]
    Validate --> Next[Recommended next diagnostic/planning step]
    Hyp -. forbidden .-> Fix[Code fix in this run]
```

The expected final-report content is:

- evidence-backed cause analysis
- uncertainty boundary
- practical next diagnostic steps
- if there is blocking uncertainty, `## 1. Clarification Items`, usually `Blocks=next-phase`

For `error-analysis`, the structured `errorAnalysis` object is the source of truth for the verbatim symptom, reproduction status, `EA-NNN` cause candidates and their counter-evidence, the next diagnostic, and routing. Its shape is enforced by the final-report schema; `validators/validate-run.py::_validate_error_analysis_consistency` enforces the cross-field semantics. A route to `implementation-option-selection` needs a credible referenced leading cause and `begin-option-selection`. A route back to `error-analysis` needs the sharp next diagnostic and `continue-investigation`.

What is prohibited is source edit, refactor, fix attempt, implementation design artifact, and running build/migration/deploy. Deferring ambiguity that could be answered from code or logs to a user question is also a defect per the profile.

## 6. Code reviewed

- [`prompts/profiles/error-analysis.md`](../../prompts/profiles/error-analysis.md)
- [`templates/reports/error-analysis-input.template.md`](../../templates/reports/error-analysis-input.template.md)
- [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
- [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)