Proposal: update specification — agents plan correct accepts plan ID or decision ID as positional argument #5558

Open
opened 2026-04-09 07:32:07 +00:00 by HAL9000 · 2 comments
Owner

Specification Update Proposal

Triggered by: Proactive scan (Cycle 5) — implementation analysis of src/cleveragents/cli/commands/plan.py
Classification: Implementation is BETTER than spec — update spec synopsis to match implementation

What Changed in the Implementation

The agents plan correct command was implemented to accept either a plan ID or a decision ID as the positional identifier argument. When a plan ID is given, the command auto-selects the root decision of that plan as the correction target. This is more user-friendly than requiring users to know the specific decision ID.

From the implementation (plan.py, correct_decision function):

# Resolve identifier: try as plan_id first, then fall back to
# decision_id for backward compatibility (issue #969).
target_decision_id: str
resolved_plan_id: str
_is_plan = False
try:
    service = container.plan_lifecycle_service()
    plan_obj = service.get_plan(identifier)
    if isinstance(plan_obj, Plan):
        _is_plan = True
except RNF:
    pass

if _is_plan:
    # identifier is a valid plan_id - auto-select root decision
    resolved_plan_id = identifier
    decisions = decision_svc.list_decisions(resolved_plan_id)
    root_decisions = [d for d in decisions if d.parent_decision_id is None]
    target_decision_id = root_decisions[0].decision_id
else:
    # Not a plan_id - treat as decision_id (backward compat)
    target_decision_id = identifier

What Spec Sections Need Updating

Section: Command Synopsis

Current spec:

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

Proposed update:

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

Section: ##### agents plan correct (detailed reference)

Current spec (positional argument description):

- `<DECISION_ID>`: The decision to correct.

Proposed update:

- `<PLAN_ID|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 (backward-compatible behavior).

Section: Examples for agents plan correct

Add an example showing plan ID usage:

agents plan correct --mode revert -g "Use FastAPI instead" PLAN-001
agents plan correct --mode revert -g "Use FastAPI instead" DEC-001
agents plan correct --mode append -g "Add caching layer" --dry-run DEC-002

Rationale

The spec synopsis <DECISION_ID> implies users must always know the specific decision ID. The implementation improved this by accepting a plan ID and auto-selecting the root decision — a more ergonomic UX. The spec should reflect this improvement so users know they can use either form. The implementation docstring already documents this: "The positional identifier can be either a plan ID or a decision ID."

Scope

  • Sections affected: Command synopsis, ##### agents plan correct argument description, examples
  • Change type: Clarify positional argument to accept plan ID or decision ID
  • Risk: Low — documentation clarification only, no behavioral change

Automated by CleverAgents Bot
Supervisor: Specification Updates | Agent: spec-updater

## Specification Update Proposal **Triggered by**: Proactive scan (Cycle 5) — implementation analysis of `src/cleveragents/cli/commands/plan.py` **Classification**: Implementation is BETTER than spec — update spec synopsis to match implementation ## What Changed in the Implementation The `agents plan correct` command was implemented to accept either a **plan ID** or a **decision ID** as the positional `identifier` argument. When a plan ID is given, the command auto-selects the root decision of that plan as the correction target. This is more user-friendly than requiring users to know the specific decision ID. From the implementation (`plan.py`, `correct_decision` function): ```python # Resolve identifier: try as plan_id first, then fall back to # decision_id for backward compatibility (issue #969). target_decision_id: str resolved_plan_id: str _is_plan = False try: service = container.plan_lifecycle_service() plan_obj = service.get_plan(identifier) if isinstance(plan_obj, Plan): _is_plan = True except RNF: pass if _is_plan: # identifier is a valid plan_id - auto-select root decision resolved_plan_id = identifier decisions = decision_svc.list_decisions(resolved_plan_id) root_decisions = [d for d in decisions if d.parent_decision_id is None] target_decision_id = root_decisions[0].decision_id else: # Not a plan_id - treat as decision_id (backward compat) target_decision_id = identifier ``` ## What Spec Sections Need Updating ### Section: Command Synopsis **Current spec**: ``` agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID> ``` **Proposed update**: ``` agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <PLAN_ID|DECISION_ID> ``` ### Section: `##### agents plan correct` (detailed reference) **Current spec** (positional argument description): ``` - `<DECISION_ID>`: The decision to correct. ``` **Proposed update**: ``` - `<PLAN_ID|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 (backward-compatible behavior). ``` ### Section: Examples for `agents plan correct` Add an example showing plan ID usage: ``` agents plan correct --mode revert -g "Use FastAPI instead" PLAN-001 agents plan correct --mode revert -g "Use FastAPI instead" DEC-001 agents plan correct --mode append -g "Add caching layer" --dry-run DEC-002 ``` ## Rationale The spec synopsis `<DECISION_ID>` implies users must always know the specific decision ID. The implementation improved this by accepting a plan ID and auto-selecting the root decision — a more ergonomic UX. The spec should reflect this improvement so users know they can use either form. The implementation docstring already documents this: "The positional *identifier* can be either a **plan ID** or a **decision ID**." ## Scope - **Sections affected**: Command synopsis, `##### agents plan correct` argument description, examples - **Change type**: Clarify positional argument to accept plan ID or decision ID - **Risk**: Low — documentation clarification only, no behavioral change --- **Automated by CleverAgents Bot** Supervisor: Specification Updates | Agent: spec-updater
HAL9000 added this to the v3.8.0 milestone 2026-04-09 07:33:28 +00:00
Author
Owner

Architecture Action Taken

PR #5612 has been created to implement this spec update:

  • Synopsis: <DECISION_ID><PLAN_ID|DECISION_ID>
  • Argument description: Expanded to explain both forms and when to use each
  • Decision tree section: Updated parameter documentation with full explanation
  • Plan errors output: Updated recovery suggestion examples

PR #5612 is awaiting human approval (Needs Feedback label applied).


Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

## Architecture Action Taken PR #5612 has been created to implement this spec update: - **Synopsis**: `<DECISION_ID>` → `<PLAN_ID|DECISION_ID>` - **Argument description**: Expanded to explain both forms and when to use each - **Decision tree section**: Updated parameter documentation with full explanation - **Plan errors output**: Updated recovery suggestion examples PR #5612 is awaiting human approval (`Needs Feedback` label applied). --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1
Author
Owner

Requesting verification so the linked PR #5595 can proceed. All spec locations now document <PLAN_ID|DECISION_ID>, and the duplicate PR #5612 has been closed. Can we get confirmation that this proposal is approved and ready to move out of State/Unverified / Needs Feedback?


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: implementation-worker

Requesting verification so the linked PR #5595 can proceed. All spec locations now document `<PLAN_ID|DECISION_ID>`, and the duplicate PR #5612 has been closed. Can we get confirmation that this proposal is approved and ready to move out of `State/Unverified` / `Needs Feedback`? --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: implementation-worker
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#5558
No description provided.