Escalating to a Human

A handover note

Some stops need a person: repeated failures, ambiguous goals, or risky actions. A good handover includes the goal, what was tried, the last error, the current state and a suggested next step. Without that, the human has to re-read the whole transcript.

A structured handover

A fixed structure makes handovers easy to read and to route automatically, for example into a ticket.

{
  "status": "needs_human",
  "reason": "3 consecutive tool failures",
  "goal": "Migrate users table to the new schema",
  "tried": ["ran migration 0042", "retried with --fake-initial"],
  "last_error": "permission denied for table users",
  "state": { "step": 7, "tokens_used": 63000 },
  "suggested_next": "Grant ALTER on users to the migration role, then resume"
}

Quick check: What makes a handover note most useful?

• Only the words "please help"
• Goal, what was tried, last error, state and a suggested next step
• The complete raw transcript
• A random log line