UAT: agents plan explain missing Impact section and Correction hint panel #3109

Open
opened 2026-04-05 06:18:40 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: fix/m3-plan-explain-impact-correction-panels
  • Commit Message: fix(cli): add Impact and Correction panels to agents plan explain output
  • Milestone: v3.2.0
  • Parent Epic: #357

Description

The agents plan explain command is missing two required output sections that are explicitly specified in docs/specification.md (lines 14545–14755), and has two additional structural mismatches with the spec.

Missing Sections

  1. Impact panel — should show: Downstream Decisions count, Downstream Child Plans count, Artifacts Produced count, Correction Impact level (low/medium/high)
  2. Correction hint panel — should show the agents plan correct <decision_id> --mode revert --guidance "..." command hint

Structural Mismatches

  1. Sequence format — spec shows "sequence": "2 of 5" (with total count) but implementation shows just the sequence number integer
  2. Alternatives format — spec shows alternatives as structured objects [{"index": 1, "description": "...", "chosen": true}, ...] but implementation shows plain strings

Root Cause

_build_explain_dict() (lines 3455–3490 of src/cleveragents/cli/commands/plan.py) does not include any impact data (downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact), no correction hint is generated or displayed, sequence is stored as a bare integer, and alternatives_considered is a plain list of strings rather than structured objects.

Spec Reference

docs/specification.md lines 14545–14755 (agents plan explain section):

  • Impact panel: lines 14582–14587
  • Correction panel: lines 14604–14607

Steps to Reproduce

  1. Record a decision with downstream_decision_ids and artifacts_produced
  2. Run agents plan explain <decision_id>
  3. Observe: no Impact panel, no Correction hint panel in the output; sequence is an integer; alternatives are plain strings

Expected vs Actual

Expected (per spec):

  • Rich output includes an "Impact" panel showing downstream_decisions, downstream_child_plans, artifacts_produced, and correction_impact
  • Rich output includes a "Correction" panel showing the agents plan correct command hint
  • JSON output has "sequence": "N of M" format
  • "alternatives" are structured objects with index/description/chosen fields

Actual:

  • No Impact panel rendered
  • No Correction hint panel rendered
  • Sequence is a bare integer
  • alternatives_considered is a plain list of strings

Code Location

src/cleveragents/cli/commands/plan.py lines 3455–3562 (_build_explain_dict, explain_decision_cmd)

Subtasks

  • Update _build_explain_dict() to include downstream_decisions, downstream_child_plans, artifacts_produced, and correction_impact fields from the decision record
  • Fix sequence field to output "N of M" string format (query total decision count for the plan)
  • Fix alternatives_considered to output structured objects [{"index": N, "description": "...", "chosen": bool}, ...]
  • Add Impact panel rendering in explain_decision_cmd Rich output (downstream decisions, child plans, artifacts produced, correction impact level)
  • Add Correction hint panel rendering in explain_decision_cmd Rich output (showing agents plan correct <decision_id> --mode revert --guidance "...")
  • Tests (Behave): Add/update scenarios in features/ covering Impact panel fields in JSON output
  • Tests (Behave): Add/update scenarios covering Correction hint panel in Rich output
  • Tests (Behave): Add/update scenarios covering "N of M" sequence format
  • Tests (Behave): Add/update scenarios covering structured alternatives objects
  • Tests (Robot): Add/update integration test for agents plan explain verifying Impact and Correction panels render correctly
  • Verify coverage >= 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • agents plan explain <decision_id> renders an Impact panel showing downstream_decisions, downstream_child_plans, artifacts_produced, and correction_impact in both Rich and JSON output modes.
  • agents plan explain <decision_id> renders a Correction panel showing the agents plan correct command hint.
  • JSON output sequence field is in "N of M" string format.
  • JSON output alternatives field contains structured objects with index, description, and chosen fields.
  • Output matches the spec at docs/specification.md lines 14545–14755.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • All nox stages pass.
  • Coverage >= 97%.

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

## Metadata - **Branch**: `fix/m3-plan-explain-impact-correction-panels` - **Commit Message**: `fix(cli): add Impact and Correction panels to agents plan explain output` - **Milestone**: v3.2.0 - **Parent Epic**: #357 ## Description The `agents plan explain` command is missing two required output sections that are explicitly specified in `docs/specification.md` (lines 14545–14755), and has two additional structural mismatches with the spec. ### Missing Sections 1. **Impact panel** — should show: Downstream Decisions count, Downstream Child Plans count, Artifacts Produced count, Correction Impact level (low/medium/high) 2. **Correction hint panel** — should show the `agents plan correct <decision_id> --mode revert --guidance "..."` command hint ### Structural Mismatches 3. **Sequence format** — spec shows `"sequence": "2 of 5"` (with total count) but implementation shows just the sequence number integer 4. **Alternatives format** — spec shows alternatives as structured objects `[{"index": 1, "description": "...", "chosen": true}, ...]` but implementation shows plain strings ### Root Cause `_build_explain_dict()` (lines 3455–3490 of `src/cleveragents/cli/commands/plan.py`) does not include any impact data (`downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact`), no correction hint is generated or displayed, sequence is stored as a bare integer, and `alternatives_considered` is a plain list of strings rather than structured objects. ### Spec Reference `docs/specification.md` lines 14545–14755 (`agents plan explain` section): - Impact panel: lines 14582–14587 - Correction panel: lines 14604–14607 ### Steps to Reproduce 1. Record a decision with `downstream_decision_ids` and `artifacts_produced` 2. Run `agents plan explain <decision_id>` 3. Observe: no Impact panel, no Correction hint panel in the output; sequence is an integer; alternatives are plain strings ### Expected vs Actual **Expected** (per spec): - Rich output includes an "Impact" panel showing `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, and `correction_impact` - Rich output includes a "Correction" panel showing the `agents plan correct` command hint - JSON output has `"sequence": "N of M"` format - `"alternatives"` are structured objects with `index`/`description`/`chosen` fields **Actual**: - No Impact panel rendered - No Correction hint panel rendered - Sequence is a bare integer - `alternatives_considered` is a plain list of strings ### Code Location `src/cleveragents/cli/commands/plan.py` lines 3455–3562 (`_build_explain_dict`, `explain_decision_cmd`) ## Subtasks - [ ] Update `_build_explain_dict()` to include `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, and `correction_impact` fields from the decision record - [ ] Fix `sequence` field to output `"N of M"` string format (query total decision count for the plan) - [ ] Fix `alternatives_considered` to output structured objects `[{"index": N, "description": "...", "chosen": bool}, ...]` - [ ] Add Impact panel rendering in `explain_decision_cmd` Rich output (downstream decisions, child plans, artifacts produced, correction impact level) - [ ] Add Correction hint panel rendering in `explain_decision_cmd` Rich output (showing `agents plan correct <decision_id> --mode revert --guidance "..."`) - [ ] Tests (Behave): Add/update scenarios in `features/` covering Impact panel fields in JSON output - [ ] Tests (Behave): Add/update scenarios covering Correction hint panel in Rich output - [ ] Tests (Behave): Add/update scenarios covering `"N of M"` sequence format - [ ] Tests (Behave): Add/update scenarios covering structured alternatives objects - [ ] Tests (Robot): Add/update integration test for `agents plan explain` verifying Impact and Correction panels render correctly - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - `agents plan explain <decision_id>` renders an **Impact** panel showing `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, and `correction_impact` in both Rich and JSON output modes. - `agents plan explain <decision_id>` renders a **Correction** panel showing the `agents plan correct` command hint. - JSON output `sequence` field is in `"N of M"` string format. - JSON output `alternatives` field contains structured objects with `index`, `description`, and `chosen` fields. - Output matches the spec at `docs/specification.md` lines 14545–14755. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - 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 06:19:11 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Critical (keeping existing — plan explain output is a core v3.2.0 deliverable)
  • Milestone: v3.2.0 (already assigned, keeping)
  • MoSCoW: Must Have — v3.2.0 acceptance criteria requires "agents plan explain shows decision details including alternatives considered." Missing Impact and Correction panels mean the explain output is incomplete per spec.
  • Parent Epic: #357 (as noted in issue body)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical (keeping existing — plan explain output is a core v3.2.0 deliverable) - **Milestone**: v3.2.0 (already assigned, keeping) - **MoSCoW**: Must Have — v3.2.0 acceptance criteria requires "`agents plan explain` shows decision details including alternatives considered." Missing Impact and Correction panels mean the explain output is incomplete per spec. - **Parent Epic**: #357 (as noted in issue body) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Label compliance fix applied:

  • Removed conflicting label: Priority/Medium
  • Kept: Priority/Critical (higher priority takes precedence)
  • Added: Type/Bug (inferred from UAT prefix and bug description)
  • Reason: Issue had both Priority/Critical and Priority/Medium — conflicting priority labels. Per CONTRIBUTING.md, exactly one Priority/* label is required.

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

Label compliance fix applied: - Removed conflicting label: `Priority/Medium` - Kept: `Priority/Critical` (higher priority takes precedence) - Added: `Type/Bug` (inferred from UAT prefix and bug description) - Reason: Issue had both `Priority/Critical` and `Priority/Medium` — conflicting priority labels. Per CONTRIBUTING.md, exactly one `Priority/*` label is required. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
freemo removed this from the v3.2.0 milestone 2026-04-06 20:50:28 +00:00
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.

Blocks
Reference
cleveragents/cleveragents-core#3109
No description provided.