From be11d3c269f2b50a89561ba5de9c0ad69aa7724e Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 07:42:23 +0000 Subject: [PATCH] docs(spec): clarify agents plan correct accepts plan ID or decision ID The implementation (plan.py correct_decision function) accepts either a plan ID or a decision ID as the positional identifier argument. When a plan ID is given, the root decision of that plan is auto-selected as the correction target. Updated documentation to reflect both identifier forms across the synopsis, argument description, recovery hints, correction guidance, and decision tree sections. ISSUES CLOSED: #5558 --- docs/specification.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 4accaad8b..a94da6383 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -339,7 +339,7 @@ The following standards are integrated into the architecture: agents plan tree [--show-superseded] <PLAN_ID> agents plan explain [--show-context] [--show-reasoning] <DECISION_ID> agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> - [--dry-run] [--yes|-y] <DECISION_ID> + [--dry-run] [--yes|-y] <PLAN_ID|DECISION_ID> agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) agents plan artifacts <PLAN_ID> agents plan prompt <PLAN_ID> <GUIDANCE> @@ -14912,14 +14912,14 @@ Including the raw model reasoning with `--show-reasoning`: ##### agents plan correct 
agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE>
-                   [--dry-run] [--yes|-y] <DECISION_ID>
+ [--dry-run] [--yes|-y] <PLAN_ID|DECISION_ID> **Purpose** Correct a decision either by reverting and re-executing or by appending a fix. **Arguments** -- ``: Decision ID. +- ``: The plan or decision to correct. When a plan ID is provided, the root decision of that plan is automatically selected as the correction target. When a decision ID is provided, that specific decision is targeted directly (backward-compatible behavior). - `--mode revert|append`: Correction mode. - `--guidance/-g TEXT`: Guidance text. - `--dry-run`: Show impact without executing. @@ -15857,7 +15857,7 @@ Show error decisions with recovery hints and retry history for a plan. │ → Check sandbox permissions and retry execution │ │ $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │ │ → Revert to Strategize phase to adjust the plan │ - │ $ agents plan correct --mode revert -g "..." <DECISION_ID> │ + │ $ agents plan correct --mode revert -g "..." <PLAN_ID|DECISION_ID> │ ╰────────────────────────────────────────────────────────────────────╯ ✓ OK @@ -15882,7 +15882,7 @@ Show error decisions with recovery hints and retry history for a plan. → Check sandbox permissions and retry execution $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J → Revert to Strategize phase to adjust the plan - $ agents plan correct --mode revert -g "..." + $ agents plan correct --mode revert -g "..." [OK] ``` @@ -15909,7 +15909,7 @@ Show error decisions with recovery hints and retry history for a plan. { "action": "revert", "message": "Revert to Strategize phase to adjust the plan", - "cli_command": "agents plan correct --mode revert -g \"...\" " + "cli_command": "agents plan correct --mode revert -g \"...\" " } ] } @@ -18677,11 +18677,11 @@ Plan: 01KH29QDEE6DZTXKWNKCV8VP0F All corrections use the same unified command: 

-agents plan correct <decision_id> --mode=<mode> --guidance "<corrected decision text>"
+agents plan correct <plan_id|decision_id> --mode=<mode> --guidance "<corrected decision text>"
**Parameters:** -* ``: The ULID of the decision to correct +* ``: When a plan ID is provided, the command auto-selects the plan's root decision. Supplying a decision ID targets that specific decision directly. * `--mode`: Either `revert` (rollback and re-run) or `append` (add fix at end) * `--guidance`: Free-form text specifying what the correct decision should be @@ -18713,6 +18713,10 @@ agents plan correct 01CRZ5QEHMVUX6TTHR81I7HCX --mode< # Add a missing invariant to the plan agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements" + +# Use a plan ID to correct its root decision +agents plan correct 01HXM8C2ZK4Q7C2B3F2R4VYV6J --mode=revert \ + --guidance "Re-run the plan with a revised authentication rollout before continuing child workstreams" **Note:** CLI commands should not require interactive input. The `--guidance` parameter provides the correction inline. @@ -19779,7 +19783,7 @@ agents action create --config ./actions/code-c agents plan use local/code-coverage local/api-service --invariant "Mock all network calls" # Correct an invariant decision (remove or replace via standard correction) -agents plan correct <DECISION_ID> --mode=revert \ +agents plan correct <PLAN_ID|DECISION_ID> --mode=revert \ --guidance "Remove this invariant - it does not apply to this module" @@ -28937,11 +28941,11 @@ agents plan explain <decision_id> # Shows: question, chosen option, alternatives, rationale, downstream impact # Correct via revert-and-replay -agents plan correct <decision_id> --mode=revert --guidance "<what the decision should be>" +agents plan correct <plan_id|decision_id> --mode=revert --guidance "<what the decision should be>" # Re-executes from that point with the new guidance # Correct via append (add fix at end) -agents plan correct <decision_id> --mode=append --guidance "<description of the fix>" +agents plan correct <plan_id|decision_id> --mode=append --guidance "<description of the fix>" # Creates a new child plan to fix the outcome without rewriting history # Compare old vs new after correction