cleveragents/cleveragents-core

Fork 3

UAT: `agents plan explain` rich output missing Alternatives Considered, Impact, and Correction hint panels #5920

New issue

Open

opened 2026-04-09 11:48:49 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 11:48:49 +00:00

Owner

Bug Report

Feature Area: Decision Tree Rendering
Command: agents plan explain <DECISION_ID>
Milestone: v3.2.0
Severity: Non-critical (Priority/Backlog)

What Was Tested

Code analysis of agents plan explain command implementation in src/cleveragents/cli/commands/plan.py (function explain_decision_cmd, lines 3841–3910) and _build_explain_dict() (lines 3803–3838) against the specification at docs/specification.md §agents plan explain (lines 14546–14610).

Expected Behavior (from spec §14546–14610)

The rich output of agents plan explain should render five distinct panels:

Decision panel — ID, Type, Question, Chosen, Confidence, Plan, Sequence ("2 of 5"), Created
Alternatives Considered panel — numbered list with (chosen) marker on the selected option
Impact panel — Downstream Decisions count, Downstream Child Plans count, Artifacts Produced count, Correction Impact level
Context Snapshot panel — context items and hot context hash (when --show-context)
Rationale panel — rationale text (when --show-reasoning)
Correction panel — the agents plan correct <DECISION_ID> --mode revert --guidance "..." command hint
Footer message: ✓ OK Decision explained

Spec example (Rich format):

╭─ Decision ─────────────────────────────────────╮
│ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9                 │
│ Type: strategy_choice                          │
│ Question: Which modules should be prioritized? │
│ Chosen: Auth and payments                      │
│ Confidence: 0.82                               │
│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J               │
│ Sequence: 2 of 5                               │
│ Created: 2026-02-08 12:58                      │
╰────────────────────────────────────────────────╯

╭─ Alternatives Considered ──────────────────────╮
│ 1. Auth and payments (chosen)                  │
│ 2. User module first (coverage 71%, med risk)  │
│ 3. All modules equally (spread thin)           │
╰────────────────────────────────────────────────╯

╭─ Impact ──────────────────────╮
│ Downstream Decisions: 3       │
│ Downstream Child Plans: 2     │
│ Artifacts Produced: 5         │
│ Correction Impact: medium     │
╰───────────────────────────────╯

╭─ Correction ──────────────────────────────────────────────╮
│ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9            │
│   --mode revert --guidance "Prioritize payments first..." │
╰───────────────────────────────────────────────────────────╯

✓ OK Decision explained

Actual Behavior

The current implementation renders a single flat table with all fields as key-value rows. It does not render:

Separate "Alternatives Considered" panel with numbered list and (chosen) marker
"Impact" panel (downstream decisions, child plans, artifacts, correction impact)
"Correction" hint panel with the correction command
Footer success message

Additionally, the sequence field is rendered as a plain integer (e.g., 2) instead of the spec-required "2 of 5" format (sequence number out of total decisions in the plan).

Code location: src/cleveragents/cli/commands/plan.py, lines 3896–3910 (rich/plain branch of explain_decision_cmd)

The _build_explain_dict() function (lines 3803–3838) also does not compute:

impact dict (downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact)
correction_hint string
sequence as "N of M" format

Steps to Reproduce

Create a plan with decisions via agents plan use <action> <project> and execute it
Get a decision ID from agents plan tree <PLAN_ID>
Run agents plan explain <DECISION_ID>
Observe: flat table with all fields, no separate panels for alternatives/impact/correction

Impact

Users cannot quickly see:

Which alternatives were considered and which was chosen (no numbered list with chosen marker)
How many downstream decisions/plans/artifacts this decision affects (no impact panel)
What correction command to run to change this decision (no correction hint)

The correction workflow is significantly harder to use without the correction hint panel.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Decision Tree Rendering **Command:** `agents plan explain <DECISION_ID>` **Milestone:** v3.2.0 **Severity:** Non-critical (Priority/Backlog) --- ## What Was Tested Code analysis of `agents plan explain` command implementation in `src/cleveragents/cli/commands/plan.py` (function `explain_decision_cmd`, lines 3841–3910) and `_build_explain_dict()` (lines 3803–3838) against the specification at `docs/specification.md` §agents plan explain (lines 14546–14610). --- ## Expected Behavior (from spec §14546–14610) The rich output of `agents plan explain` should render **five distinct panels**: 1. **Decision panel** — ID, Type, Question, Chosen, Confidence, Plan, Sequence ("2 of 5"), Created 2. **Alternatives Considered panel** — numbered list with `(chosen)` marker on the selected option 3. **Impact panel** — Downstream Decisions count, Downstream Child Plans count, Artifacts Produced count, Correction Impact level 4. **Context Snapshot panel** — context items and hot context hash (when `--show-context`) 5. **Rationale panel** — rationale text (when `--show-reasoning`) 6. **Correction panel** — the `agents plan correct <DECISION_ID> --mode revert --guidance "..."` command hint 7. **Footer message:** `✓ OK Decision explained` Spec example (Rich format): ``` ╭─ Decision ─────────────────────────────────────╮ │ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │ │ Type: strategy_choice │ │ Question: Which modules should be prioritized? │ │ Chosen: Auth and payments │ │ Confidence: 0.82 │ │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │ │ Sequence: 2 of 5 │ │ Created: 2026-02-08 12:58 │ ╰────────────────────────────────────────────────╯ ╭─ Alternatives Considered ──────────────────────╮ │ 1. Auth and payments (chosen) │ │ 2. User module first (coverage 71%, med risk) │ │ 3. All modules equally (spread thin) │ ╰────────────────────────────────────────────────╯ ╭─ Impact ──────────────────────╮ │ Downstream Decisions: 3 │ │ Downstream Child Plans: 2 │ │ Artifacts Produced: 5 │ │ Correction Impact: medium │ ╰───────────────────────────────╯ ╭─ Correction ──────────────────────────────────────────────╮ │ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │ │ --mode revert --guidance "Prioritize payments first..." │ ╰───────────────────────────────────────────────────────────╯ ✓ OK Decision explained ``` --- ## Actual Behavior The current implementation renders a **single flat table** with all fields as key-value rows. It does **not** render: - Separate "Alternatives Considered" panel with numbered list and `(chosen)` marker - "Impact" panel (downstream decisions, child plans, artifacts, correction impact) - "Correction" hint panel with the correction command - Footer success message Additionally, the `sequence` field is rendered as a plain integer (e.g., `2`) instead of the spec-required `"2 of 5"` format (sequence number out of total decisions in the plan). **Code location:** `src/cleveragents/cli/commands/plan.py`, lines 3896–3910 (rich/plain branch of `explain_decision_cmd`) The `_build_explain_dict()` function (lines 3803–3838) also does not compute: - `impact` dict (downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact) - `correction_hint` string - `sequence` as "N of M" format --- ## Steps to Reproduce 1. Create a plan with decisions via `agents plan use <action> <project>` and execute it 2. Get a decision ID from `agents plan tree <PLAN_ID>` 3. Run `agents plan explain <DECISION_ID>` 4. Observe: flat table with all fields, no separate panels for alternatives/impact/correction --- ## Impact Users cannot quickly see: - Which alternatives were considered and which was chosen (no numbered list with chosen marker) - How many downstream decisions/plans/artifacts this decision affects (no impact panel) - What correction command to run to change this decision (no correction hint) The correction workflow is significantly harder to use without the correction hint panel. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 11:51:53 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 12:16:38 +00:00

~~HAL9000 referenced this issue 2026-04-09 12:21:22 +00:00~~

[AUTO-UAT-POOL] UAT Testing Report (Cycle 1) #5750

HAL9000 added

and removed

labels

2026-04-09 12:23:14 +00:00

HAL9000 commented

2026-04-09 12:33:18 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 12:35:08 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 30) #5908

HAL9000 added the

Points

label

2026-04-09 12:52:44 +00:00

HAL9000 added a new dependency

2026-04-09 13:47:58 +00:00

#4958 EPIC: Decision Recording & Tree Visualization — Plan Decisions Persisted to DB