Onboarding UX: use AskUserQuestion for multi-choice; remove press-enter-for-default pattern

[ZaxShen]

Pain

Two UX problems in first-run-onboarding and tmb-reonboard surfaced during live dogfood:

1. Multi-choice asks rely on plain text input — bro lists options 1/2/3 and waits for the user to type a digit. Interactive Claude Code has AskUserQuestion, a first-class multi-choice primitive with proper radio-button UI, descriptions per choice, and no ambiguity. We're not using it.

2. "Press enter to accept default" doesn't work. Claude Code's input prompt cannot send empty input — the user has to type something to commit. Prompts like:

   One more — what's your PR target branch? (default: main — press enter to accept, or type an alternative like master)

   …force the user to type main literally. Only plan-mode accepts bare Enter. So every "press-enter-for-default" instruction in every skill is broken.

Research — AskUserQuestion

CC 2026 exposes AskUserQuestion (deferred tool, loaded via ToolSearch) specifically for structured question flows:

• Radio-button UI for multi-choice, with per-choice label + description.
• Default choice pre-selected (solves the press-enter problem).
• Returns the chosen value directly — no parsing "1" → "github-flow" required.
• Consistent with how ExitPlanMode is invoked.

Proposed changes

1. Branching-model question → AskUserQuestion

Current (text):

1. github-flow — single main, feature branches off main, PRs back to main.
2. gitflow — long-lived develop branch, releases promoted to main.
3. custom — you tell me.

New: AskUserQuestion with three options, github-flow pre-selected. User clicks; bro receives the value directly.

2. PR target branch → plain text input, no "press enter" claim

Current:

What's your PR target branch? (default: main — press enter to accept, or type an alternative like master)

Replace with: AskUserQuestion containing common options (main, master, trunk, develop) plus an "other" that opens a text input. The default-on-radio solves "just go with main" in one click.

3. Every other skill referencing "press enter to keep"

tmb-reonboard has four of these. Convert all to AskUserQuestion with the current value as the default option.

Scope note — naming confusion surfaced in same dogfood

Zax (live): "github-flow, gitflow are kind of confused for me, are they industry standards naming?"

Short answer: yes, both are industry-standard names (GitHub Flow coined by GitHub; Git Flow coined by Vincent Driessen, 2010). But the near-identical names cause confusion. Proposal for the AskUserQuestion labels:

Option value (internal)	User-facing label
github-flow	Trunk + feature branches (GitHub Flow)
gitflow	Trunk + develop + releases (Git Flow)
custom	Something else (you tell me)

Lead with the structural description, brand name in parens. Reduces the "which is which?" guessing.

Acceptance criteria

• first-run-onboarding/SKILL.md rewritten to call AskUserQuestion for the branching-model question and the PR-target question.
• tmb-reonboard/SKILL.md rewritten to use AskUserQuestion everywhere it currently says "press enter to keep".
• Every other skill prompt scrubbed for "press enter to accept" language — none should remain.
• Branching options labeled with structural descriptions lead, brand name in parens.
• Live dogfood: user can complete onboarding in ≤3 clicks (name → branching → PR target), no typing digits.

Related

• Surfaced during PR 📝 dogfood setup: SCENARIOS.md + bun workspaces + doc fixes (closes #40, #42) #41 dogfood.
• Paired with bro first-response latency — 18s with 21.7k token context, 0 MCP tool calls #47 (perf) — smaller context + AskUserQuestion UI should reduce typo/ambiguity errors compounding with latency.

[ZaxShen]

Resolved by the onboarding refactor that landed across PRs #41–#59 and verified in PR #64 Layer 3 dogfood.

Current state:

• tmb_first-run-onboarding (skills/tmb_first-run-onboarding/SKILL.md) uses a single batched 3-question AskUserQuestion radio form (name + branching + PR target).
• The press-enter-for-default pattern is gone from the skill — every option is an explicit radio choice with descriptions.
• A 4th conditional AskUserQuestion fires only on the Custom workflow branch (Step 3a, multi-select for protected branches).
• Lint asserts the AskUserQuestion contract (tests/lint/onboarding-skill-contract.sh): no text-fallback, no synonym-of-Other placeholders, no env-leaked identity examples.

Verified in dogfood: identity + 3 configs land cleanly, protected_branches=["main"] (raw array, not double-encoded string), one Human round-trip total.