AI SURFACE AREA SPEC (1-PAGE)

Use this to spec any AI workflow (assistant, agent, copilot) before it ships. Keep it short. If you can’t fill a section, that’s a product gap.

1) WORKFLOW
- Name:
- User persona (who triggers it):
- Primary job-to-be-done (one sentence):
- “Done” definition (observable outcome):

2) DATA ACCESS (READ)
- Sources the AI can read (systems, object types):
- Scope rules (per workspace? per project? per record ownership?):
- Sensitive data exclusions (e.g., payroll, secrets, private notes):
- User-visible disclosure: where do you show what was accessed?

3) ACTIONS (WRITE)
List every write action as: VERB + OBJECT + CONSTRAINT.
Example: “update CRM field” constrained to {stage, next_step} only.
- Allowed write actions:
- Disallowed write actions:
- Human approval required for (be explicit):

4) PROVENANCE & EXPLAINABILITY
- What citations are shown (doc links, record links, timestamps):
- How users verify quickly (UI affordance):
- What you do when no reliable source exists (block, ask user, or answer with warning):

5) ESCALATION & FALLBACKS
- If the AI is uncertain: (ask clarifying question / propose options / stop)
- If tools fail (timeouts, permissions, rate limits): (retry policy + user message)
- If policy blocks content/action: (what user sees + how to proceed)

6) EVALS (RELEASE GATE)
- Golden tasks (5–20 examples) that match real user work:
- Pass/fail criteria for each task (qualitative is fine, but explicit):
- Regression trigger: what changes require re-running evals? (model change, prompt change, tool change, retrieval change)
- Rollback plan if evals fail in production:

7) AUDIT LOG (USER-FACING)
Minimum fields you will store and expose:
- Intent (plain language)
- Sources consulted (links)
- Planned actions (preview)
- Execution results (success/failure + reason)
- Rollback path (undo button or steps)

8) COST BOUNDARIES
- Who pays (seat, workflow, usage):
- Admin controls (caps, disabling high-cost actions, alerts):
- User controls (confirm before expensive action, “draft only” mode):

9) SAFETY & ABUSE
- Obvious abuse cases (prompt injection via docs, data exfil, harmful content):
- Mitigations you will ship now (input sanitization, allowlists, policy filters):
- What you will not support (explicitly):

SIGN-OFF
- Product owner:
- Engineering owner:
- Security/privacy reviewer (if applicable):
- Date: