Refusal-First AI Feature Spec (One-Page)

1) Feature + user job
- Feature name:
- Primary user job it supports (one sentence):
- Highest-stakes outcome if wrong (e.g., sends email, edits code, changes billing):

2) Define the “allowed set” (what the AI is permitted to do)
- Allowed content/actions:
- Disallowed content/actions:
- Domains that require extra gating (legal, medical, finance, HR, security):

3) Refusal modes (write these before the happy path)
A) Safety refusal (hard no)
- Triggers (specific):
- User message (short):
- Next-step buttons (2–3):

B) Competence refusal (soft no)
- Triggers (missing context, low evidence, ambiguous request):
- User message that states boundary (“I don’t have X” / “I can’t verify Y”):
- Fastest path to proceed (single input):
- Acceptable fallback (draft, outline, checklist, question set):

C) Economic refusal (budget-aware no)
- Triggers (large scope, expensive tools, long context, repeated retries):
- User message that offers choices:
- Cheaper alternatives (narrow scope, sample, ‘lite mode’):
- Hard limits (timeouts, max tool calls, max retries):

D) Permission refusal (access-aware no)
- Triggers (missing integration, missing workspace permission, restricted doc):
- User message:
- Request-access flow owner (admin / user / IT):

4) Deterministic gates (enforced by the app, not the model)
- Policy check location (before planning / before execution):
- Permission check location:
- Approval requirement (what actions require explicit confirmation):
- Tool execution bounds (timeouts, retry policy, rate limits):

5) Evidence & scope transparency
- What the UI will state about scope (which docs/tools were used):
- Citation approach (links to source docs, record IDs, or query summary):

6) Telemetry (minimum viable)
Log these fields for every AI request:
- Refusal type (none/safety/competence/economic/permission)
- Scope statement (doc set/tool set in-bounds)
- Tool-call trace (tools called + errors)
- User next action (narrowed request, connected integration, escalated to human, abandoned)
- Outcome flag (user accepted output, edited heavily, reverted, reported issue)

7) Release checklist
- Red-team prompts for your domain (10 examples):
- “Runaway cost” scenarios tested (3 examples):
- Permission boundary tests (at least: no access, partial access, expired token):
- Support playbook: what agents say when refusal feels wrong

If you can’t fill this out in one sitting, your feature is too vague. Reduce scope until refusal behavior is obvious and testable.