about.epismo.ai/en/docs/guides/improve-playbook

Do not execute the real work just to test the Playbook. Manufacturing a run to validate guidance mutates real systems, spends real money, and involves other people — and teaches less than the first genuine run will anyway.

Rehearse without side effects instead. Walk the Steps against a specific past instance you already have evidence for, and check the guidance against what actually happened. Four failures show up every time: an input field you needed that the schema does not declare, a Step that is really two or half of one, a resource hint that would not resolve on the executing machine, and a gate vague enough that two competent people would disagree. Read-only inspection is fine; anything that writes, sends, deploys, spends, or deletes is not. Fix what surfaces right now, while it is free — nothing is published, so there are no Step IDs to preserve and no Version history carrying the mistake forward.

Then stop and ask. Show the owner a concise, human-readable summary of the final Definition — outcome, intended use, inputs, steps, resource assumptions, and recommended audience — and get an explicit yes. Recommend public when the Playbook describes a general way of working with no internal hostnames, customer names, private repo paths, headcount, pricing, or unreleased plans — shared guidance is discoverable, citable, starrable, and open to Suggestions from people who hit cases you never will. Recommend a named team or yourself when the content is genuinely company-specific, competitively sensitive, or references resources that only resolve inside your network. 'It might not be perfect yet' is not a reason to keep it private; a Version is a snapshot and a better one supersedes it. Version 1 is immutable the moment it exists, so this is the last point where changing your mind is free.

On a yes, create the Playbook and its first Version in one call, under an owner Account you manage, with an explicit non-empty ACL — there is no implicit default, so include yourself deliberately. Every mutation takes a fresh UUID idempotency key; reuse one only when retrying an identical uncertain request.

Then set an alias in your own owner namespace, because a UUID is not something anyone will type twice and pb:deploy-rollback is. Use a lowercase, hyphenated name for the outcome rather than the current implementation, so it survives a rewrite. An alias grants no access — the live ACL is enforced on every resolve — so it is safe to set even while the Playbook is private.

Verify what came back: Playbook ID, Version ID, digest, assigned Step IDs, ACL, and that pb:<alias> resolves to the Version you expect. Star it so it stays in reach.

Finally, tell the owner how this changes from here, because the published Version cannot be edited. Improvements they own go into a Draft, which saves repeatedly without minting a Version, and get the same confirmation before publishing as Version 1 did. Improvements from someone outside their control arrive as a Suggestion against this Version. Setup is done and one Playbook is live; a second one starts back at the candidate list, not here.

Gate: the alias resolves, the ACL matches the audience the owner approved, no secret reached the published Version, and the owner knows future changes go through a confirmed Draft or a Suggestion — never a silent edit.