cleveragents/cleveragents-core

Fork 3

UAT: `agents plan explain` rich output uses wrong layout — missing spec-required panels #3156

New issue

Open

opened 2026-04-05 07:02:26 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 07:02:26 +00:00

Owner

Metadata

Branch: bugfix/plan-explain-rich-output-spec-compliance
Commit Message: fix(cli): replace table layout with spec-required panels in plan explain rich output
Milestone: v3.2.0
Parent Epic: #357

Bug Report

Feature Area: plan tree and plan explain CLI Commands (v3.2.0)

What was tested

Code analysis of src/cleveragents/cli/commands/plan.py:

Lines 3493–3562: explain_decision_cmd command
Lines 3455–3490: _build_explain_dict helper function
Lines 3546–3562: Rich output rendering

Spec Reference

docs/specification.md lines 14545–14800 (agents plan explain command specification)
docs/reference/plan_cli.md lines 225–260

Expected behavior (from spec)

The agents plan explain rich output must render the following panels:

"Decision" panel with: ID, Type, Question, Chosen, Confidence, Plan, Sequence ("N of M" format), Created
"Alternatives Considered" panel listing alternatives with (chosen) marker on the selected option
"Impact" panel with: Downstream Decisions, Downstream Child Plans, Artifacts Produced, Correction Impact
"Context Snapshot" panel (when --show-context is used)
"Rationale" panel (shown in the spec's rich output)
"Correction" panel with the correction command hint: agents plan correct <DECISION_ID> --mode revert --guidance "..."
A success message: ✓ OK Decision explained

Actual behavior (from code analysis)

The current implementation (explain_decision_cmd, lines 3546–3562) renders a single Table with Field/Value rows wrapped in a Panel:

table = Table(title="Decision Details", show_header=False, expand=False)
table.add_column("Field", style="bold")
table.add_column("Value")
for key, val in data.items():
    ...
    table.add_row(key, str(val))
console.print(Panel(table, expand=False))

This is a generic key-value dump, NOT the spec's structured panel layout. Specifically:

No "Alternatives Considered" panel — alternatives are shown as a raw JSON list in the table
No "Impact" panel — completely absent (no downstream decisions, child plans, artifacts, correction impact data)
No "Correction" panel — no correction command hint shown
No success message — ✓ OK Decision explained is never printed
Rationale hidden by default — spec shows rationale in rich output always, but implementation only shows it with --show-reasoning
Sequence format wrong — shows a number (e.g., 3) not "N of M" format (e.g., 3 of 7)

Code location

src/cleveragents/cli/commands/plan.py:

Lines 3546–3562: Rich output rendering — uses generic table instead of spec panels
Lines 3455–3490: _build_explain_dict — missing impact and correction_hint fields
Line 3474: "alternatives_considered": decision.alternatives_considered — raw list of strings, not structured

Steps to reproduce

Create a plan with decisions recorded
Run: agents plan explain <DECISION_ID>
Observe: A generic key-value table instead of the spec's structured panels; no alternatives panel, no impact panel, no correction hint

Impact

This directly blocks the v3.2.0 milestone acceptance criterion:

agents plan explain shows decision details including alternatives considered

Subtasks

Replace generic table rendering with spec-required panel layout
Add "Alternatives Considered" panel with (chosen) marker
Add "Impact" panel (requires downstream decision/child plan count from decision service)
Add "Correction" panel with correction command hint
Show rationale in rich output by default (not only with --show-reasoning)
Fix sequence format to "N of M"
Add ✓ OK Decision explained success message
Add Behave unit tests for the new panel rendering
Verify nox passes

Definition of Done

All panels render as specified in docs/specification.md lines 14560–14610
Alternatives Considered panel shows structured list with (chosen) marker
Impact panel shows downstream decisions, child plans, artifacts, correction impact
Correction panel shows the correction command hint
Success message is printed
Tests pass and coverage ≥ 97%
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `bugfix/plan-explain-rich-output-spec-compliance` - **Commit Message**: `fix(cli): replace table layout with spec-required panels in plan explain rich output` - **Milestone**: v3.2.0 - **Parent Epic**: #357 ## Bug Report **Feature Area**: plan tree and plan explain CLI Commands (v3.2.0) ### What was tested Code analysis of `src/cleveragents/cli/commands/plan.py`: - Lines 3493–3562: `explain_decision_cmd` command - Lines 3455–3490: `_build_explain_dict` helper function - Lines 3546–3562: Rich output rendering ### Spec Reference `docs/specification.md` lines 14545–14800 (`agents plan explain` command specification) `docs/reference/plan_cli.md` lines 225–260 ### Expected behavior (from spec) The `agents plan explain` rich output must render the following panels: 1. **"Decision" panel** with: ID, Type, Question, Chosen, Confidence, Plan, Sequence ("N of M" format), Created 2. **"Alternatives Considered" panel** listing alternatives with `(chosen)` marker on the selected option 3. **"Impact" panel** with: Downstream Decisions, Downstream Child Plans, Artifacts Produced, Correction Impact 4. **"Context Snapshot" panel** (when `--show-context` is used) 5. **"Rationale" panel** (shown in the spec's rich output) 6. **"Correction" panel** with the correction command hint: `agents plan correct <DECISION_ID> --mode revert --guidance "..."` 7. **A success message**: `✓ OK Decision explained` ### Actual behavior (from code analysis) The current implementation (`explain_decision_cmd`, lines 3546–3562) renders a single `Table` with Field/Value rows wrapped in a `Panel`: ```python table = Table(title="Decision Details", show_header=False, expand=False) table.add_column("Field", style="bold") table.add_column("Value") for key, val in data.items(): ... table.add_row(key, str(val)) console.print(Panel(table, expand=False)) ``` This is a generic key-value dump, NOT the spec's structured panel layout. Specifically: - **No "Alternatives Considered" panel** — alternatives are shown as a raw JSON list in the table - **No "Impact" panel** — completely absent (no downstream decisions, child plans, artifacts, correction impact data) - **No "Correction" panel** — no correction command hint shown - **No success message** — `✓ OK Decision explained` is never printed - **Rationale hidden by default** — spec shows rationale in rich output always, but implementation only shows it with `--show-reasoning` - **Sequence format wrong** — shows a number (e.g., `3`) not "N of M" format (e.g., `3 of 7`) ### Code location `src/cleveragents/cli/commands/plan.py`: - Lines 3546–3562: Rich output rendering — uses generic table instead of spec panels - Lines 3455–3490: `_build_explain_dict` — missing `impact` and `correction_hint` fields - Line 3474: `"alternatives_considered": decision.alternatives_considered` — raw list of strings, not structured ### Steps to reproduce 1. Create a plan with decisions recorded 2. Run: `agents plan explain <DECISION_ID>` 3. Observe: A generic key-value table instead of the spec's structured panels; no alternatives panel, no impact panel, no correction hint ### Impact This directly blocks the v3.2.0 milestone acceptance criterion: > `agents plan explain` shows decision details including alternatives considered ## Subtasks - [ ] Replace generic table rendering with spec-required panel layout - [ ] Add "Alternatives Considered" panel with `(chosen)` marker - [ ] Add "Impact" panel (requires downstream decision/child plan count from decision service) - [ ] Add "Correction" panel with correction command hint - [ ] Show rationale in rich output by default (not only with `--show-reasoning`) - [ ] Fix sequence format to "N of M" - [ ] Add `✓ OK Decision explained` success message - [ ] Add Behave unit tests for the new panel rendering - [ ] Verify `nox` passes ## Definition of Done - All panels render as specified in `docs/specification.md` lines 14560–14610 - Alternatives Considered panel shows structured list with `(chosen)` marker - Impact panel shows downstream decisions, child plans, artifacts, correction impact - Correction panel shows the correction command hint - Success message is printed - Tests pass and coverage ≥ 97% - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.2.0 milestone

2026-04-05 07:03:22 +00:00

freemo added a new dependency

2026-04-05 07:04:34 +00:00

#357 Epic: Decisions + Validations + Invariants (M3)

freemo referenced this issue

2026-04-05 07:06:25 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3124

freemo added the

MoSCoW

Must have

label

2026-04-05 07:08:03 +00:00

freemo commented

2026-04-05 07:10:22 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Critical — this directly blocks the v3.2.0 acceptance criterion: "agents plan explain shows decision details including alternatives considered"
Milestone: v3.2.0
MoSCoW: Must Have — the spec defines a specific panel layout for plan explain rich output; the current generic table rendering is a fundamental spec deviation that must be fixed for milestone completion
Parent Epic: #357 (Decisions + Validations + Invariants)

This issue overlaps with #3115 (sequence format and alternatives format) but is broader — it covers the entire rich output layout including missing Impact, Correction, and Rationale panels. Both issues should be addressed together. Dependency link to parent Epic already existed.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — this directly blocks the v3.2.0 acceptance criterion: "`agents plan explain` shows decision details including alternatives considered" - **Milestone**: v3.2.0 - **MoSCoW**: Must Have — the spec defines a specific panel layout for `plan explain` rich output; the current generic table rendering is a fundamental spec deviation that must be fixed for milestone completion - **Parent Epic**: #357 (Decisions + Validations + Invariants) This issue overlaps with #3115 (sequence format and alternatives format) but is broader — it covers the entire rich output layout including missing Impact, Correction, and Rationale panels. Both issues should be addressed together. Dependency link to parent Epic already existed. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 07:17:07 +00:00

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793

freemo referenced this issue

2026-04-05 09:01:27 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo referenced this issue

2026-04-05 09:04:55 +00:00

Task: Autonomous build progress report — 2026-04-05 #3075

freemo referenced this issue

2026-04-05 09:18:23 +00:00

[CA-AUTO] System Watchdog — Session Tracker — watchdog-1 — 2026-04-05 #3197