ask-human

name	ask-human
layer	method
description	Emit a blocking question the owner can read in ~10 seconds and answer in one reply — the scannable, recommendation-first handoff every agent posts when it hits a fork it can't own. Leads with the one decision + a recommendation, carries the 🤖 provenance header, doubles as the
allowed-tools	Bash, Read, Grep

Ask the human — the scannable, one-decision handoff

You hit a fork. First apply the decide-vs-ask test (AGENTS.md → Deciding vs asking): ask only when it's irreversible/expensive and not derivable and genuinely the human's call. If any one fails → decide + log a Decisions-log line and keep moving. Don't reach for this skill to dodge a call you can make.

If it is ask-worthy, this skill is how you ask well. The owner may be holding ~20 async threads on their phone: the comment must be graspable in ~10 seconds, self-contained (a fresh session resumes from it with zero memory — #639), and it must always propose an answer. Never post a naked "what do you want?".

The template

Post this as a top-level issue comment (add_issue_comment) — never a PR review body (the owner misses those, #846). One decision per comment; batch related questions into it.

## 🔀 Blocked — <the one decision, in one line>
> 🤖 **Claude Code** · interactive agent · posted from @pmcp's account (not Maarten) · _<one-line context>_

**TL;DR — recommend <X>:** <the decision restated + why X is your pick, in one or two lines>
**Status:** <what's done · `branch-name` pushed? · what's NOT done>
**Why it came up:** <what cannot proceed until this is answered>
**Options:**
  - **A) <label>** — <consequence> _(recommended)_
  - **B) <label>** — <consequence>
**Reply:** `A` or `B` (or in-medium — see below). Your reply spawns a fresh session that
resumes from THIS ticket; `lgtm`/`approve` if A-as-recommended is fine.
**Don't lose:** <decisions/assumptions the next agent must carry forward>

Rules that make it work:

• Lead with the decision + a recommendation. The first two lines must answer "what's being asked, and what does the agent suggest?" with no scrollback.
• Always a recommendation. You did the work; you have an opinion — state it and why.
• Provenance header is mandatory (enforced by require-comment-provenance). Interactive agents post under @pmcp's account → use the "not Maarten" disclaimer above. A bot-account pipeline comment uses > 🤖 **<tool>** · agent pipeline (CI) · _<context>_ instead (no @pmcp disclaimer — it'd be false).
• @mention only because action is needed. This is an ask → @mention @pmcp (NOTIFY_HANDLE). Pure FYIs get no mention.
• Push before you block. If you've written anything, git push -u origin <branch> first and name that branch under Status — an unpushed worktree is lost on stop (#639).
• Then apply status:blocked and stop.

Attach the right medium

Prose is the fallback, not the default. If the question is visual or structural, a paragraph is the wrong channel — the owner shouldn't have to reconstruct a layout or a data model in their head. Attach the artifact that shows it, and let them reply on the artifact itself (the reply loop is WS5, #1191). We already own every medium — pick by what the question is, not by habit.

Your question is about…	Attach (medium)	Produce it with	Owner replies by
How it looks / feels (a rendered UI, spacing, copy, states)	live preview	ui-proposal (staging deploy, NUXT_PUBLIC_CROUTON_REVIEW=true) — or a screenshot if no runnable app	pinning feedback on the preview → 🎯 Preview feedback comment naming the file; or A/B
One screen / one state (a single view, an error, a before/after)	screenshot	node scripts/app-shots.mjs <baseUrl> <path[:name]> → screenshots/<name>.png	commenting / A/B
A flow or interaction (multi-step, timing, motion)	short video	demo-video (WebM storyboard)	commenting
The data model (fields, types, relationships)	schema render	schema-review (→ PNG/HTML/MD)	inline comment on the committed .md; or A/B
Structure / status / dependencies (what depends on what, where the tree is)	diagram	ticket-diagram (Excalidraw on the epic)	editing the Excalidraw → scripts/ticket-excalidraw-import.mjs round-trips it back; or A/B
A tradeoff / priority / naming (no visual or structural surface)	prose	the block above	A/B/lgtm

Rules:

• One artifact, the most direct one. Don't attach three renders "to be safe" — pick the medium that answers this question fastest and link it from the blocking comment.
• The artifact supplements the block; it doesn't replace it. Still lead with the decision + recommendation in text — the artifact is the evidence, the block is the ask.
• Screenshots land in screenshots/ (gitignored) — never the repo root or an app dir.
• Reuse the skill, don't reinvent it. Each medium is its own skill/script with its own gotchas; invoke it, don't hand-roll a render.
• If producing the artifact would cost more than the answer is worth (a deploy for a one-line copy tweak), fall back to a screenshot or prose — match the effort to the stakes.

Why this shape

• 10-second-scannable → the owner triages 20 threads without opening each.
• Recommendation-first → most replies collapse to lgtm, one round-trip (epic metric #1).
• Self-contained → the resuming session (resume-on-comment.yml, fresh, checks out main) continues from the branch + comment without re-deriving or diverging (#639).

This extends #639 (the handoff block) — it doesn't replace it. #639 gave the block its state/after/don't-lose fields; this adds the scannable lead + the always-a-recommendation rule and packages it so every agent emits the same shape.