Retrieval Contract One-Pager (Template)

Purpose
Define a retrieval service that reliably returns defensible context for AI answers under real permissions.

1) Use Case (pick one)
- Workflow name:
- Primary user persona:
- Decisions/actions this will influence (be specific):
- “Hard fail” risk (what happens if it’s wrong):

2) Data Sources (explicit list)
For each source:
- System (e.g., Confluence, Google Drive, GitHub, Jira, Salesforce):
- Object types (pages, docs, issues, PRs, tickets, records):
- Ownership (team / system owner):
- Update behavior (human-edited, system-generated, append-only, etc.):
- Exclusions (what must NOT be indexed):

3) Identity & Permissions Model
- Identity provider (Okta, Azure AD, Google Workspace, etc.):
- How users map to each source’s ACLs:
- Group mapping approach:
- Policy rules that must be enforced at retrieval time:
- Red-line test: name 3 documents a specific user must never retrieve

4) Freshness & Versioning
- Freshness expectation per source (immediate / near-real-time / scheduled):
- Versioning strategy (store doc versions? timestamps? hashes?):
- What happens when access is revoked (retraction strategy):

5) Retrieval Runtime Contract
Inputs:
- user_id:
- query:
- allowed sources:
- max_results:
Outputs (required):
- doc_id (stable):
- doc_version:
- snippet text:
- snippet span (paragraph ID or character offsets):
- access decision (allowed/denied):
- metadata for filtering (type, owner, timestamp)

6) Ranking Strategy
- Candidate generation (dense, sparse, or hybrid):
- Metadata filters (required filters before scoring):
- Reranking approach (cross-encoder / LLM rerank):
- Fallback behavior if retrieval fails:

7) Evaluation Plan (non-negotiable)
- Golden set owner:
- Minimum test set size you can maintain (qualitative is fine):
- Failure taxonomy:
 * missing context
 * wrong context
 * wrong citation
 * policy violation
 * stale information
- Release gate: what must pass before shipping?

8) Observability & Audit
- What you log per request (retrieval bundle, filters applied, doc versions):
- Where logs live and retention policy:
- How to replay a bad answer:
- On-call / escalation path:

9) Acceptance Criteria (write it like a contract)
- “A user without access cannot retrieve restricted snippets” (how you test it):
- “Every answer must include citations to exact spans” (definition of exact):
- “We can explain any answer by replaying retrieval” (what data is required):

Sign-off
- Data owner(s):
- Security/privacy:
- Engineering owner:
- Date: