From 404d5013cface8a6a04305d46f8b1ea487332507 Mon Sep 17 00:00:00 2001
From: CleverThis <hal9000@cleverthis.com>
Date: Mon, 13 Apr 2026 07:27:24 +0000
Subject: [PATCH] docs(plan-cli): ensure plan tree ULID examples match full
 length

ISSUES CLOSED: #7674
---
 CHANGELOG.md               |  4 +++
 docs/reference/plan_cli.md | 52 +++++++++++++++++++++++++++++++-------
 2 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 35247aff4..1439f5ce1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -133,6 +133,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **Plan CLI documentation corrections** (PR #6571): Ensured plan explain and
+  plan tree examples use full 26-character ULIDs and documented `agents plan
+  correct` usage alongside `agents plan explain` for consistent guidance. (#7674)
+
 - **Validation Gate Empty-Run Guard** (#7508): Fixed `ApplyValidationSummary.all_required_passed`
   returning `True` when zero validations were run, silently bypassing the apply gate. The property
   now returns `False` when the validation result set is empty (`is_empty` is `True`), ensuring
diff --git a/docs/reference/plan_cli.md b/docs/reference/plan_cli.md
index dbabe08ad..bc106209e 100644
--- a/docs/reference/plan_cli.md
+++ b/docs/reference/plan_cli.md
@@ -20,6 +20,7 @@ The `agents plan` command group manages plans in the CleverAgents v3 plan lifecy
 | `agents plan diff`             | Show ChangeSet as unified diff          |
 | `agents plan artifacts`        | Show ChangeSet ID, sandbox refs, summary|
 | `agents plan explain`          | Explain a single decision               |
+| `agents plan correct`          | Correct a decision with new guidance    |
 | `agents plan tree`             | Display decision tree for a plan        |
 
 ## `agents plan use`
@@ -251,16 +252,16 @@ Alternatives considered are always included in the output.
 
 ```bash
 # Default rich output
-agents plan explain 01HXYZ1234567890ABCDEFGH
+agents plan explain 01ARZ3NDEKTSV4RRFFQ69G5FAV
 
 # JSON with full context
-agents plan explain 01HXYZ1234567890ABCDEFGH --format json --show-context
+agents plan explain 01ARZ3NDEKTSV4RRFFQ69G5FAV --format json --show-context
 
 # Show reasoning
-agents plan explain 01HXYZ1234567890ABCDEFGH --show-reasoning
+agents plan explain 01ARZ3NDEKTSV4RRFFQ69G5FAV --show-reasoning
 
 # YAML output with all details
-agents plan explain 01HXYZ1234567890ABCDEFGH --format yaml \
+agents plan explain 01ARZ3NDEKTSV4RRFFQ69G5FAV --format yaml \
   --show-context --show-reasoning
 ```
 
@@ -286,17 +287,50 @@ agents plan tree <PLAN_ID> [OPTIONS]
 
 ```bash
 # Default rich tree view
-agents plan tree 01HXYZ1234567890ABCDEFGH
+agents plan tree 01ARZ3NDEKTSV4RRFFQ69G5FAV
 
 # Table format
-agents plan tree 01HXYZ1234567890ABCDEFGH --format table
+agents plan tree 01ARZ3NDEKTSV4RRFFQ69G5FAV --format table
 
 # Include superseded decisions
-agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded
+agents plan tree 01ARZ3NDEKTSV4RRFFQ69G5FAV --show-superseded
 
 # Limit depth to 2 levels
-agents plan tree 01HXYZ1234567890ABCDEFGH --depth 2
+agents plan tree 01ARZ3NDEKTSV4RRFFQ69G5FAV --depth 2
 
 # JSON output for scripting
-agents plan tree 01HXYZ1234567890ABCDEFGH --format json
+agents plan tree 01ARZ3NDEKTSV4RRFFQ69G5FAV --format json
 ```
+## `agents plan correct`
+
+Correct a recorded decision by providing updated guidance.
+
+### Synopsis
+
+```bash
+agents plan correct <DECISION_ID> --mode <MODE> [OPTIONS]
+```
+
+`<MODE>` must be either `revert` (re-run from the corrected decision) or `append`
+(add guidance without replaying the tree).
+
+### Options
+
+| Flag                | Description                                                  |
+|---------------------|--------------------------------------------------------------|
+| `--mode MODE`       | Correction mode: `revert` recomputes from the decision; `append` records guidance only |
+| `--guidance`, `-g`  | Guidance text describing the corrected decision               |
+| `--dry-run`         | Preview the correction impact without applying it            |
+| `--yes`, `-y`       | Skip confirmation prompts when replaying corrections         |
+| `--format`, `-f`    | Output format: json, yaml, plain, table, rich                |
+
+### Examples
+
+```bash
+# Revert decision with updated guidance
+agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW9 --mode revert \
+  --guidance "Prioritize incident triage before refactors"
+
+# Append guidance without recomputing immediately
+agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW9 --mode append \
+  --guidance "Include database observability checks" --dry-run
-- 
2.52.0