cleveragents/cleveragents-core

Fork 3

[AUTO-UAT-2] agents plan explain omits rationale and context snapshot from default output #8098

New issue

Closed

opened 2026-04-13 03:31:50 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-13 03:31:50 +00:00

Owner

Metadata

Commit message: fix(cli): include rationale and context snapshot in plan explain default output
Branch name: fix/plan-explain-default-output-spec-alignment

Background and Context

The v3.2.0 milestone acceptance criteria require that agents plan explain <decision_id> shows decision details including alternatives considered, rationale, and context snapshot summary. The specification section for agents plan explain states:

Shows: rationale, alternatives considered, context snapshot summary

The current implementation in src/cleveragents/cli/commands/plan.py (_build_explain_dict) hides rationale and context_snapshot behind optional flags (--show-reasoning and --show-context respectively), meaning the default output does not satisfy the spec.

Current Behavior

Running agents plan explain <decision_id> (without flags) returns:

decision_id ✓
question ✓
chosen ✓
type ✓
alternatives_considered ✓
rationale ✗ (hidden behind --show-reasoning)
context_snapshot ✗ (hidden behind --show-context)

The _build_explain_dict function in src/cleveragents/cli/commands/plan.py only adds rationale and actor_reasoning when show_reasoning=True, and only adds context_snapshot when show_context=True. Both default to False.

Expected Behavior

Per the v3.2.0 specification acceptance criteria:

agents plan explain shows decision details including alternatives considered
Shows: rationale, alternatives considered, context snapshot summary

The default output of agents plan explain <decision_id> must include:

rationale (always, not just with --show-reasoning)
alternatives_considered (already present ✓)
A context snapshot summary (always, not just with --show-context)

The --show-reasoning and --show-context flags may remain for extended detail (e.g., full actor_reasoning trace), but the base fields (rationale, context snapshot hash/summary) must appear in the default output.

Evidence

File: src/cleveragents/cli/commands/plan.py, function _build_explain_dict (lines ~4150–4185):

def _build_explain_dict(
    decision: Decision,
    *,
    show_context: bool = False,
    show_reasoning: bool = False,
) -> dict[str, object]:
    data: dict[str, object] = {
        "decision_id": decision.decision_id,
        ...
        "alternatives_considered": decision.alternatives_considered,
    }
    if show_reasoning:  # ← rationale hidden behind flag
        data["rationale"] = decision.rationale
        data["actor_reasoning"] = decision.actor_reasoning or ""
    if show_context:    # ← context_snapshot hidden behind flag
        snap = decision.context_snapshot
        data["context_snapshot"] = { ... }
    return data

The BDD feature file features/plan_explain.feature confirms this behavior:

Scenario: Explain a decision with default format
    ...
    And the explain dict should not contain key "rationale"
    And the explain dict should not contain key "context_snapshot"

This BDD scenario explicitly asserts the spec-violating behavior, meaning the tests are aligned with the implementation but both deviate from the spec.

Duplicate Check

Searched open issues for "plan explain", "rationale default", "show-reasoning", "show-context", "explain spec" — no existing issue found.
Issue #7926 covers a related but distinct problem (decision dependency persistence).

Subtasks

Update _build_explain_dict in src/cleveragents/cli/commands/plan.py to include rationale and a context snapshot summary (at minimum hot_context_hash) in the default output
Keep --show-reasoning for extended detail (full actor_reasoning LLM trace) and --show-context for full context snapshot detail
Update features/plan_explain.feature scenarios to assert rationale and context snapshot summary are present in default output
Update features/steps/plan_explain_steps.py step definitions accordingly
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.
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.

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-worker | Session: [AUTO-UAT-2]

## Metadata - **Commit message**: `fix(cli): include rationale and context snapshot in plan explain default output` - **Branch name**: `fix/plan-explain-default-output-spec-alignment` ## Background and Context The v3.2.0 milestone acceptance criteria require that `agents plan explain <decision_id>` shows decision details including alternatives considered, rationale, and context snapshot summary. The specification section for `agents plan explain` states: > Shows: rationale, alternatives considered, context snapshot summary The current implementation in `src/cleveragents/cli/commands/plan.py` (`_build_explain_dict`) hides `rationale` and `context_snapshot` behind optional flags (`--show-reasoning` and `--show-context` respectively), meaning the default output does not satisfy the spec. ## Current Behavior Running `agents plan explain <decision_id>` (without flags) returns: - `decision_id` ✓ - `question` ✓ - `chosen` ✓ - `type` ✓ - `alternatives_considered` ✓ - `rationale` ✗ (hidden behind `--show-reasoning`) - `context_snapshot` ✗ (hidden behind `--show-context`) The `_build_explain_dict` function in `src/cleveragents/cli/commands/plan.py` only adds `rationale` and `actor_reasoning` when `show_reasoning=True`, and only adds `context_snapshot` when `show_context=True`. Both default to `False`. ## Expected Behavior Per the v3.2.0 specification acceptance criteria: > `agents plan explain` shows decision details including alternatives considered > Shows: rationale, alternatives considered, context snapshot summary The default output of `agents plan explain <decision_id>` must include: - `rationale` (always, not just with `--show-reasoning`) - `alternatives_considered` (already present ✓) - A context snapshot summary (always, not just with `--show-context`) The `--show-reasoning` and `--show-context` flags may remain for extended detail (e.g., full `actor_reasoning` trace), but the base fields (`rationale`, context snapshot hash/summary) must appear in the default output. ## Evidence File: `src/cleveragents/cli/commands/plan.py`, function `_build_explain_dict` (lines ~4150–4185): ```python def _build_explain_dict( decision: Decision, *, show_context: bool = False, show_reasoning: bool = False, ) -> dict[str, object]: data: dict[str, object] = { "decision_id": decision.decision_id, ... "alternatives_considered": decision.alternatives_considered, } if show_reasoning: # ← rationale hidden behind flag data["rationale"] = decision.rationale data["actor_reasoning"] = decision.actor_reasoning or "" if show_context: # ← context_snapshot hidden behind flag snap = decision.context_snapshot data["context_snapshot"] = { ... } return data ``` The BDD feature file `features/plan_explain.feature` confirms this behavior: ```gherkin Scenario: Explain a decision with default format ... And the explain dict should not contain key "rationale" And the explain dict should not contain key "context_snapshot" ``` This BDD scenario explicitly asserts the spec-violating behavior, meaning the tests are aligned with the implementation but both deviate from the spec. ## Duplicate Check - Searched open issues for "plan explain", "rationale default", "show-reasoning", "show-context", "explain spec" — no existing issue found. - Issue #7926 covers a related but distinct problem (decision dependency persistence). ## Subtasks - [ ] Update `_build_explain_dict` in `src/cleveragents/cli/commands/plan.py` to include `rationale` and a context snapshot summary (at minimum `hot_context_hash`) in the default output - [ ] Keep `--show-reasoning` for extended detail (full `actor_reasoning` LLM trace) and `--show-context` for full context snapshot detail - [ ] Update `features/plan_explain.feature` scenarios to assert `rationale` and context snapshot summary are present in default output - [ ] Update `features/steps/plan_explain_steps.py` step definitions accordingly - [ ] 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. - 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-worker | Session: [AUTO-UAT-2]

HAL9000 added this to the v3.2.0 milestone

2026-04-13 03:31:55 +00:00

HAL9000 added the

labels

2026-04-13 03:33:49 +00:00

HAL9000 commented

2026-04-13 04:07:13 +00:00

Author

Owner

✅ Verified — The v3.2.0 acceptance criterion explicitly states: 'agents plan explain shows decision details including alternatives considered.' Omitting rationale and context snapshot means this criterion is not met. Must Have fix for v3.2.0. Verified.

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

✅ **Verified** — The v3.2.0 acceptance criterion explicitly states: '`agents plan explain` shows decision details including alternatives considered.' Omitting rationale and context snapshot means this criterion is not met. **Must Have** fix for v3.2.0. Verified. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-13 04:17:08 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Report (Cycle 1) #8181

HAL9000 referenced this issue

2026-04-13 06:58:10 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Report (Cycle 2) #8266