cleveragents-core/docs/reference/decision_correction.md

Decision Correction

Corrections allow users to edit the decision tree of a plan and recompute affected subtrees. This is the primary mechanism for steering plan execution after decisions have already been made.

Correction Modes

Mode	Description
revert	Undo a specific decision and all of its descendants. The affected subtree is removed and will be recomputed with new guidance.
append	Add new guidance at a decision point without removing existing work. A new branch is created in the decision tree.

Revert

Revert mode is used when a decision was fundamentally wrong and needs to be undone. All child decisions that flowed from the reverted decision are also removed. The planner will re-evaluate using the supplied guidance.

Append

Append mode is used when the original decision was acceptable but additional direction is needed. It creates a supplementary branch rather than replacing the original.

Correction Lifecycle

Each correction moves through these statuses:

Status	Description
pending	Created but not yet analysed or executed
analyzing	Impact analysis is in progress
executing	The correction is being applied
applied	Successfully applied
failed	Execution encountered an error
cancelled	User cancelled before execution

CLI Commands

agents plan correct

Create and execute a correction on a decision.

agents plan correct --mode (revert|append) --guidance <TEXT> [--dry-run] [--yes|-y] [--plan <PLAN_ID>] <DECISION_ID>

Options:

Option	Short	Description
--mode	-m	Correction mode: revert or append (default: revert)
--guidance	-g	Guidance text for the correction (required)
--dry-run		Only analyse impact, do not execute
--yes	-y	Skip confirmation prompt
--plan	-p	Explicit plan ID (defaults to latest active plan)
--format	-f	Output format: rich, json, yaml, plain, table

Examples:

# Revert a decision with guidance
agents plan correct --mode revert -g "Use FastAPI instead of Flask" DEC-001

# Append guidance in dry-run mode
agents plan correct --mode append -g "Add caching layer" --dry-run DEC-002

# Skip confirmation
agents plan correct --mode revert -g "Fix the API endpoint" --yes DEC-003

agents plan diff --correction

Show the diff for a specific correction attempt.

agents plan diff --correction <CORRECTION_ATTEMPT_ID> <PLAN_ID>

Domain Models

CorrectionRequest

Field	Type	Description
correction_id	ULID	Unique identifier
plan_id	str	Plan being corrected
target_decision_id	str	Decision to target
mode	CorrectionMode	revert or append
guidance	str	User-supplied guidance
dry_run	bool	Analyse only
created_at	datetime	Creation timestamp
status	CorrectionStatus	Current lifecycle status

CorrectionImpact

Returned by --dry-run to preview what would change:

Field	Type	Description
affected_decisions	list[str]	Decision IDs that would be recomputed
affected_files	list[str]	File paths that would change
estimated_cost	float or None	Estimated cost in credits
risk_level	str	low, medium, or high

CorrectionResult

Returned after execution completes:

Field	Type	Description
correction_id	str	The correction that was executed
status	CorrectionStatus	Final status
new_decisions	list[str]	New decision IDs created
reverted_decisions	list[str]	Decision IDs removed
error_message	str or None	Error detail if failed
completed_at	datetime	Completion timestamp

CorrectionAttempt

Records each execution attempt:

Field	Type	Description
attempt_id	ULID	Unique attempt identifier
correction_id	str	Parent correction
started_at	datetime	Start time
completed_at	datetime or None	End time
success	bool	Whether it succeeded
details	dict	Arbitrary metadata