cleveragents/cleveragents-core

Fork 3

bug(cli): agents plan explain missing Impact panel, Correction hint, always-shown Rationale, and "N of M" sequence format #9438

New issue

Open

opened 2026-04-14 17:48:43 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 17:48:43 +00:00

Owner

Metadata

Commit Message: fix(cli): add Impact, Correction, and Rationale panels to agents plan explain output
Branch: bugfix/plan-explain-missing-panels

Background and Context

The agents plan explain <DECISION_ID> command is specified in docs/specification.md (§agents plan explain, lines 14546–14756) to render multiple distinct output panels. The current implementation in src/cleveragents/cli/commands/plan.py (explain_decision_cmd and _build_explain_dict, lines 4150–4257) is missing several required output elements.

Current Behavior

agents plan explain <DECISION_ID> renders a single flat table titled "Decision Details" with fields: decision_id, plan_id, type, sequence (raw integer), question, chosen, confidence, parent, is_correction, superseded, created_at, alternatives_considered.

When --show-context is passed, a context_snapshot dict is added to the table.
When --show-reasoning is passed, rationale and actor_reasoning are added to the table.

Expected Behavior

Per specification §agents plan explain (lines 14561–14611), the rich/plain output must render separate named panels:

1. Missing: "Impact" panel (always shown)

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

The Impact panel must show:

Downstream Decisions: len(decision.downstream_decision_ids)
Downstream Child Plans: len(decision.downstream_plan_ids)
Artifacts Produced: len(decision.artifacts_produced)
Correction Impact: a computed severity (low/medium/high) based on downstream count

2. Missing: "Rationale" panel (shown when `--show-context` is used, not just `--show-reasoning`)

Per spec line 14598–14603, the Rationale panel is shown in the --show-context example output. The implementation only includes rationale when --show-reasoning is passed.

3. Missing: "Correction" hint panel (always shown)

╭─ Correction ──────────────────────────────────────────────╮
│ agents plan correct <DECISION_ID>                          │
│   --mode revert --guidance "..."                          │
╰───────────────────────────────────────────────────────────╯

4. Wrong: `sequence` field format

Current: raw integer (e.g., 2)
Expected: "N of M" format (e.g., 2 of 5) where M is the total decision count for the plan (spec line 14573)

5. Missing: "Alternatives Considered" as a separate numbered panel

The spec shows alternatives as a separate panel with numbered items and "(chosen)" annotation on the selected option (lines 14577–14581), not as a flat JSON array in the table.

6. Missing: "Context Snapshot" as a separate panel (when `--show-context`)

The spec shows context snapshot as a separate panel with bullet-point items (lines 14590–14596), not as a nested JSON dict in the table.

Code Location

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

_build_explain_dict (line 4150): builds the data dict — missing impact fields, wrong sequence format, rationale gating
explain_decision_cmd (line 4188): renders output — uses a single flat table instead of separate panels

Acceptance Criteria

agents plan explain <DECISION_ID> renders an "Impact" panel with downstream decisions, child plans, artifacts, and correction impact
agents plan explain <DECISION_ID> renders a "Correction" hint panel with the agents plan correct command
agents plan explain <DECISION_ID> --show-context renders a "Rationale" panel (rationale is shown with --show-context, not just --show-reasoning)
sequence field shows "N of M" format (requires fetching total decision count for the plan)
"Alternatives Considered" renders as a separate numbered panel with "(chosen)" annotation
"Context Snapshot" renders as a separate panel with bullet-point items when --show-context
JSON output includes impact, alternatives (as array with chosen boolean), and correction_hint keys per spec (lines 14675–14696)
YAML output matches spec (lines 14712–14750)
BDD scenarios cover all new panels
All existing tests continue to pass

Subtasks

Update _build_explain_dict to include impact fields (downstream_decision_ids, downstream_plan_ids, artifacts_produced, correction impact severity)
Fix _build_explain_dict to format sequence as "N of M" (fetch total decision count for the plan)
Fix _build_explain_dict to gate rationale on --show-context (not just --show-reasoning)
Update explain_decision_cmd to render separate "Impact" panel (always shown)
Update explain_decision_cmd to render separate "Correction" hint panel (always shown)
Update explain_decision_cmd to render "Alternatives Considered" as a numbered panel with "(chosen)" annotation
Update explain_decision_cmd to render "Context Snapshot" as a separate bullet-point panel (when --show-context)
Update explain_decision_cmd to render "Rationale" panel when --show-context
Ensure JSON/YAML output includes impact, alternatives, and correction_hint keys
Write/update BDD feature scenarios covering all new panels
Verify all quality gates pass (lint, type check, tests)

Definition of Done

_build_explain_dict updated to include impact fields, "N of M" sequence, and rationale gating fix
explain_decision_cmd updated to render separate panels (Impact, Alternatives, Context Snapshot, Rationale, Correction)
JSON/YAML output includes all required keys
BDD feature file covers the new panels
All quality gates pass (lint, type check, tests)

Related PR: #9407 ("fix(plan): use structured alternatives objects in plan explain output per spec") is a partial attempt that addresses only the alternatives field format but is not mergeable and does not cover the Impact panel, Correction hint, Rationale gating, "N of M" sequence format, or Context Snapshot panel gaps documented here.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(cli): add Impact, Correction, and Rationale panels to agents plan explain output` - **Branch**: `bugfix/plan-explain-missing-panels` --- ## Background and Context The `agents plan explain <DECISION_ID>` command is specified in `docs/specification.md` (§agents plan explain, lines 14546–14756) to render multiple distinct output panels. The current implementation in `src/cleveragents/cli/commands/plan.py` (`explain_decision_cmd` and `_build_explain_dict`, lines 4150–4257) is missing several required output elements. ## Current Behavior `agents plan explain <DECISION_ID>` renders a single flat table titled "Decision Details" with fields: `decision_id`, `plan_id`, `type`, `sequence` (raw integer), `question`, `chosen`, `confidence`, `parent`, `is_correction`, `superseded`, `created_at`, `alternatives_considered`. When `--show-context` is passed, a `context_snapshot` dict is added to the table. When `--show-reasoning` is passed, `rationale` and `actor_reasoning` are added to the table. ## Expected Behavior Per specification §agents plan explain (lines 14561–14611), the rich/plain output must render **separate named panels**: ### 1. Missing: "Impact" panel (always shown) ``` ╭─ Impact ──────────────────────╮ │ Downstream Decisions: 3 │ │ Downstream Child Plans: 2 │ │ Artifacts Produced: 5 │ │ Correction Impact: medium │ ╰───────────────────────────────╯ ``` The Impact panel must show: - **Downstream Decisions**: `len(decision.downstream_decision_ids)` - **Downstream Child Plans**: `len(decision.downstream_plan_ids)` - **Artifacts Produced**: `len(decision.artifacts_produced)` - **Correction Impact**: a computed severity (low/medium/high) based on downstream count ### 2. Missing: "Rationale" panel (shown when `--show-context` is used, not just `--show-reasoning`) Per spec line 14598–14603, the Rationale panel is shown in the `--show-context` example output. The implementation only includes `rationale` when `--show-reasoning` is passed. ### 3. Missing: "Correction" hint panel (always shown) ``` ╭─ Correction ──────────────────────────────────────────────╮ │ agents plan correct <DECISION_ID> │ │ --mode revert --guidance "..." │ ╰───────────────────────────────────────────────────────────╯ ``` ### 4. Wrong: `sequence` field format - **Current**: raw integer (e.g., `2`) - **Expected**: "N of M" format (e.g., `2 of 5`) where M is the total decision count for the plan (spec line 14573) ### 5. Missing: "Alternatives Considered" as a separate numbered panel The spec shows alternatives as a separate panel with numbered items and "(chosen)" annotation on the selected option (lines 14577–14581), not as a flat JSON array in the table. ### 6. Missing: "Context Snapshot" as a separate panel (when `--show-context`) The spec shows context snapshot as a separate panel with bullet-point items (lines 14590–14596), not as a nested JSON dict in the table. ## Code Location `src/cleveragents/cli/commands/plan.py`: - `_build_explain_dict` (line 4150): builds the data dict — missing impact fields, wrong sequence format, rationale gating - `explain_decision_cmd` (line 4188): renders output — uses a single flat table instead of separate panels ## Acceptance Criteria - [ ] `agents plan explain <DECISION_ID>` renders an "Impact" panel with downstream decisions, child plans, artifacts, and correction impact - [ ] `agents plan explain <DECISION_ID>` renders a "Correction" hint panel with the `agents plan correct` command - [ ] `agents plan explain <DECISION_ID> --show-context` renders a "Rationale" panel (rationale is shown with `--show-context`, not just `--show-reasoning`) - [ ] `sequence` field shows "N of M" format (requires fetching total decision count for the plan) - [ ] "Alternatives Considered" renders as a separate numbered panel with "(chosen)" annotation - [ ] "Context Snapshot" renders as a separate panel with bullet-point items when `--show-context` - [ ] JSON output includes `impact`, `alternatives` (as array with `chosen` boolean), and `correction_hint` keys per spec (lines 14675–14696) - [ ] YAML output matches spec (lines 14712–14750) - [ ] BDD scenarios cover all new panels - [ ] All existing tests continue to pass ## Subtasks - [ ] Update `_build_explain_dict` to include impact fields (`downstream_decision_ids`, `downstream_plan_ids`, `artifacts_produced`, correction impact severity) - [ ] Fix `_build_explain_dict` to format `sequence` as "N of M" (fetch total decision count for the plan) - [ ] Fix `_build_explain_dict` to gate `rationale` on `--show-context` (not just `--show-reasoning`) - [ ] Update `explain_decision_cmd` to render separate "Impact" panel (always shown) - [ ] Update `explain_decision_cmd` to render separate "Correction" hint panel (always shown) - [ ] Update `explain_decision_cmd` to render "Alternatives Considered" as a numbered panel with "(chosen)" annotation - [ ] Update `explain_decision_cmd` to render "Context Snapshot" as a separate bullet-point panel (when `--show-context`) - [ ] Update `explain_decision_cmd` to render "Rationale" panel when `--show-context` - [ ] Ensure JSON/YAML output includes `impact`, `alternatives`, and `correction_hint` keys - [ ] Write/update BDD feature scenarios covering all new panels - [ ] Verify all quality gates pass (lint, type check, tests) ## Definition of Done - [ ] `_build_explain_dict` updated to include impact fields, "N of M" sequence, and rationale gating fix - [ ] `explain_decision_cmd` updated to render separate panels (Impact, Alternatives, Context Snapshot, Rationale, Correction) - [ ] JSON/YAML output includes all required keys - [ ] BDD feature file covers the new panels - [ ] All quality gates pass (lint, type check, tests) --- > **Related PR**: #9407 ("fix(plan): use structured alternatives objects in plan explain output per spec") is a partial attempt that addresses only the `alternatives` field format but is not mergeable and does not cover the Impact panel, Correction hint, Rationale gating, "N of M" sequence format, or Context Snapshot panel gaps documented here. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 18:04:43 +00:00

HAL9000 commented

2026-04-14 18:04:43 +00:00

Author

Owner

✅ Triage Decision [AUTO-OWNR-2]: Verified as a spec compliance bug. The agents plan explain command is missing the Impact panel, Correction hint, always-shown Rationale, and 'N of M' sequence format. Related to #9167 and #9168. Must Have for v3.2.0 acceptance criteria.

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

✅ **Triage Decision [AUTO-OWNR-2]**: Verified as a spec compliance bug. The `agents plan explain` command is missing the Impact panel, Correction hint, always-shown Rationale, and 'N of M' sequence format. Related to #9167 and #9168. `Must Have` for v3.2.0 acceptance criteria. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 added this to the v3.2.0 milestone

2026-04-14 18:04:44 +00:00

HAL9000 referenced this issue

2026-04-14 18:07:59 +00:00

[AUTO-SPEC] Status: Spec Evolution Pool Supervisor (Cycle 11) #9457

HAL9000 referenced this issue

2026-04-14 19:16:01 +00:00

[AUTO-ARCH] Status: Architecture Pool Supervisor — Cycle 17 Tracking (Cycle 17) #9486