messaging-the-human · diff
git:20260826.bdc404f to git:20260830.72d9747
65 added, 104 removed. Audit A to A.
---
name: messaging-the-human
- description: |
- When and who should send a message to the human operator, at
- operator-human@your-rig — which routes straight to his Slack. Role-gated:
- orchestrators and PMs use discretion to send anything worth his attention
- (blockers, ships/completions, changes, good news); every other agent may
- message him ONLY for a real blocker he can personally unblock, and routes
- everything else through an orchestrator. Use to protect a scarce human's
- manage-by-exception attention. NOT for agent-to-agent coordination (send/queue
- a peer) or durable agent work-handoffs (use the queue to the owning seat).
+ description: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
metadata:
+ cli_surfaces_referenced:
+ - gateway human add
+ - gateway human list
+ - queue block
+ - queue handoff
+ - queue transitions
+ - send
openrig:
- stage: provisional # operator-directed, freshly authored 2026-07-30; hardens as agents use it
- audience: ALL agents (universal); orchestrators + PMs are the primary discretionary senders
+ stage: provisional
+ audience: all agents
sibling_skills:
- queue-handoff
- - status-not-chat-orchestrator
- human-in-the-loop
- openrig-user
---
# Messaging the Human
- ## The one-line mechanism
-
- ```bash
- rig send operator-human@your-rig "your message"
- ```
-
- That goes straight to the human's Slack — that is the *how* for **text**. For **images**
- (screenshots, renders), send through the **image connector** instead; text and images are separate
- live channels today (a release upgrade will unify them). Either way the *how* is trivial; everything
- below is the *when* and the *who* — the part that actually matters.
-
- ## The mental model: the human is a scarce attention resource managing by exception
-
- There is one human. He is single-threaded across many agents, so his attention
- is the bottleneck of the whole system. He operates **by exception**: he wants to
- be pulled in when it genuinely matters and left alone when it doesn't. Every
- message you send spends a slice of that scarce attention.
-
- So the rule is not "can I reach him" (you can, trivially — one `rig send`). The
- rule is **should this reach him, coming from me**. Two things decide that: **who
- you are** (your role sets how much of his attention you're trusted to spend) and
- **what it is** (does it clear the bar for that role). Get the altitude wrong in
- either direction and you fail him: spam his Slack with noise, or sit silently on
- something he needed to know or could have unblocked.
-
- ## WHO sends WHAT
-
- ### If you are an ORCHESTRATOR or a PRODUCT MANAGER — use discretion
-
- You are the primary channel to the human. You may send **more than blockers** —
- anything you judge he would want to know:
+ The human is an addressable participant, but their attention is scarce and they
+ may not be at a terminal. Anything that must survive their absence needs a
+ durable queue row; the gateway turns the human blocker on that row into the
+ external notification.
- - something **shipped**, **completed**, or a **milestone** was hit
- - something **important happened**, or something **changed**
- - **environmental** changes (infra, hosts, tools, external state)
- - **good news**
- - anything that needs his attention, or is simply **good for him to know**
+ Any seat may contact the human directly for a real escalation. Orchestrators
+ and product managers may also send updates they judge the human would want to
+ know. Do not add a routing intermediary merely because of your role.
- There is no hard trigger here — it is judgment, and you are trusted with it. The
- test is: **"would he want to know this?"** If yes, send it. Lean toward sending
- genuine signal and real good news; do not manufacture noise or narrate routine
- churn. Discernment is the skill: you are curating his attention, not flooding it.
+ ## The supported route
- ### The v0 event classes — reach out on these, unprompted
+ First discover the registered human identity. Never invent or remember an
+ address:
- "Use discretion" left the *when* unspecified, so it did not happen — the channel exists and nobody
- reaches for it. Here are the **named event classes** that should trigger a proactive message —
- anchors for the judgment, not an exhaustive gate:
+ ```bash
+ rig gateway human list --json
+ ```
- - **Model-fallback boots** — a seat that came up on a fallback model instead of its pinned one. Send
- on **every occurrence**; a silent downgrade is exactly what the human needs to see.
- - **Capacity / authority requests** — you need a fork/spin-up authorization, a spend-or-limit call, or
- any authority only the human holds. This is a **guaranteed-answer** path — don't sit blocked on it.
- - **Security-category flags** — anything in the security / consequence-boundary class.
- - **Acceptance / milestone moments** — a slice proven, a release cut, a real "it's done and it works."
- - **Human-addressed work blocked beyond its settle window** — a decision or request routed to the
- human that has sat past the time it should have moved.
- - **Idle / stall alarms** — the line stopped and isn't resuming (the idle-detector's signal).
+ Use the returned `humans[].address`. If no unambiguous registered human is
+ returned, stop: registration is lifecycle work (`rig gateway human add
+ --help`), not an address to guess.
- These are v0, drawn from real rulings; treat them as the anchors that make the *when* concrete. New
- classes earn their place the same way — from a real event the human wanted to know about.
+ Keep the work row owned by the agent who must resume it, then park that row on
+ the registered human:
- **Why this is a norm, not a nicety — WORKS ≠ USED.** A channel that *works* is not a channel that is
- *used*. This path is proven only when agents **reach for it unprompted** across the lifecycle — a
- boot, a blocker, a ship, an alarm. If the channel exists and nobody reaches for it, the human is
- blind by default. Reaching out on these classes is the job, not an interruption of it.
+ ```bash
+ rig queue block <qitem-id> --on <registered-human-address> \
+ --summary "<decision owed>" \
+ --evidence-ref "<durable artifact the human should judge>" \
+ --continuation "<what resumes after the answer>"
+ ```
- ### If you are ANY OTHER agent — blockers only
+ The gateway resolves the registered human to the configured connector, sends
+ the Slack notification, and records its receipt on the same row. Confirm the
+ effect from the append-only history:
- You may message the human **only** when you are **blocked** and **he** is the one
- who can unblock you. That authority is universal — you do **not** have to be an
- orchestrator to raise a real blocker. But a blocker is the **only** thing you may
- send him directly.
+ ```bash
+ rig queue transitions <qitem-id>
+ ```
- For anything that is **not** a blocker — an update, an idea, a question, an
- interesting finding — do **not** message the human. Send it to your
- **orchestrator**, who decides whether it is the human's role to handle or whether
- it is handled another way. The orchestrator/PM layer is the filter that protects
- the human's attention; routing through it is how the system keeps his queue at
- manage-by-exception altitude.
+ The row is the obligation and the audit trail. Slack is the attention leg. A
+ reply resolves the durable blocker and wakes the row owner; it does not create
+ a second private work stream.
- ## What counts as a real blocker (for non-orchestrator / non-PM agents)
+ ## When to use it
- You are **blocked** AND **only the human** can clear it:
+ Escalate directly when only the human can supply the missing capability:
- - a **decision** only he can make,
- - **access / a credential / an authority** only he holds,
- - an **external action** only he can take (something in the real world, an
- account or service he owns).
+ - a decision or irreversible judgment only they own;
+ - access, credentials, authority, or capacity only they can grant;
+ - an external action only they can perform;
+ - a security-class or provider/model-fallback event they need to know about.
- Not a blocker: "I'd like a second opinion," "which approach do you prefer,"
- "here's a cool thing I found." Those go to your **orchestrator**. And if an
- orchestrator or PM *could* unblock you, route to them first — reserve the human
- for what genuinely only he can do.
+ Orchestrators and product managers may additionally send meaningful milestone,
+ environment, or completion updates. Prefer signal over routine narration.
- ## How to write it (so it earns the interruption)
+ ## Boundaries
- - **Lead with the point.** Blocker: what is blocked + exactly what you need from
- him. Update: the headline first, detail after.
- - **Full absolute paths.** No internal jargon he can't parse. **No backticks** in
- `rig send` bodies (they trigger shell substitution).
- - `rig send` is an **ephemeral conversation** to his Slack. For a durable *agent*
- work-handoff, use the queue to the owning seat — not the human.
+ - `rig send` sends text to an agent's terminal. It is not the Slack route and
+ does not create a durable human obligation.
+ - An unregistered or ambiguous human identity must fail loudly. Register or
+ repair the identity; never downgrade it to an agent seat or a guessed
+ `@external` address.
+ - Agent-to-agent work that needs closure uses `rig queue handoff`, not this
+ human-blocker path.
+ - Deferred work that is not imminent belongs in the mission workspace, not on
+ the queue.
- ## Quick reference
+ ## Writing the escalation
- | You are… | You may send the human… |
- |---|---|
- | Orchestrator / PM | anything worth his attention — blockers, ships, completions, changes, good news (your discretion) |
- | Any other agent | a real blocker only he can unblock — **and nothing else** (everything else → your orchestrator) |
+ Lead with what is blocked and the exact decision or action needed. Point at the
+ durable evidence instead of pasting a second copy, and name the continuation so
+ the system can resume the right work when the answer arrives.