feat(plan): implement agents plan explain to show decision details and alternatives #9281

New issue

Open

opened 2026-04-14 13:59:54 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-14 13:59:54 +00:00

Owner

Metadata

Commit Message: feat(plan): implement agents plan explain to show decision details and alternatives
Branch: feat/plan-explain-decision-details
Milestone: v3.2.0

Background and Context

The v3.2.0 milestone (M3: Decisions + Validations + Invariants) requires that agents plan explain shows decision details including alternatives considered. This command is a critical observability and auditability tool that allows users and automated agents to deeply inspect any individual decision made during a plan execution.

Currently, users can list decisions via agents plan tree or agents plan list, but there is no way to drill into a specific decision to understand:

What context was available when the decision was made
What alternatives were evaluated and why they were rejected
Why the chosen option was ultimately selected
What concrete impact the decision had (files changed, actions taken)

Without agents plan explain, users cannot perform meaningful post-hoc audits, debug unexpected plan outcomes, or understand the reasoning chain behind automated decisions. This is especially important for compliance, debugging, and iterative improvement of agent plans.

Expected Behavior

Running agents plan explain <PLAN_ID> <DECISION_ID> should produce a detailed, human-readable report for the specified decision, including:

Decision Summary — ID, type, timestamp, and current status
Decision Context — the full context snapshot available at decision time (inputs, state, prior decisions)
Alternatives Considered — a list of all options that were evaluated, with their scores or rejection reasons
Chosen Option Rationale — the explanation for why the selected option was preferred
Decision Impact — files modified, actions triggered, or downstream decisions spawned as a result
Machine-readable output — --format json flag returns the full decision record as structured JSON

Example output (human-readable):

Decision: dec_abc123
Plan:     plan_xyz789
Type:     file_modification
Status:   completed
Made at:  2026-04-14T10:23:45Z

Context:
  - Task: Refactor authentication module
  - Prior decisions: 3 completed
  - Available files: src/auth/login.py, src/auth/session.py

Alternatives Considered:
  1. [REJECTED] Inline token validation — reason: violates separation of concerns
  2. [REJECTED] Third-party library — reason: adds unvetted dependency
  3. [CHOSEN]   Extract AuthValidator class — reason: clean separation, testable, no new deps

Impact:
  - Modified: src/auth/login.py (+45 / -12 lines)
  - Created:  src/auth/validator.py (+87 lines)
  - Spawned:  2 downstream decisions (dec_def456, dec_ghi789)

Acceptance Criteria

agents plan explain <PLAN_ID> <DECISION_ID> is a valid CLI command that executes without error
The command outputs the decision summary (ID, type, timestamp, status)
The command displays the decision context (inputs and state available at decision time)
The command lists all alternatives that were considered, with rejection reasons where available
The command shows the rationale for the chosen option
The command shows the impact of the decision (files/changes produced, downstream decisions spawned)
--format json flag returns a complete, valid JSON object containing all decision fields
The command returns a non-zero exit code and a clear error message when the PLAN_ID or DECISION_ID does not exist
The command is documented in the CLI help (agents plan explain --help)
Unit tests cover: successful explain output, missing plan, missing decision, JSON format output
Integration tests verify end-to-end output against a known plan fixture

Subtasks

Audit existing plan/decision data model to confirm all required fields are stored (context, alternatives, rationale, impact)
Add any missing fields to the decision schema (e.g., alternatives, rationale, context_snapshot, impact)
Implement agents plan explain CLI command entry point
Implement the PlanExplainFormatter (or equivalent) for human-readable output
Implement JSON serialization path for --format json
Wire up error handling for unknown PLAN_ID and DECISION_ID
Write unit tests for the explain command (happy path, error cases, JSON format)
Write integration test using a plan fixture with known decisions
Update CLI help text and any relevant documentation
Perform manual smoke test: run agents plan explain against a real plan and verify output

Definition of Done

All acceptance criteria checkboxes are checked
All subtasks are completed
CI passes (lint, type-check, unit tests, integration tests)
The --format json output is validated against the decision schema
The feature is documented in the CLI reference
Code reviewed and approved by at least one maintainer
Issue is closed and linked to the merge commit on branch feat/plan-explain-decision-details

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `feat(plan): implement agents plan explain to show decision details and alternatives` - **Branch**: `feat/plan-explain-decision-details` - **Milestone**: v3.2.0 ## Background and Context The v3.2.0 milestone (M3: Decisions + Validations + Invariants) requires that `agents plan explain` shows decision details including alternatives considered. This command is a critical observability and auditability tool that allows users and automated agents to deeply inspect any individual decision made during a plan execution. Currently, users can list decisions via `agents plan tree` or `agents plan list`, but there is no way to drill into a specific decision to understand: - What context was available when the decision was made - What alternatives were evaluated and why they were rejected - Why the chosen option was ultimately selected - What concrete impact the decision had (files changed, actions taken) Without `agents plan explain`, users cannot perform meaningful post-hoc audits, debug unexpected plan outcomes, or understand the reasoning chain behind automated decisions. This is especially important for compliance, debugging, and iterative improvement of agent plans. ## Expected Behavior Running `agents plan explain <PLAN_ID> <DECISION_ID>` should produce a detailed, human-readable report for the specified decision, including: 1. **Decision Summary** — ID, type, timestamp, and current status 2. **Decision Context** — the full context snapshot available at decision time (inputs, state, prior decisions) 3. **Alternatives Considered** — a list of all options that were evaluated, with their scores or rejection reasons 4. **Chosen Option Rationale** — the explanation for why the selected option was preferred 5. **Decision Impact** — files modified, actions triggered, or downstream decisions spawned as a result 6. **Machine-readable output** — `--format json` flag returns the full decision record as structured JSON Example output (human-readable): ``` Decision: dec_abc123 Plan: plan_xyz789 Type: file_modification Status: completed Made at: 2026-04-14T10:23:45Z Context: - Task: Refactor authentication module - Prior decisions: 3 completed - Available files: src/auth/login.py, src/auth/session.py Alternatives Considered: 1. [REJECTED] Inline token validation — reason: violates separation of concerns 2. [REJECTED] Third-party library — reason: adds unvetted dependency 3. [CHOSEN] Extract AuthValidator class — reason: clean separation, testable, no new deps Impact: - Modified: src/auth/login.py (+45 / -12 lines) - Created: src/auth/validator.py (+87 lines) - Spawned: 2 downstream decisions (dec_def456, dec_ghi789) ``` ## Acceptance Criteria - [ ] `agents plan explain <PLAN_ID> <DECISION_ID>` is a valid CLI command that executes without error - [ ] The command outputs the decision summary (ID, type, timestamp, status) - [ ] The command displays the decision context (inputs and state available at decision time) - [ ] The command lists all alternatives that were considered, with rejection reasons where available - [ ] The command shows the rationale for the chosen option - [ ] The command shows the impact of the decision (files/changes produced, downstream decisions spawned) - [ ] `--format json` flag returns a complete, valid JSON object containing all decision fields - [ ] The command returns a non-zero exit code and a clear error message when the PLAN_ID or DECISION_ID does not exist - [ ] The command is documented in the CLI help (`agents plan explain --help`) - [ ] Unit tests cover: successful explain output, missing plan, missing decision, JSON format output - [ ] Integration tests verify end-to-end output against a known plan fixture ## Subtasks - [ ] Audit existing plan/decision data model to confirm all required fields are stored (context, alternatives, rationale, impact) - [ ] Add any missing fields to the decision schema (e.g., `alternatives`, `rationale`, `context_snapshot`, `impact`) - [ ] Implement `agents plan explain` CLI command entry point - [ ] Implement the `PlanExplainFormatter` (or equivalent) for human-readable output - [ ] Implement JSON serialization path for `--format json` - [ ] Wire up error handling for unknown PLAN_ID and DECISION_ID - [ ] Write unit tests for the explain command (happy path, error cases, JSON format) - [ ] Write integration test using a plan fixture with known decisions - [ ] Update CLI help text and any relevant documentation - [ ] Perform manual smoke test: run `agents plan explain` against a real plan and verify output ## Definition of Done - All acceptance criteria checkboxes are checked - All subtasks are completed - CI passes (lint, type-check, unit tests, integration tests) - The `--format json` output is validated against the decision schema - The feature is documented in the CLI reference - Code reviewed and approved by at least one maintainer - Issue is closed and linked to the merge commit on branch `feat/plan-explain-decision-details` --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 14:01:17 +00:00

HAL9000 added this to the v3.2.0 milestone