ai-human-handoff-contract · diff
git:20260911.25436b5 to git:20261005.2bc0998
72 added, 12 removed. Audit A to A.
---
name: ai-human-handoff-contract
- description: "Define and test when an AI workflow must hand a task to a human, preserving evidence and preventing unapproved continuation."
+ description: "Define and test AI→human handoff as a versioned state machine with multi-signal triggers, review packets, approval binding, and no silent consent. Use for escalations, approvals, and irreversible agent actions."
category: development
risk: safe
source: self
source_type: self
date_added: "2026-09-11"
- tags: ["ai-workflows", "evaluation", "ai-human-handoff-contract"]
+ tags: ["ai-workflows", "handoff", "escalation", "human-in-the-loop", "approval", "sla"]
tools: ["claude", "cursor", "gemini", "codex"]
---
- # Human Handoff Contract
+ # AI Human Handoff Contract AI Skill Guide (Claude)
- ## Scope
+ ## Overview & Engine Architecture
- Identify decision ownership, irreversible actions, required evidence, and the human review channel. Derive handoff triggers from application requirements rather than model confidence alone. Keep thresholds configurable by the authorized owner.
+ Handoff is **architecture**, not a confidence fallback. Model confidence ≠ risk. Production contracts combine deterministic policy triggers, UX friction signals, and calibrated scores—with a **never-auto** list no score can override.
- ## Procedure
+ Claude operates as a Principal Agent Operations Designer for **state machines**, **multi-signal escalation**, **minimum-sufficient review packets**, and **approval binding**.
- Define states such as active, awaiting_review, approved, rejected, and expired. Specify which actions remain permitted in each state and who may transition it. An agent must not approve its own pending action.
+ ```
+ ┌─────────────────────────────────────────────────────────────┐
+ │ Triggers → state (active|awaiting_review|approved|…) │
+ │ → review packet → human transition → resume or stop │
+ │ Silence / timeout ≠ approval │
+ └─────────────────────────────────────────────────────────────┘
+ ```
- ## Checks
+ ---
- Prepare a review packet containing the user's request, relevant evidence, proposed action, uncertainty, and expiry. Minimize personal data and exclude credentials. Link evidence rather than dumping an entire conversation where possible.
+ ## Actions the contract must name
- ## Failure Handling
+ | Action | When |
+ | :--- | :--- |
+ | **Resolve** | Low risk, covered knowledge |
+ | **Clarify** | Ambiguous; budget N questions |
+ | **Route** | Wrong team/queue |
+ | **Escalate / approve** | Judgment, high stake, policy |
+ | **Stop** | Would require unauthorized guess |
- Test missing evidence, unavailable reviewers, conflicting approvals, expiry, cancellation, and duplicate notifications. Bind approval to the reviewed action and inputs; material changes require renewed review.
+ ---
+ ## Triggers (multi-signal; per-intent thresholds)
+
+ - Explicit human request (always honor)
+ - Policy/risk flags (refunds, legal, medical, money movement)
+ - Loop detection (N turns unresolved)
+ - Sentiment / severity / account tier / $ value
+ - Tool/schema failure / citation verify fail
+ - Calibrated confidence **per intent** (verify calibration first)
+ - **Never-answer list** (hard escalate/stop)
+
+ Owner configures thresholds; agent must not self-approve.
+
+ ---
+
+ ## States & rules
+
+ `active → awaiting_review → approved|rejected|expired|cancelled`
+
+ - Define permitted tools per state (mutating tools blocked while awaiting).
+ - Bind approval to **hash(action + critical inputs)**; material change → re-review.
+ - Timeout policy: pending stays pending or expires—**never** auto-approve on silence.
+ - Unavailable reviewer → fallback queue + user messaging.
+
+ ---
+
+ ## Review packet (minimum sufficient)
+
+ User goal · verified facts · evidence links · actions attempted · proposed action · uncertainty/risk reason · expiry/SLA · owner · workflow version. Minimize PII (`@ai-pii-redaction-review`). Prefer links over full transcript dumps.
+
+ ---
+
+ ## Tests required
+
+ Missing evidence · reviewer unavailable · conflicting approvals · expiry · cancel · duplicate notify · approval after input mutation · agent attempting self-approve.
+
+ ---
+
## Deliverable
- Deliver the state contract, test cases, and a concise reviewer-facing template. A timed-out approval stays pending or expires according to policy; silence is not permission.
+ Versioned contract YAML/doc + eval cases + reviewer template. Weekly calibration: false escalations vs misses; promote incidents into `@ai-evaluation-dataset`.
+ ## Related skills
+
+ `@prompt-regression-gate`, `@llm-json-contract-check`, `@ai-pii-redaction-review`, `@ai-citation-verification`
+
+ ## Agent Operational Directive
+
+ > **MANDATORY**: Derive triggers from risk, not confidence alone. Block irreversible actions without bound approval. Silence is not permission. Agents cannot approve themselves.
+
+ ## Sources
+
+ Human escalation architecture briefs; multi-signal CS handoff guides; per-intent confidence calibration playbooks; agent-led escalation patterns.