Inspect / Prepare / Execute Contract

Inspect / Prepare / Execute Contract

Capabilities should separate context gathering, work preparation, and external effects. Inspect and Prepare can be useful without changing the outside world; Execute is the only phase that may cross into effect, and it must pass the platform's approval, authorization, idempotency, audit, and kill-switch checks.

Problem

Extensible platforms often let addons mix analysis, drafting, and action in one method. The platform cannot tell whether the capability is still thinking, preparing, or about to change the world, so approval and audit become conventions instead of architecture.

Context

Use this pattern when a platform supports addons, connectors, agents, assistant modules, workflow capabilities, or delegated actors that can gather context, draft work, and eventually perform an external effect.

Forces

• Capabilities need to inspect context and prepare useful drafts.
• External effects need stronger governance than internal work.
• Missing information should be found before execution.
• Addon authors will otherwise invent local lifecycle semantics.
• Approval gates need a stable effect boundary.
• Operators need one reviewable shape for every capability.
• Execution mode has to be visible before approval can mean anything.
• Fallback paths must not bypass the phase contract when the happy path cannot continue.
• Prepare should produce typed intent that Execute can validate, approve, audit, and replay.

Solution

Make every capability implement a three-phase contract:

Inspect -> Prepare -> Execute

Inspect reads context, checks readiness, and reports missing inputs or possible actions. Prepare creates internal artifacts such as drafts, tasks, blockers, plans, and action requests. Neither phase has external side effects. Execute is the only phase allowed to perform the approved effect, and it must consult the platform's approval, authorization, idempotency, audit, and disablement checks.

Where the action is non-trivial, Prepare should emit a typed intermediate model rather than an opaque blob. That gives approval, dry-run, execution, and audit the same representation of intent.

Consequences

The system can be helpful before it is powerful. Capabilities can inspect and draft freely, while irreversible or external work remains concentrated behind a governable execution boundary.

Failure Modes

• A capability sends, posts, books, charges, or mutates an external system during Inspect.
• Prepare quietly performs the real action.
• Each addon invents its own phase names and approval semantics.
• The approval gate cannot prove which prepared action maps to the executed effect.
• Dry-run and real mutation share the same execution path without a structural boundary.
• Workers or retries bypass the phase boundary.
• A fallback path executes the effect directly because the formal path is temporarily blocked.

Proof Points

contract: Inspect and Prepare produce context, drafts, tasks, blockers, and action requests; Execute is where approved effects happen.

approval, worker, audit, and module rails that make Execute governable.

• SADIE — addons use an Inspect / Prepare / Execute
• Ampriot — the parent platform supplies the truth,

Full source pattern: inspect-prepare-execute-contract.md.