queue_clarification

Category: intel
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Generates an AWAITING_HUMAN block with focused clarification questions for a chunk. Call it to lock ambiguous context until a human answers.

Arguments

Required: chunk_ref.

Optional: max_questions.

chunk_ref.
max_questions. Note: Capped at 5; defaults 5.

Result

Object with chunk_id, state (awaiting_human), questions array (id, text, type, priority), and the awaiting_human_block text. Question types are scope, time, semantics, action, downstream_use.

Boundaries

Operates inside the selected profile boundary. Frozen chunks are refused; all other states may be queued.

Lifecycle / side effects

Persists up to five typed open questions with history events, writes the AWAITING_HUMAN annotation block, moves the chunk toward awaiting_human where the transition is legal, and records a run-history entry. All-or-nothing.

Errors

Missing chunk_ref rejected by validation. Unknown chunk returns not-found. Frozen chunks return a cannot-queue error payload.

Example

{
  "chunk_ref": "<uuid>",
  "max_questions": 3
}

Result shape:

{
  "awaiting_human_block": "--- AWAITING_HUMAN ...",
  "chunk_id": "<uuid>",
  "questions": [
    {
      "id": "<uuid>",
      "priority": 0.9,
      "text": "Which workflow does this relate to ...?",
      "type": "scope"
    }
  ],
  "state": "awaiting_human"
}