# 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 decision or preparation, clear options, and evidence checked or unavailable. Use short bullets when multiple action items are needed.
- Write Needs Human comments for a non-engineer first. Avoid internal execution terms such as runner, workflow, MCP, continuation, blocker, token file, or environment unless the person already used them or the term is unavoidable. When a technical term is unavoidable, add a short plain-language explanation.
- When setup or external configuration is needed, include official setup/reference links with human-readable labels and one short note about what each page is for. Do not paste bare URL lists. Do not copy long procedures into the comment.
- When credentials, OAuth, tokens, account approval, or admin setup is needed, do not only say "configure the runner/environment." Say what the person should do in user-facing terms: ask someone with access to the service or admin console to prepare the credential or approval, use the project's safe secret-setting method, and explicitly say not to paste secrets into the issue, repository, or logs.
- Structure question handoffs as: current status, decision needed, preparation needed, reference links, and cautions. Do not include reply examples unless the person explicitly asks for them.
- Avoid internal coordination terms in human-facing action notes. Prefer phrases such as "share the URL", "prepare the domain", "ask someone with service access to complete the setup", 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.
