designing-hitl-workflows
Designs human-in-the-loop (HITL) checkpoints for AI agent workflows — deciding where to pause for human approval, structuring the approval interface, handling timeouts and non-responses, and building
SKILL.mdplugins/loxihart-ai/skills/designing-hitl-workflows/SKILL.md
GitHubHITL Workflow Design
The purpose of HITL is not to slow down automation — it's to build trust in automation by making the right actions safe to delegate and keeping humans in control of the actions that aren't.
An agent that always asks for approval isn't autonomous. An agent that never asks isn't trustworthy for consequential work. HITL is the design discipline that determines which is which.
Decision Tree
What are you building?
│
├─ Where should I put checkpoints in this workflow?
│ → Section 1: Checkpoint Placement Framework
│
├─ What should the approval interface look like?
│ → Section 2: Approval Interface Patterns
│
├─ What happens if the human doesn't respond in time?
│ → Section 3: Timeout and Escalation Handling
│
└─ I'm implementing HITL in n8n / Claude API / Base44
→ references/hitl-patterns.md (implementation patterns)
Is HITL required here?
Run this gate on each action the agent can take:
Is the action irreversible OR high-consequence OR affects a non-consenting third party?
├─ YES → HITL checkpoint REQUIRED (Section 1: "always checkpoint")
└─ NO → Is it a high-volume batch whose aggregate undo cost is high?
├─ YES → HITL checkpoint REQUIRED (batch approval)
└─ NO → No checkpoint; log and monitor, or automate freely
Section 1: Checkpoint Placement Framework
Place checkpoints based on two dimensions: reversibility and consequence.
HIGH CONSEQUENCE
│
CHECKPOINT │ ALWAYS CHECKPOINT
if high volume │ (mandatory human review)
│
LOW ─────────────────────────────────────────── HIGH
REVERSIBILITY │ REVERSIBILITY
│
AUTOMATE │ LOG AND MONITOR
freely │ (audit trail, no pause)
│
LOW CONSEQUENCE
Always checkpoint (high consequence, low reversibility):
- Sending emails to external clients on behalf of a human
- Creating or modifying contracts, invoices, or financial records
- Publishing content to a live site or social channel
- Deleting records, files, or data
- Committing code to a protected branch
- Any action affecting a third party who didn't consent to automation
Checkpoint if high volume (low consequence, but many at once):
- Batch operations: tagging 500 contacts, updating 100 records
- Even if each action is individually reversible, the aggregate effort to undo justifies a checkpoint
Log and monitor (high reversibility, low consequence):
- Internal drafts, staging changes, read operations
- Classification, summarization, analysis without side effects
Automate freely (low consequence, fully reversible):
- Formatting, categorizing, enriching data
- Generating options for human selection
- Any operation that produces output without acting on it
The "surprised" test
Before finalizing checkpoint placement: would a reasonable client be surprised to learn this action happened automatically without their knowledge? If yes: add a checkpoint.
Section 2: Approval Interface Patterns
Required output template — minimum viable approval message
Every approval request MUST answer:
- What action is about to happen? (specific, not "send email")
- What is the target? (who/what will be affected)
- Why is the agent doing this? (one-sentence reasoning)
- What are the options? (Approve / Reject / Modify)
- What happens if no response? (default behavior on timeout)
Template:
🔔 Approval Required
Action: Send proposal email to Marcus Webb (marcus@acmecorp.com)
Reason: Discovery call completed — agent generated follow-up proposal
based on call notes. Budget: $8,500, SOW attached.
[Approve] [Reject] [Edit before sending]
No response in 4 hours → action will be paused, not sent.
What to avoid
- Vague summaries ("Agent wants to proceed") — never acceptable
- Binary approve/reject without a modify path for consequential actions
- Defaulting to approval on timeout (see Section 3)
- Approval requests to Slack/email without a direct action link
- Multiple pending approvals in one message thread — each request must be its own isolated message with its own action buttons
Section 3: Timeout and Escalation Handling
Default on timeout: pause, never proceed.
An agent that proceeds without approval when the human doesn't respond is not a HITL system — it's an automated system with a courtesy notice. The default on timeout must be to pause the workflow and hold state.
Timeout ladder
T+0:00 → Approval request sent (primary channel: Slack DM or email)
T+1:00 → Reminder with escalating urgency language
T+4:00 → Escalation to secondary contact (if defined)
T+24:00 → Workflow paused, task queued for manual review
T+72:00 → Task expires, logged as "requires re-initiation"
Adjust timeframes to workflow urgency. A client-facing proposal can wait 24 hours. A time-sensitive booking might need 30 minutes.
Escalation path configuration
Every HITL workflow should define:
primary_approver: [EMAIL]
secondary_approver: [backup contact or team channel]
timeout_minutes: 240
on_timeout: pause # never: auto-approve
escalation_message: "Action pending approval for 4 hours — needs review"
Implementation Patterns
Platform-specific implementation — n8n Wait nodes, Claude API tool-based HITL / stop sequences, and the Base44 approval queue panel — lives in references/hitl-patterns.md. Place the checkpoints here (Sections 1–3), then wire them up there.
Self-Verification
- Every checkpoint placement justified by the reversibility/consequence matrix
- Every approval message answers all 5 required questions
- Timeout default is pause (never auto-approve)
- Escalation ladder defined for every HITL workflow
- "Surprised" test passed for all un-checkpointed consequential actions
CLAIMS
- Defaulting to auto-approve on timeout defeats the purpose of HITL and creates liability for the agent operator — pause is always the correct default
- Binary approve/reject without a modify path leads to approval fatigue; reviewers begin approving blindly when they can't easily correct
COUNTEREXAMPLE
- For very high-frequency, low-stakes operations (tagging 1000 newsletter subscribers), per-item HITL is impractical; batch approval with sampling review is more appropriate
CONTRADICTIONS
- Full HITL on every consequential action conflicts with automation ROI for high-volume workflows; the resolution is batching and sampling, not eliminating checkpoints