# Estimation Reference

CleverAgents supports optional pre-execution estimation through the
`estimation_actor` role. The actor produces a structured `EstimationReport`
that is persisted on plans and shown in plan status output.

## EstimationReport Schema

```json
{
  "cost_range_usd_min": 0.5,
  "cost_range_usd_max": 2.0,
  "token_estimate_input": 1200,
  "token_estimate_output": 600,
  "expected_steps": 4,
  "expected_child_plans": 1,
  "rollback_risk": 0.25,
  "confidence": 0.75,
  "estimated_duration_minutes": 18.0,
  "rationale": "Derived from plan size and constraints",
  "historical_basis": [],
  "actor_used": "local/estimator",
  "generated_at": "2026-03-12T10:00:00Z"
}
```

### Field Summary

- `cost_range_usd_min` / `cost_range_usd_max`: Estimated USD cost band.
- `token_estimate_input` / `token_estimate_output`: LLM token expectations.
- `expected_steps`, `expected_child_plans`: Work-size projection.
- `rollback_risk`: Rollback likelihood in `[0.0, 1.0]`.
- `confidence`: Model confidence in `[0.0, 1.0]`.
- `estimated_duration_minutes`: Duration estimate in minutes.
- `rationale`: Human-readable explanation of estimate.
- `historical_basis`: Optional prior plan IDs used as basis.
- `actor_used`: Namespaced actor identifier (`namespace/name`).
- `generated_at`: Timestamp of estimation generation.

### Validation Rules

- `cost_range_usd_max >= cost_range_usd_min`
- `rollback_risk` and `confidence` are bounded to `[0.0, 1.0]`
- all count/duration/token values are non-negative
- `actor_used` (when present) must be namespaced

## CLI Integration

Use `--no-estimate` to explicitly skip estimation:

```bash
agents plan use local/refactor my-project --no-estimate
```

When estimation is skipped, `estimation_skipped` is recorded with the reason.

## Persistence

Estimation data is stored on `v3_plans`:

- `estimation_report`: JSON-serialized `EstimationReport`
- `estimation_skipped_json`: JSON-serialized `EstimationSkipped`

## Runtime Behavior

Estimation runs during `plan use`:

1. create plan from action
2. invoke estimation actor if configured and not skipped
3. store either `estimation_report` or `estimation_skipped`
4. continue lifecycle (estimation is informational only)