# Decision Domain Model

The decision subsystem records every choice point in a plan's lifecycle
as a **Decision** node in a persistent tree.  Decisions are created
during the Strategize and Execute phases and form the basis for
targeted correction and replay.

## Decision Types

| Type                     | Phase      | Description                              |
|--------------------------|------------|------------------------------------------|
| `prompt_definition`      | Strategize | Root decision — the plan prompt           |
| `invariant_enforced`     | Strategize | An invariant constraint was applied       |
| `strategy_choice`        | Strategize | High-level approach chosen                |
| `implementation_choice`  | Execute    | How to implement a specific task          |
| `resource_selection`     | Execute    | Which resources to read / modify          |
| `subplan_spawn`          | Strategize | Decision to create a child plan           |
| `subplan_parallel_spawn` | Strategize | Spawn a group of child plans in parallel  |
| `tool_invocation`        | Execute    | Which skill / tool to use                 |
| `error_recovery`         | Execute    | How to handle a failure                   |
| `validation_response`    | Execute    | Response to a validation failure          |
| `user_intervention`      | Any        | User-provided guidance / correction       |

## Decision Fields

### Identity

- **decision_id** — ULID, auto-generated
- **plan_id** — ULID of the parent plan (required)
- **parent_decision_id** — ULID of the parent decision, or `None` for the root
- **sequence_number** — monotonic order within the plan (0-indexed, never reused)

### Classification

- **decision_type** — one of the 11 `DecisionType` enum values

### Content

- **question** — what question was being answered (required, non-empty)
- **chosen_option** — the option that was selected (required, non-empty)
- **alternatives_considered** — list of other options evaluated
- **confidence_score** — float 0.0–1.0, or `None` if not applicable

### Context Snapshot

Every decision captures a `ContextSnapshot` for replay:

- **hot_context_hash** — cryptographic hash of the context window
- **hot_context_ref** — storage pointer to the full serialised context
- **relevant_resources** — list of `ResourceRef` entries (resource_id + optional path)
- **actor_state_ref** — LangGraph actor checkpoint reference

### Rationale

- **rationale** — human-readable explanation
- **actor_reasoning** — raw LLM reasoning trace, if available

### Downstream Impact

- **downstream_decision_ids** — ULIDs of decisions that depend on this one
- **downstream_plan_ids** — ULIDs of child plans spawned from this decision
- **artifacts_produced** — list of `ArtifactRef` (artifact_path + artifact_type)

### Timestamps

- **created_at** — UTC datetime, auto-set on creation

### Correction Metadata

- **is_correction** — boolean, True if this decision corrects another
- **corrects_decision_id** — ULID of the original decision
- **correction_reason** — why the correction was made
- **superseded_by** — ULID of the decision that replaced this one

## Tree Structure

Decisions form a tree via `parent_decision_id`:

```
prompt_definition (root, parent=None)
├── invariant_enforced
├── strategy_choice
│   ├── implementation_choice
│   │   ├── resource_selection
│   │   └── tool_invocation
│   └── subplan_spawn
└── strategy_choice
```

The `prompt_definition` type is always the root and must have
`parent_decision_id = None`.  This is enforced by a model validator.

## Correction Lifecycle

Corrections never mutate existing decisions.  Instead:

1. A new `Decision` is created with `is_correction=True` and
   `corrects_decision_id` pointing to the original.
2. The original decision has its `superseded_by` field set to the
   new decision's ID.
3. All downstream decisions of the original are also superseded.

The **current tree** consists of all decisions where
`superseded_by IS NULL`.

## Validation Rules

- `plan_id` must be a valid ULID
- `parent_decision_id`, `corrects_decision_id`, `superseded_by` must
  be valid ULIDs or None
- `confidence_score` must be in [0.0, 1.0] or None
- `prompt_definition` decisions must have `parent_decision_id = None`
- If `is_correction` is True, `corrects_decision_id` must be set
- If `corrects_decision_id` is set, `is_correction` must be True

## Source

- Domain model: `src/cleveragents/domain/models/core/decision.py`
- Specification: `docs/specification.md` L18390–L18521
- ADR-007: Decision tree and correction
- ADR-033: Decision recording protocol
- ADR-034: Decision tree versioning and history