GOVERNABLE AI FEATURE SPEC — TEMPLATE (copy/paste)

1) Feature name
- Short name:
- Owner (PM/Eng):
- Launch surface (UI/API):

2) The decision (single sentence)
- “The system will ________ (action) given ________ (inputs) under ________ (constraints).”
- Decision type: read-only / write / external side-effect

3) Allowed actions and scopes (deny by default)
- Tools/functions exposed to the model:
 - Tool name:
 - Read or write:
 - Required user/workspace scope:
 - Max objects per call:
 - Forbidden fields/operations:
- Authentication model:
 - Per-user token? service token? both?
 - Expiry and rotation policy:

4) UX gating
- Mode: Draft → Review → Apply OR Plan → Execute OR constrained automation
- What the user must confirm (checkboxes, preview diff, recipient list, etc.):
- What the user can edit before apply:
- What happens on model uncertainty (fallback behavior):

5) Traceability (minimum viable trace)
- Trace ID generation point:
- Log/trace fields REQUIRED:
 - provider + model identifier:
 - prompt template version:
 - tool schema version(s):
 - retrieved context identifiers (doc IDs, record IDs):
 - tool calls (name + params) and tool responses (sanitized):
 - final output + post-processing steps:
- Data handling:
 - What must be redacted (PII, secrets):
 - Retention period:
 - Who can access traces:

6) Rollback plan (must exist before GA)
- What exactly can be undone:
- Mechanism:
 - object versioning / diff apply-back / compensating action / outbox cancel
- User-facing Undo UX:
- Operational rollback:
 - kill switch location (feature flag/config):
 - how to disable writes while keeping read-only value:

7) Safety and abuse
- Prompt injection exposure points (RAG docs, web content, user input):
- Hard rules:
 - Never execute tool X
 - Never send to external domain Y
 - Never modify field Z
- Rate limits and quotas:

8) Evaluation and release
- What constitutes a “correct” decision (clear rubric):
- Test set source (tickets, docs, synthetic cases) and storage:
- Regression checks for:
 - prompt changes
 - tool schema changes
 - model/provider changes
- Rollout plan:
 - internal → small cohort → wider release
 - monitoring signals to watch (error spikes, increased undos, policy denies)

9) Incident runbook (one page)
- How to find a bad decision (search by trace ID, user, time):
- How to reproduce (replay inputs + context IDs):
- First response steps:
 - flip kill switch
 - notify support
 - identify blast radius (which users/objects)
- Remediation steps:
 - rollback procedure
 - patch prompt/tool policy
 - add regression case

If you can’t fill sections 5 and 6 with confidence, you’re not shipping a feature. You’re shipping a liability.