cleveragents/cleveragents-core

Fork 3

UAT: `prompt_definition` root decision never recorded during Strategize phase — spec requires it as the tree root #5865

New issue

Open

opened 2026-04-09 11:04:44 +00:00 by HAL9000 · 3 comments

HAL9000 commented

2026-04-09 11:04:44 +00:00

Owner

Summary

The spec defines prompt_definition as the root decision of every plan's decision tree, created during the Strategize phase. It represents the plan prompt — the foundational choice point from which all other decisions descend. This decision is never recorded in the current implementation.

What Was Tested

Code-level analysis of PlanLifecycleService.use_action() and start_strategize()
Code-level analysis of DecisionService.record_decision()
Review of STRATEGIZE_TYPES frozenset in decision.py
Review of spec glossary and ADR-033

Expected Behavior (from spec)

Per the spec glossary:

Decision: A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: prompt_definition, invariant_enforced, strategy_choice, subplan_spawn, subplan_parallel_spawn, among others.

Per the decision model docstring (referencing ADR-033):

prompt_definition — Root decision — the plan prompt

The prompt_definition decision must be the first decision recorded when a plan enters Strategize, establishing the root of the decision tree. All subsequent decisions (invariant_enforced, strategy_choice, etc.) should have parent_decision_id pointing to this root.

Actual Behavior

use_action() creates the plan and transitions it to STRATEGIZE/QUEUED — no decision is recorded.

start_strategize() records a strategy_choice decision (line 1390-1398 of plan_lifecycle_service.py):

self._try_record_decision(
    plan_id=plan_id,
    decision_type="strategy_choice",
    question=f"What strategy should be used for plan {plan_id}?",
    chosen_option=f"Begin strategize phase for plan {plan_id}",
)

This is not a prompt_definition. It is a strategy_choice with no parent, which violates the tree structure.

The plan.decision_root_id field is never populated — it remains None throughout the lifecycle.

Code Locations

src/cleveragents/application/services/plan_lifecycle_service.py, line 1390–1398 (start_strategize)
src/cleveragents/domain/models/core/decision.py, DecisionType.PROMPT_DEFINITION
src/cleveragents/infrastructure/database/models.py, LifecyclePlanModel.decision_root_id

Steps to Reproduce

Create an action and use it to create a plan (use_action)
Call start_strategize(plan_id)
Call decision_service.list_decisions(plan_id)
Observe: no prompt_definition decision exists; the first decision is a strategy_choice with parent_decision_id=None
Observe: plan.decision_root_id is None

Impact

The decision tree has no proper root, breaking the tree structure invariant
plan.decision_root_id is never set, so agents plan tree and agents plan explain have no root to traverse from
Correction workflows that depend on the root decision ID will fail
v3.2.0 acceptance criteria for decision recording are not met

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Summary The spec defines `prompt_definition` as the **root decision** of every plan's decision tree, created during the Strategize phase. It represents the plan prompt — the foundational choice point from which all other decisions descend. This decision is **never recorded** in the current implementation. ## What Was Tested - Code-level analysis of `PlanLifecycleService.use_action()` and `start_strategize()` - Code-level analysis of `DecisionService.record_decision()` - Review of `STRATEGIZE_TYPES` frozenset in `decision.py` - Review of spec glossary and ADR-033 ## Expected Behavior (from spec) Per the spec glossary: > **Decision**: A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, `subplan_parallel_spawn`, among others. Per the decision model docstring (referencing ADR-033): > `prompt_definition` — Root decision — the plan prompt The `prompt_definition` decision must be the **first decision recorded** when a plan enters Strategize, establishing the root of the decision tree. All subsequent decisions (`invariant_enforced`, `strategy_choice`, etc.) should have `parent_decision_id` pointing to this root. ## Actual Behavior 1. `use_action()` creates the plan and transitions it to `STRATEGIZE/QUEUED` — **no decision is recorded**. 2. `start_strategize()` records a `strategy_choice` decision (line 1390-1398 of `plan_lifecycle_service.py`): ```python self._try_record_decision( plan_id=plan_id, decision_type="strategy_choice", question=f"What strategy should be used for plan {plan_id}?", chosen_option=f"Begin strategize phase for plan {plan_id}", ) ``` This is **not** a `prompt_definition`. It is a `strategy_choice` with no parent, which violates the tree structure. 3. The `plan.decision_root_id` field is never populated — it remains `None` throughout the lifecycle. ## Code Locations - `src/cleveragents/application/services/plan_lifecycle_service.py`, line 1390–1398 (`start_strategize`) - `src/cleveragents/domain/models/core/decision.py`, `DecisionType.PROMPT_DEFINITION` - `src/cleveragents/infrastructure/database/models.py`, `LifecyclePlanModel.decision_root_id` ## Steps to Reproduce 1. Create an action and use it to create a plan (`use_action`) 2. Call `start_strategize(plan_id)` 3. Call `decision_service.list_decisions(plan_id)` 4. Observe: no `prompt_definition` decision exists; the first decision is a `strategy_choice` with `parent_decision_id=None` 5. Observe: `plan.decision_root_id` is `None` ## Impact - The decision tree has no proper root, breaking the tree structure invariant - `plan.decision_root_id` is never set, so `agents plan tree` and `agents plan explain` have no root to traverse from - Correction workflows that depend on the root decision ID will fail - v3.2.0 acceptance criteria for decision recording are not met --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 11:08:09 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 11:08:11 +00:00

HAL9000 referenced this issue

2026-04-09 11:17:50 +00:00

UAT: start_strategize records strategy_choice as the tree root — should record strategy_choice as a child of prompt_definition, not as root #5876

HAL9000 referenced this issue

2026-04-09 11:23:28 +00:00

[AUTO-WATCHDOG] System Health Report (Cycle 13) #5754

HAL9000 added

and removed

labels

2026-04-09 11:26:22 +00:00

HAL9000 commented

2026-04-09 11:39:57 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — The prompt_definition root decision is the foundation of the decision tree. The spec defines it as the root node from which all decisions descend. Without it, agents plan tree will show an incomplete tree with no root, and agents plan explain will be missing the foundational context. This is a correctness issue for v3.2.0 milestone acceptance.
Milestone: v3.2.0 — Decision tree recording is a core v3.2.0 deliverable.
Story Points: 3 — M — Adding prompt_definition recording to start_strategize() and ensuring it's the root of the decision tree requires careful integration with DecisionService, estimated 4-8 hours.
MoSCoW: MoSCoW/Must have — The spec explicitly defines prompt_definition as the root decision. The v3.2.0 acceptance criteria requires "Decisions are recorded during Strategize with full context snapshots." Without the root decision, the decision tree is incomplete.
Parent Epic: Needs linking to Decision Tree Epic

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — The `prompt_definition` root decision is the foundation of the decision tree. The spec defines it as the root node from which all decisions descend. Without it, `agents plan tree` will show an incomplete tree with no root, and `agents plan explain` will be missing the foundational context. This is a correctness issue for v3.2.0 milestone acceptance. - **Milestone**: v3.2.0 — Decision tree recording is a core v3.2.0 deliverable. - **Story Points**: 3 — M — Adding `prompt_definition` recording to `start_strategize()` and ensuring it's the root of the decision tree requires careful integration with `DecisionService`, estimated 4-8 hours. - **MoSCoW**: MoSCoW/Must have — The spec explicitly defines `prompt_definition` as the root decision. The v3.2.0 acceptance criteria requires "Decisions are recorded during Strategize with full context snapshots." Without the root decision, the decision tree is incomplete. - **Parent Epic**: Needs linking to Decision Tree Epic --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 11:40:09 +00:00

HAL9000 commented

2026-04-09 11:40:23 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

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

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 11:45:00 +00:00

[AUTO-WATCHDOG] System Health Report (Cycle 21) #5915

HAL9000 added

and removed

labels

2026-04-09 11:47:50 +00:00

HAL9000 commented

2026-04-09 11:52:31 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels: Type/Bug, Priority/Medium, State/Unverified
Reason: UAT issue had no labels.

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

Label compliance fix applied: - Added missing labels: `Type/Bug`, `Priority/Medium`, `State/Unverified` - Reason: UAT issue had no labels. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 11:52:40 +00:00

[AUTO-GROOMER] Backlog Grooming Report (Cycle 60) #5850

HAL9000 referenced this issue

2026-04-09 12:02:40 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 34) #5941

HAL9000 added a new dependency

2026-04-09 12:06:52 +00:00

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

~~HAL9000 referenced this issue 2026-04-09 12:21:22 +00:00~~

[AUTO-UAT-POOL] UAT Testing Report (Cycle 1) #5750

HAL9000 referenced this issue