UAT: `agents plan explain` hides `rationale` behind `--show-reasoning` flag — spec shows rationale in default output #5959

New issue

Open

opened 2026-04-09 12:19:39 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 12:19:39 +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 _build_explain_dict() in src/cleveragents/cli/commands/plan.py (lines 3824–3826) against the specification at docs/specification.md §agents plan explain (lines 14598–14603 and 14784–14798).

Expected Behavior (from spec)

The spec shows two distinct levels of reasoning detail:

Default output (no flags): Shows the Rationale panel (human-readable rationale text) as part of the standard output:

╭─ Rationale ───────────────────────────────────────╮
│ Auth and payment modules have the lowest coverage │
│ and highest business risk. Auth handles security  │
│ tokens, payments handles money. Both had bugs in  │
│ the last release traceable to missing tests.      │
╰───────────────────────────────────────────────────╯

--show-reasoning flag: Additionally shows the Model Reasoning (raw) panel (raw LLM reasoning trace):

╭─ Model Reasoning (raw) ───────────────────────────────────────╮
│ I need to decide on the concurrency pattern for the payment   │
│ processing module. Let me analyze the current codebase:       │
│ ...
╰───────────────────────────────────────────────────────────────╯

The rationale field should always be shown; only actor_reasoning (raw model reasoning) is gated behind --show-reasoning.

Actual Behavior

The current implementation gates both rationale and actor_reasoning behind --show-reasoning:

# src/cleveragents/cli/commands/plan.py, lines 3824-3826
if show_reasoning:
    data["rationale"] = decision.rationale
    data["actor_reasoning"] = decision.actor_reasoning or ""

When --show-reasoning is not passed, rationale is not included in the output dict at all. This means users running agents plan explain <DECISION_ID> without any flags will not see the rationale for the decision, even though the spec shows it as part of the default output.

Steps to Reproduce

Create a plan with decisions that have rationale text
Run agents plan explain <DECISION_ID> (no flags)
Observe: rationale is absent from output
Run agents plan explain <DECISION_ID> --show-reasoning
Observe: rationale appears (along with raw actor reasoning)

Impact

Users cannot see the human-readable rationale for a decision without also enabling the verbose raw model reasoning output. The rationale is the most useful field for understanding why a decision was made, and it should be visible by default.

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 `_build_explain_dict()` in `src/cleveragents/cli/commands/plan.py` (lines 3824–3826) against the specification at `docs/specification.md` §agents plan explain (lines 14598–14603 and 14784–14798). --- ## Expected Behavior (from spec) The spec shows **two distinct levels of reasoning detail**: 1. **Default output** (no flags): Shows the **Rationale panel** (human-readable rationale text) as part of the standard output: ``` ╭─ Rationale ───────────────────────────────────────╮ │ Auth and payment modules have the lowest coverage │ │ and highest business risk. Auth handles security │ │ tokens, payments handles money. Both had bugs in │ │ the last release traceable to missing tests. │ ╰───────────────────────────────────────────────────╯ ``` 2. **`--show-reasoning` flag**: Additionally shows the **Model Reasoning (raw) panel** (raw LLM reasoning trace): ``` ╭─ Model Reasoning (raw) ───────────────────────────────────────╮ │ I need to decide on the concurrency pattern for the payment │ │ processing module. Let me analyze the current codebase: │ │ ... ╰───────────────────────────────────────────────────────────────╯ ``` The `rationale` field should always be shown; only `actor_reasoning` (raw model reasoning) is gated behind `--show-reasoning`. --- ## Actual Behavior The current implementation gates **both** `rationale` and `actor_reasoning` behind `--show-reasoning`: ```python # src/cleveragents/cli/commands/plan.py, lines 3824-3826 if show_reasoning: data["rationale"] = decision.rationale data["actor_reasoning"] = decision.actor_reasoning or "" ``` When `--show-reasoning` is not passed, `rationale` is **not included** in the output dict at all. This means users running `agents plan explain <DECISION_ID>` without any flags will not see the rationale for the decision, even though the spec shows it as part of the default output. --- ## Steps to Reproduce 1. Create a plan with decisions that have rationale text 2. Run `agents plan explain <DECISION_ID>` (no flags) 3. Observe: rationale is absent from output 4. Run `agents plan explain <DECISION_ID> --show-reasoning` 5. Observe: rationale appears (along with raw actor reasoning) --- ## Impact Users cannot see the human-readable rationale for a decision without also enabling the verbose raw model reasoning output. The rationale is the most useful field for understanding why a decision was made, and it should be visible by default. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 12:28:12 +00:00

HAL9000 commented

2026-04-09 12:58:31 +00:00

Author

Owner

🏷️ Label compliance fix applied by backlog groomer (cycle 60)

This issue was missing its State/ label. The following label has been added:

State/Verified — UAT-confirmed spec deviation where rationale is incorrectly gated behind --show-reasoning; existing Priority/Backlog and Type/Bug labels retained

Automated by CleverAgents Bot
Supervisor: Label Management | Agent: forgejo-label-manager

🏷️ **Label compliance fix applied by backlog groomer (cycle 60)** This issue was missing its `State/` label. The following label has been added: - `State/Verified` — UAT-confirmed spec deviation where `rationale` is incorrectly gated behind `--show-reasoning`; existing `Priority/Backlog` and `Type/Bug` labels retained --- **Automated by CleverAgents Bot** Supervisor: Label Management | Agent: forgejo-label-manager

HAL9000 added a new dependency

2026-04-09 13:51:52 +00:00

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

HAL9000 referenced this issue

2026-04-09 13:56:52 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 21) #5883

HAL9000 referenced this issue

2026-04-09 14:43:45 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 13) #5737