Agent plan preview

Problem Context

• The product can generate, infer, or assemble a plan before running an agent, workflow, tool sequence, research task, code task, content operation, or customer action.
• The plan can include tool calls, data retrieval, edits, messages, payments, deployments, scheduling, deletes, external integrations, or other side effects.
• Users need to know what the agent will do before work starts, especially when plan steps affect other people, systems, money, security, compliance, or public output.
• A plan may become stale after the user changes the objective, source scope, permissions, model instructions, selected record, or available tools.
• Some steps may be editable while others are fixed by policy, required by dependency, conditional, blocked, or gated by human approval.

Selection Rules

• Choose agent plan preview when an AI agent's proposed multi-step execution needs review before it starts.
• Use task list when users are choosing from known tasks they own, not reviewing an agent-generated run plan.
• Use recommended next action when the system proposes one immediate action rather than a sequence of planned steps.
• Use human approval gate when a running automation is paused at a specific step and needs authorization to continue.
• Use step navigation when users move through a fixed human-driven sequence instead of shaping an agent run.
• Use prompt box when the main task is composing the initial request; show agent plan preview after the request produces a proposed plan.
• Use agent progress trace after execution starts and tool-use visibility while tools run; do not use plan preview as the runtime log.
• Expose planned tools, data sources, permissions, assumptions, approval gates, external side effects, and expected outputs before Run.
• Allow edits only for plan fields the system can honor, and label fixed or policy-required steps as fixed.
• Invalidate or regenerate the plan when objective, context, source scope, permissions, tool availability, or model instructions change.

Required States

• Draft plan state with objective, ordered steps, planned tools, and expected output.
• Editable step state with edit, remove, reorder, or scope controls where safe.
• Fixed or required step state where policy or dependency prevents editing.
• Optional and conditional step states.
• Permission-limited or missing-input blocked step state.
• Risk warning state for external side effects, destructive actions, money movement, or public communication.
• Human approval gate marker state for steps that will pause during execution.
• Plan changed, regenerated, stale, or out-of-date state after context changes.
• Run-ready state with visible run, save, cancel, and review controls.
• Run-started handoff state that preserves the reviewed plan version.
• Mobile compact plan preview state.

Interaction Contract

• The preview names the objective, plan version, source context, model or workflow instructions, planned tools, and expected output before run.
• Each plan step explains what the agent will do, what data it will access, what side effect may occur, and whether the user can edit it.
• Editing, removing, reordering, or scoping steps updates the plan version and validation state before execution.
• Fixed, required, permission-limited, blocked, stale, and approval-required states change available actions before Run.
• Run starts only the reviewed plan version, or warns that the plan changed and asks the user to review again.
• When execution starts, the UI preserves the reviewed plan and hands off to progress trace, tool-use visibility, human approval gate, and audit trail surfaces.
• Canceling or saving the preview does not silently run tools or commit side effects.
• Keyboard and touch users can inspect, edit, reorder where allowed, approve, run, save, or cancel without losing the plan context.

Implementation Checklist

• Model plan ID, plan version, objective, source scope, assumptions, steps, dependencies, tools, permissions, expected outputs, side effects, approval gates, risk level, editability, and stale triggers as structured data.
• Separate proposed plan state from execution progress, tool-call events, human approval gates, recommended next actions, task rows, and audit history.
• Render each step with title, purpose, tool, input, output, side effect, editability, dependency, and status before run.
• Add controls for edit step, remove step, reorder step, change source scope, regenerate plan, save plan, cancel, and run reviewed plan.
• Require explicit review before high-impact steps such as sending messages, changing records, spending money, deleting data, deploying, or publishing.
• Revalidate plan version, permissions, available tools, source scope, objective, and selected record immediately before run.
• Log reviewed plan version, user edits, run-start decision, plan diff, and later execution result for audit where outcomes matter.
• Test hidden tool calls, stale plan, edited step, fixed step, optional step, conditional step, blocked permission, approval gate marker, mobile wrapping, keyboard reordering, and screen-reader status updates.

Common Generated-UI Mistakes

• Showing a vague plan summary while hiding planned tool calls, data access, and side effects.
• Calling execution history a plan preview after the work has already run.
• Letting the agent execute a different plan than the one the user reviewed.
• Making every step editable even when policy, dependency, or safety requires fixed steps.
• Showing Run when required inputs, permissions, or approval gates are unresolved.
• Treating one recommended action as a full plan.
• Using task list row status for agent plan steps even though the agent, not the user, owns execution.
• Hiding stale-plan state after objective, context, source scope, or tool availability changes.

Critique Questions

• What exact plan version will run if the user selects Run?
• Can users see every planned tool call, data source, side effect, approval gate, and expected output?
• Which steps are editable, fixed, optional, conditional, blocked, or stale, and why?
• What context changes invalidate the plan before execution?
• How does the UI prove that execution followed the reviewed plan version?
• Would task list, recommended next action, human approval gate, step navigation, or progress trace solve the actual problem instead?