It worked once. Run it twice.
Run It Twice makes coding agents test whether one logical action still creates one real outcome when requests retry, users double-click, webhooks redeliver, workers restart, or the network lies.
Packaged for Claude Code, OpenAI Codex, Cursor, and compatible agents.
🌐 English · 简体中文 · Português · 日本語 · Español · Русский
If your agent can charge, send, create, delete, reserve, provision, or migrate something, this skill is for you.
Install · Verdicts · Benchmark · Read the skill
Install from GitHub:
npx skills add Pablo-aps/run-it-twiceTo install from a local checkout instead:
npx skills add . --skill run-it-twiceOpenAI Codex can also discover a direct user-level copy without the Skills CLI:
mkdir -p ~/.agents/skills && cp -R skills/run-it-twice ~/.agents/skills/Then ask your agent explicitly:
Use the run-it-twice skill to test the order-creation flow under retry, concurrency, and restart. Count committed orders and emitted events at their authoritative stores.
In OpenAI Codex, you can mention $run-it-twice directly; if a local copy does not appear in /skills, restart Codex. The Codex discovery location and invocation syntax follow the official OpenAI skills documentation.
- Anyone using an AI coding agent to build an API route, webhook, background job, checkout, upload, or migration that changes real state.
- Engineers who own payments, orders, inventory, provisioning, uploads, or other state-changing APIs.
- Teams operating queues, jobs, webhooks, schedulers, outbox/inbox flows, and retrying workers.
- Reviewers and incident responders who need evidence stronger than "the handler returned
200."
This is a testing and review workflow, not a runtime idempotency library or a claim of exactly-once execution.
| Before | With Run It Twice |
|---|---|
| "Retry on timeout." | Keep one stable intent_id, give each attempt its own trace identity, and reconcile ambiguous outcomes before retrying. |
| "The handler ran twice, but the unit test passed." | Count committed rows, accepted charges, inventory moves, messages, or provider actions at the authority that owns them. |
| "We have an idempotency key." | Verify payload binding, atomic claim, conflict behavior, expiry, concurrency, and recovery after process state disappears. |
| "It looks idempotent." | Return one evidence-scoped verdict with observed counts, tested scenarios, residual risk, and the first failing boundary. |
one logical intent
├─ attempt A ─┐
└─ attempt B ─┴─ stable intent_id ─▶ atomic claim / recovery ─▶ authoritative effect ledger
└─▶ one verdict
The skill keeps business identity separate from transport attempts, binds the first accepted intent to a canonical semantic payload, and asks the system of record—not logs or mocks—what actually happened.
- Define the intent contract. Name the scope, stable intent ID, per-attempt ID, payload fingerprint, allowed effects, and stable result.
- Locate the authority. Inventory every real effect and the database, ledger, broker, provider, or filesystem that can prove its acceptance.
- Replay the ugly way—safely. Exercise sequential retry, lost response, persisted replay, simultaneous attempts, late delivery, restart, crash windows, and expired ownership in an isolated environment.
- Count, repair, and report. Assert the effect ledger after each scenario, fix the narrowest broken boundary when requested, add regression coverage, and issue exactly one verdict.
Two controls prevent a false sense of safety: the same intent ID with a changed semantic payload must conflict without a new effect, while two legitimate intent IDs with identical payloads must remain distinct.
| Verdict | Meaning |
|---|---|
REPEAT-SAFE |
Executed evidence covers the relevant retry/failure boundaries and both controls; observed authoritative effects stay within the declared allowance. Untested boundaries are named. |
DUPLICATES |
One logical intent created more authoritative effects than allowed. This takes precedence when the count invariant is breached. |
DIVERGES |
Repeats disagree on authoritative content or meaningful result, changed-payload reuse is accepted, or legitimate distinct intents are collapsed—without an excess-effect finding. |
NOT TESTED |
Safe execution or authoritative evidence is unavailable. Static risks may be listed, but they are not presented as observed failures. |
Every report uses the same compact evidence shape:
Verdict: REPEAT-SAFE | DUPLICATES | DIVERGES | NOT TESTED
Intent contract: <scope, stable ID, attempt ID, payload binding>
Allowed effects: <effect -> expected count>
Observed effects: <effect -> count and authoritative evidence>
Scenarios: <retry, replay, concurrency, restart, crash, controls>
Finding: <first failing boundary or why evidence is incomplete>
Change: <implemented fix or none>
Residual risk: <untested boundary and safest next step>
Run destructive scenarios only against an isolated environment, sandbox, fake, or controlled fixture. Charges, refunds, deletes, emails, provisioning, and irreversible transitions are unsafe by default. If the boundary cannot be exercised safely or counted authoritatively, stop before mutation and report NOT TESTED.
In one reproducible paired snapshot, the same model reviewed the same 16 repository fixtures with and without the skill:
| Metric | Without skill | With Run It Twice |
|---|---|---|
| Correct verdict | 10 / 16 (62.5%) | 16 / 16 (100%) |
| Correct restraint when execution evidence was missing | 1 / 3 (33.3%) | 3 / 3 (100%) |
False REPEAT-SAFE verdicts |
0 | 0 |
| Decisive-signal recall | 91.7% | 97.9% |
| Scenario recall | 97.9% | 99.1% |
| Decisive-evidence coverage | 100% | 96.9% |
The snapshot used gpt-5.6-luna at low reasoning through codex-cli 0.147.0, one run per cell, on August 19, 2026. Baseline and treatment used the same fixtures, schema, model settings, and common task prompt; treatment additionally received the committed skill and the separately recorded instruction Use $run-it-twice for this review.
Inspect the raw paired result, cases, scoring contract, and full methodology. Revalidate every recorded hash and score locally:
node benchmark/check.mjsThis is a synthetic repository-artifact review with a declared, non-secret holdout. It does not execute or repair real applications, prove exactly-once behavior, or estimate population-level model quality. Model output is nondeterministic, and one run per cell is a smoke snapshot—not a stable universal performance estimate.
To print the frozen 32-cell plan without calling a model:
node benchmark/run.mjs --dry-runThe benchmark measures review behavior, not whether any target system is repeat-safe. That verdict still requires evidence from the system under review.
Does this prove exactly-once execution?
No. It verifies a declared observable outcome against the failure boundaries that were actually exercised. The claim stays deliberately narrower than exactly-once execution.
Is an idempotency key enough?
No. The key still needs correct scope, durable payload binding, an atomic claim, deterministic conflict behavior, safe retention, and propagation or reconciliation across downstream authorities.
What counts as an authoritative effect?
The acceptance point that owns reality: a committed row, ledger entry, accepted provider charge, inventory transition, broker record, sent message, created file, or provisioned resource. Handler calls, log lines, mocks, and HTTP responses alone do not establish the count.
Will it mutate production to test retries?
It should not. The workflow requires an isolated target for destructive scenarios and returns NOT TESTED when safe execution or authoritative evidence is unavailable.
Can it help repair a failure?
Yes, when repair is in scope. It looks for the narrowest broken identity, ownership, atomicity, or recovery boundary, adds a regression test, and re-runs the relevant matrix. It does not prescribe one universal mechanism.
- OpenAI: Build skills — skill structure, discovery locations, and invocation.
- Open Agent Skills specification — the portable skill format.
- Skills CLI — cross-agent installation and discovery.
- RFC 9110 §9.2.2: Idempotent Methods — the HTTP semantics baseline.
- Amazon Builders' Library: Making retries safe with idempotent APIs — caller intent, retries, and late-arriving requests.
- Stripe API: Idempotent requests — a production API contract for keys, stored outcomes, and parameter conflicts.
- PostgreSQL: Constraints — authoritative uniqueness and integrity constraints.