cleveragents-core/docs/reference/decision_correction.md

Decision Correction Reference

Overview

The correction subsystem allows operators to modify a plan's decision tree after execution by either reverting a subtree of decisions or appending new decisions as a child plan.

Correction Modes

Revert

Invalidates the targeted decision and every descendant reachable via BFS traversal. Associated artifacts are archived and affected child plans are rolled back.

          ┌─── D1 (target) ◄── revert starts here
          │       │
          │    ┌──┴──┐
          │    D2    D3          ← all invalidated
          │          │
          │          D4          ← also invalidated

Append

Preserves the original decision and spawns a new child plan rooted at the target node. The child plan carries the operator's guidance and produces additional decisions without disturbing the existing tree.

          D1 (target)
           │
        ┌──┴──────────┐
        D2 (original)  CP-new   ← child plan appended

Impact Analysis — BFS Algorithm

Impact analysis uses breadth-first search over the decision tree's adjacency list (parent → children mapping):

from collections import deque

def compute_affected_subtree(target_id, tree):
    affected = []
    queue = deque([target_id])
    while queue:
        node = queue.popleft()
        affected.append(node)
        queue.extend(tree.get(node, []))
    return affected

Risk Classification

Affected Count	Risk Level
≤ 3	low
4 – 10	medium
> 10	high

Dry-Run Output

A dry-run report contains:

• impact — Full CorrectionImpact with affected decisions, files, child plans, estimated cost, and risk level.
• decisions_to_invalidate — Decision IDs that would be marked invalid (revert mode only).
• child_plans_to_rollback — Child plans that would be rolled back.
• estimated_recompute_time_seconds — Wall-clock estimate.
• warnings — Human-readable cautions (e.g. high risk).

Status Lifecycle

PENDING → ANALYZING → EXECUTING → APPLIED
                                 → FAILED
         PENDING → CANCELLED
         ANALYZING → CANCELLED

Service API

Method	Description
request_correction()	Create a new correction request
analyze_impact()	BFS impact analysis on the decision tree
generate_dry_run_report()	Full report without side effects
execute_revert()	Invalidate subtree + archive artifacts
execute_append()	Spawn child plan preserving original decision
execute_correction()	Dispatch to revert or append based on mode
get_correction()	Retrieve a correction by ID
list_corrections()	List corrections (optional plan_id filter)
list_attempts()	List execution attempts for a correction
cancel_correction()	Cancel a pending/analyzing correction