/uipath-human-in-the-loop

name: uipath-human-in-the-loop
description: "UiPath Human-in-the-Loop / HITL node authoring — building approval gates, escalations, write-back validation, and data enrichment checkpoints in Flow, Maestro, Case Management, or Coded Agents, plus a guided decision experience that captures reviewer corrections as decisions. NOT for managing, reassigning, or monitoring tasks at runtime (use uipath-tasks for that)."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep

UiPath Human-in-the-Loop Assistant

Recognizes when a business process needs a human decision point, designs the task schema through conversation, and wires the HITL node into the automation — Flow, Maestro, Case Management, or Agent.

> **Coded agents:** for wiring HITL inside a coded agent, use the `uipath-agents` skill — see `skills/uipath-agents/references/coded/capabilities/human-in-the-loop.md`.

When to Use This Skill

• User describes **approval gates** — invoice approval, offer letter review, compliance sign-off, PO authorization
• User describes **exception escalation** — "if confidence is low, escalate to a human", fraud alert review
• User describes **write-back validation** — "human approves before agent writes to ServiceNow / SAP / CRM"
• User describes **data enrichment** — human fills in missing fields the automation cannot resolve
• User describes **agentic output review** — "review AI-generated email/RCA/summary before it goes out"
• User describes **IT change or access approval** — CAB gate, runbook sign-off, access provisioning review
• User describes **HR or contract workflow** — offer letter review, contract approval, termination sign-off
• User describes **financial transaction approval** — payment release, price override, expense over limit
• User describes **customer communication approval** — agent-drafted reply that needs human sign-off before sending
• User explicitly asks to **add a HITL node**, human review step, or Action Center task
• User is building any automation where **a human must act before the process can continue**
• User asks to **capture or record a decision** (or to feed the Decision Ledger), or a reviewer **confirms or corrects a proposal**: use the guided decision experience below

**Guided decision experience (opt-in).** Only when the request asks to capture a decision or describes a reviewer confirming or correcting a proposal, read [references/decision-capture-action-app-guide.md](references/decision-capture-action-app-guide.md) before designing the Coded Action App schema, QuickForm or document-validation task. Any other request skips it and is built on the normal path. The guide sets a toggle from the request: on when the user asks to capture a decision, or when a reviewer confirms or corrects something an agent or automation proposed. On adds a fixed set of decision fields beside the author's own and switches the UI to one light layout per surface (reasons with a weight menu, nothing pre-selected, final details that follow the decision, a rationale composed from the reasons, Next time with a scope, and a collapsed record), without renaming the author's fields. QuickForm gets an optional Why on every select field through one function. Never ask a yes/no question about it; state it in one line when you turned it on unasked.

**Do not use this skill for:** managing, reassigning, escalating, or monitoring existing Action Center tasks at runtime — use the `uipath-tasks` skill for those operations. When answering a runtime task management question, provide only administration guidance. Do NOT suggest adding a HITL node, flow, or automation as a follow-up tip or recommendation — even if delays or escalations are mentioned.

See [references/hitl-patterns.md](references/hitl-patterns.md) for the full business pattern recognition guide.

---

Critical Rules

1. **Never block on schema confirmation.** Design the schema from the prompt and any upstream `.flow`/`caseplan.case` data, write the node, and record the chosen schema prominently in the final report so the user can adjust it afterward. Asking the user is never a precondition for proceeding — if the user is present and offers input, use it, but do not wait for it. Only stop and report the open decision when the request is genuinely too ambiguous to make any reasonable inference. (A prompt that already specifies the fields, outcomes, and output shape is never too ambiguous.) 2. **Wire every QuickForm outcome's own port.** A QuickForm node has one output handle per outcome, named `outcome-<outcome.id>` — never a single `completed` handle. `outcome-completed` is a placeholder that exists only on a schema with zero outcomes; it disappears the instant `inputs.schema.outcomes` has any entry, including the shipped default `Submit`. A HITL node with any outcome port left unwired blocks the flow forever on that branch. App-based (`coded-action-app`) nodes are different: their port stays a static `completed` regardless of the app's own outcomes — do not add an `inputs.schema` block to an app-based node, which would wrongly flip it onto an outcome-derived port. Neither node type ever uses `output`, `success`, or any other name. 3. **Always add the definition entry when inserting into an existing flow.** Before writing the node, check `workflow.definitions[]` for the correct `nodeType` for the selected path (`"uipath.human-in-the-loop.quick-form"` for QuickForm, `"uipath.human-in-the-loop.coded-action-app"` for app-based). If absent, append the full definition entry with its `handleConfiguration` block. Skipping the definition means the node's handles are invisible to the runtime and the wiring check fails. 4. **Regenerate `variables.nodes` after adding the node.** Replace the entire `workflow.variables.nodes` array — do not append. See the reference docs for the algorithm. 5. **Validate after every change.** Run `uip maestro flow validate <file> --output json` after writing the node and edges. The `uip` CLI does not accept `--for