Assistant-Grade Action Spec Template (copy/paste)

Goal
- Job to be done (one sentence):
- Deterministic end state (what exists/changes when done):
- System of record (where the truth lives):

User + Environment
- Primary user role:
- Where the user initiates (ChatGPT, Microsoft Copilot, Slack, IDE, browser):
- Related systems involved (e.g., Jira, GitHub, Salesforce, NetSuite):

Action Catalog (keep it small)
- Action name (verb-object):
- Description (what it does, what it does NOT do):
- Risk level (low/med/high):

Auth + Permissions
- Auth method (OAuth, API key, SSO-backed):
- Required scopes/roles (least privilege):
- Admin controls (enable/disable, scope restrictions):
- Revocation plan (token rotation, immediate kill switch):

Input Schema (tool contract)
- Required fields:
- Optional fields:
- Enums (status, priority, region, currency, etc.):
- Validation rules (length, format, allowed values):
- Redaction rules (never accept or return secrets):

Two-Step Safety (for medium/high risk)
1) Preview endpoint
- Input:
- Output must include:
 - plan_id
 - human-readable summary
 - machine-readable changes[] (diff-like list)
 - warnings[] (what could go wrong)

2) Commit endpoint
- Input: plan_id
- Idempotency key strategy (required):
- Failure modes (what errors can occur and how they surface):

Receipts (non-negotiable)
- What IDs are returned:
- Deep links returned (exact record URLs):
- Timestamp returned:
- Actor attribution (who/what executed: user + assistant + integration):
- Post-condition checks (how you confirm the write succeeded):

Audit + Observability
- Log fields: request_id, user_id, workspace/org, tool name, inputs (redacted), outputs (redacted), created/updated object IDs
- Export options (SIEM-friendly format if applicable)
- Rate limits and abuse controls:

UX Contract (inside the assistant)
- Confirmation text shown before commit:
- What the assistant should say on success (include receipt links):
- What the assistant should say on failure (actionable next step):

Test Plan (minimum)
- Happy path
- Invalid enum/value
- Permission denied
- Retry/duplicate (idempotency)
- Partial failure and rollback behavior
- Audit log verification

Launch Gate
- Security review completed (yes/no)
- Admin documentation written (yes/no)
- Support runbook (known errors, how to revoke, how to investigate) (yes/no)

Rule of thumb: if you can’t produce a receipt with IDs + links + an audit trail, you didn’t ship an assistant integration. You shipped a demo.