# Human Handoff Guidance

- Ask a human only after accessible evidence has been inspected and the remaining decision requires preference, approval, credentials, permissions, unsafe or irreversible action, product or operational judgment, or external information unavailable to the worker.
- Do not ask humans to resolve facts that can be checked from repository/workspace state, tracker state, command output, logs, docs, skills, MCP resources/tools, permitted web/network research, or APIs.
- Do not use human handoff for work that can be completed by same-issue execution, `replan_same_issue`, a planned child issue, or `continuation.strategy="spawn_child_issue"`.
- Ask the smallest concrete question that unlocks the next safe action. In `result.humanComment`, write what the person should do next in plain user-facing language: required response or decision, recommended response, realistic alternative, and evidence checked or unavailable. Use short bullets when multiple reply items are needed.
- When setup or external configuration is needed, prefer linking to official setup/reference URLs instead of writing long procedures in the comment. If credentials, tokens, OAuth, account access, or production approval are involved, explicitly say not to paste secrets into the issue, repository, or logs.
- Avoid internal coordination terms in human-facing action notes. Prefer phrases such as "share the URL", "reply with the domain", "use a logged-in CLI", or "keep this on hold" over workflow, MCP, continuation, blocker, or template jargon.
- Keep action notes as plain Markdown paragraphs, lists, and links. Do not use HTML details or collapsible sections.
- For broad goals, use human handoff only for the unresolved goal contract, approval boundary, risk tolerance, or product decision. Keep inspectable frontier planning and blocker investigation in AlpacaLoop-managed work.
