# Agent State Machine Mapper

Convert a loosely described agent workflow into explicit states, transitions, guards, retries, timeouts, and terminal outcomes.

## Prompt

You are an AI workflow engineer who specializes in deterministic state management around probabilistic agent behavior.

Inputs:
1. Agent goal and workflow narrative: {{workflow_narrative}}
2. Events, tools, approvals, and external systems: {{events_and_dependencies}}
3. Business rules and prohibited transitions: {{business_rules}}
4. Retry, timeout, cancellation, and recovery expectations: {{recovery_requirements}}
5. Persistence, orchestration, and audit constraints: {{technical_constraints}}

Do the following:
1. Identify stable states, transient processing states, waiting states, and terminal outcomes; distinguish state from data attributes and UI labels.
2. Define every transition with its triggering event, guard conditions, side effects, idempotency behavior, owner, and audit record.
3. Add explicit paths for validation failure, tool outage, partial success, human rejection, timeout, cancellation, duplicate events, and resumed execution.
4. Detect unreachable states, ambiguous ownership, unsafe loops, missing terminal states, and transitions that allow the agent to bypass authorization or verification.
5. Produce a state table, Mermaid-compatible state diagram text, transition contract examples, invariants, and test cases covering happy paths and recovery paths.

## Best for

Engineers turning agent prototypes into durable workflows that can resume safely, handle asynchronous events, and avoid duplicate side effects.

## Compatible tools

- Claude
- ChatGPT

## How to use

- Describe events and external side effects separately.
- List every approval and prohibited transition.
- Specify retry, timeout, and cancellation behavior.
- Validate the map against event replay and duplicate delivery.

## Customization tips

- Use states for durable conditions, not every internal step.
- Add guard conditions for authorization and verification.
- Give external writes idempotency keys.
- Define terminal outcomes for rejection, cancellation, and recovery.

## Example input

Workflow: A contract-intake agent receives an uploaded agreement, validates required fields, extracts terms, requests legal review for risky clauses, collects business approval, and stores the signed record. Events: file upload, extraction result, reviewer decision, approval webhook, and document-system confirmation. Rules: no business approval before legal clearance when risk is high; storage only after both approvals. Recovery: tools retry twice, reviews expire after five business days, and users may cancel before storage. Technical constraints: durable workflow engine, event replay, and seven-year audit retention.

## Example output

The map defines Received, Validating, ExtractionPending, ReviewRequired, AwaitingLegal, AwaitingBusiness, ReadyToStore, Storing, Completed, Rejected, Cancelled, and ManualRecovery states. Every external write uses a contract ID plus operation key for idempotency. High-risk contracts cannot enter AwaitingBusiness without legal approval. Expired reviews move to ManualRecovery rather than silently restarting. Duplicate webhooks are acknowledged without repeating side effects, and cancellation is blocked once immutable storage is confirmed.