AI CONTRACT SPEC (ONE WORKFLOW) — TEMPLATE

Goal
- Name the workflow:
- User job-to-be-done (one sentence):
- What “done” means (observable outcome):

1) Scope and Non-Goals
- In scope:
- Out of scope:
- Explicitly forbidden behaviors (e.g., send email, delete records, create users):

2) Inputs (Contract)
- Allowed input sources (UI fields, specific documents, specific systems):
- Max input size rules (token/character limits; truncation behavior):
- Redaction rules (PII/PHI/secrets):
- Required fields:
- Optional fields:
- Input validation (what gets rejected, what gets sanitized):

3) Outputs (Contract)
- Output type: (JSON only / tool call only / human-readable text + citations)
- Output schema (list keys and allowed enums):
- Required citations? If yes, define allowed sources and citation format:
- Output validation rules (reject if missing keys, unknown enums, empty fields):
- User-facing presentation rules (tone, length caps, prohibited language):

4) Tools and Permissions
- Tool whitelist (each tool has name, description, required args, allowed arg ranges):
- Permission model (roles allowed to invoke each tool):
- Argument validation rules (server-side, before execution):
- Idempotency plan for write actions (keys, dedupe strategy):

5) Failure Modes and Fallback UX
- Refusal: what the UI shows, what user can do next:
- Invalid output (schema fail): retry policy and user messaging:
- Timeout / rate limit: backoff behavior and user messaging:
- Low-confidence handling (what threshold triggers handoff; define signal you use):
- Human handoff path (who, how, what context is passed):

6) Observability and Audit
- What to log (inputs, redactions, tool calls, outputs, model name/version, timestamps):
- Correlation IDs (trace a single user request across systems):
- Retention policy (duration and deletion behavior):
- Export requirements (what customers can download, in what format):
- Access controls (who can view logs; admin roles):

7) Testing and Release Controls
- Golden test set (small set of representative cases; store expected structured outputs):
- Regression plan for model updates (pin versions where possible; staging gate):
- Abuse tests (prompt injection attempts; tool misuse attempts):
- Rollout (feature flag, allowlist, staged deployment):

8) Operational Controls (Admin)
- On/off toggle per workspace/account:
- Model/provider selection policy (if exposed):
- Data-sharing settings (training usage, if applicable):
- Rate limits per user/workspace:

Definition of Done (must be true before GA)
- Output validator blocks non-conforming responses.
- Tool permissions enforced server-side.
- Clear fallback UX exists for refusal, invalid output, and timeouts.
- Audit logs are accessible to admins and exportable.
- Regression tests run before model/version changes.