Verified Workflow Spec (VWS) — One-Page Template

Use this before you ship any feature where an AI system reads sensitive data or takes external actions (email, tickets, code, payments, admin changes). The goal is a workflow you can operate, audit, and constrain.

1) Workflow Name + Owner
- Name:
- Business owner (team / role):
- Engineering owner:
- On-call/incident owner:

2) Scope (what this workflow is allowed to do)
- Systems it can read (exact systems):
- Systems it can write to (exact systems):
- Hard exclusions (what it must never touch):

3) Actions (the verbs)
For each action, fill a row:
- Action: (e.g., “create Jira ticket”, “open GitHub PR”, “send email”, “issue refund”)
- Reversible? (Yes/No)
- If reversible: compensating action (e.g., revert PR, void invoice)
- Required auth mechanism: (OAuth app, GitHub App, cloud IAM role, service account)
- Required token scope / permissions:

4) Approval Rules
Define where humans must approve.
- Always require approval for (irreversible actions):
- Conditional approvals (thresholds, domains, environments):
- Who can approve (roles/groups):
- How approval is recorded (UI event, signed request, ticket comment):

5) Policy Checks (machine-enforced)
- Authorization policy engine (OPA/Cedar/other):
- Required checks before action executes:
 - Identity present + session freshness:
 - Least-privilege scope verified:
 - Destination allowlist (domains/repos/projects):
 - Rate limit / circuit breaker:

6) Audit Log Fields (minimum viable evidence)
Log these for every step:
- Correlation ID / workflow run ID
- Actor (user/service) + tenant/account
- Input payload (sanitized as needed)
- Retrieved sources (IDs/links, not just pasted text)
- Model identifier + prompt/template version
- Tool call name + parameters
- Policy decision result + policy version
- Approval events (who/when/what changed)
- Output/side effect result (IDs, links)
- Errors, retries, timeouts

7) Failure Modes + Response
- Known bad outcomes (wrong recipient, wrong repo, wrong customer record):
- Detection signals (alerts, anomaly checks, user reports):
- Automated stops (circuit breakers, disable switch):
- Manual rollback steps (clear checklist):

8) Environments + Rollout
- Sandbox mode (what’s simulated):
- Staged rollout plan (who gets it first):
- Kill switch (where it lives, who can use it):

If you can’t fill this template in under an hour, the workflow is too vague. Narrow the scope until it becomes spec-able—and then ship it.