SIMULATION.md

# ABOUT SIMULATION.MD

SIMULATION.md is a working idea: a plain markdown file that sets up a rehearsal for an AI agent before it does anything real. It lists the plans to compare, the mock tools that stand in for real ones, the ways each mock fails, and what counts as a good result. The failures are the ones you write down: a timeout, a duplicate, a partial write, a bounce. The agent runs each plan against the mocks many times, compares the results, and names the assumption that would change the answer. Then a person decides what, if anything, runs for real.

## WHAT IT COULD COVER

• - the task: what the agent is about to do, and why it is risky
• - plans: two to six ways to do it
• - mock tools: stand-ins for email, payments, a database or an outside service
• - failures: the faults you write down, how often, and in what order
• - the world: starting data, made up or scrubbed, never live records
• - success: what a good result is, and what is never acceptable
• - the answer: which plan does best, and which assumption would flip it
• - after: what still needs a person before anything real

## HOW IT COULD WORK

• - the mocks: a mock server such as Prism or WireMock answers like the real service, from an OpenAPI description or recorded examples
• - the faults: a proxy such as Toxiproxy adds delay, timeouts and dropped connections between the agent and the mocks
• - the seeds: every random choice comes from a seed, so the same run gives the same result
• - the sweep: each plan runs many times across the ranges, and the report shows which assumption moves the answer most
• - the agent: writes the plans, runs the rehearsal and presents the comparison; a person picks

## METHODS AND TOOLS IT COULD NAME

• - fault injection: adding errors on purpose to see how a plan copes
• - chaos engineering: testing how systems cope by causing failures on purpose, a practice made known by Netflix's Chaos Monkey
• - Toxiproxy: an open-source proxy from Shopify for simulating network trouble
• - Prism and WireMock: open-source mock servers for HTTP services
• - OpenAPI: an open standard for describing HTTP services, from which mocks can be made
• - Monte Carlo: running a plan many times with random draws from the ranges
• - sensitivity analysis: changing one assumption at a time to see which moves the answer
• - dry runs: modes such as terraform plan and kubectl's dry-run flag that show what would change without changing it
• - idempotency keys: a key sent with a request so a retry is not carried out twice, used by payment services such as Stripe

## WHO IT COULD HELP

• - finance operations: rehearse a refund batch where the payment service times out halfway
• - support teams: a bulk reply plan against a mock mailer that rejects some addresses
• - platform teams: a migration plan against a database copy that runs out of disk midway
• - marketing teams: a send to 40,000 people against a mock that rate-limits
• - startups: compare retrying, queueing and giving up before wiring an agent to a real service

Many costly agent mistakes are not bad reasoning. They are reasonable plans meeting a timeout, a retry or a duplicate. Those cases are cheap to write down and expensive to discover live.

## A SKETCH

```md
---
simulation: draft
---
# SIMULATION.md
- task: refund 1,200 orders after an outage, made-up example
- plan_a: one batch, retry each failed call twice
- plan_b: batches of 100, stop the run after 5 failures
- mocks: payments, orders database, customer email
- fault: payments times out 1 call in 50, after the refund lands
- fault: email bounces 2 in 100; the database never fails
- world: scrubbed copy of the 1,200 orders, seed 7
- success: every order refunded once, none twice
- assumption: timeouts from 1 to 5 calls in 100
- runs: 500 per plan at each timeout rate
- result: the agent reports, a person picks a plan
- real_run: none from here; every real refund needs a yes
```

## DISCLAIMER

SIMULATION.md does not run anything real, and a rehearsal is not a test of any real system, a prediction or a safety check. Mock tools fail only in the ways you write down; real services can fail in ways nobody wrote down, so a plan that passes a rehearsal can still go wrong. The file states the setup and the limits; your permissions, approvals and contracts are what control real actions. The orders, rates and counts in the sketch are made up. Tools named here are described for reference only, with no affiliation or endorsement.

SIMULATION.md is an informational page. It is provided as is, without warranty of any kind, and may be incomplete, inaccurate or out of date. Nothing here is financial, investment, legal, tax, insurance, medical, engineering, safety or other professional advice, or an offer or solicitation of any kind. The sketch is an illustration, not a standard or a recommendation. Names of third-party products or companies, if any, are used only to describe them; no affiliation or endorsement is implied. Use at your own risk. This page sets no cookies and runs no scripts or analytics; like any website, its host keeps standard request logs.