flow-selector

name	flow-selector
description	Presents 2+ candidate flows from flow-detector and asks the user to pick one. Issues exactly one AskUserQuestion. Never activates when flow-detector returns a single candidate, and never asks cluster-by-cluster questions.

Flow Selector

Present candidate flows produced by flow-detector and let the user pick one. Single decision point — no follow-up questions.

Activation Triggers

This skill activates when:

• flow-detector has emitted two or more candidate flows.
• The caller (/clarify command or @clarifier agent) hands off the candidate list.

This skill does not activate when:

• flow-detector returned exactly one candidate. The caller proceeds straight to execution-context-builder. If this skill is invoked with a single-candidate list, no-op and log "single candidate; selector skipped".

Hard Rules

1. Issue exactly one AskUserQuestion call. Never two. Never a follow-up.
2. The question's options are the candidate titles. The "Other" escape hatch is added automatically by AskUserQuestion.
3. Do not ask sub-questions about entity, trigger, channel, recipient, or failure handling. Those are encoded in each candidate's full_context.
4. Do not ask "are you sure?" after the user picks.
5. Pass the chosen candidate's full_context directly to execution-context-builder.

Process

1. Print the framing

Output a brief framing block before the question:

This task has multiple possible flows:

1. <candidate[0].title>
   <candidate[0].one_line_diff>

2. <candidate[1].title>
   <candidate[1].one_line_diff>

…

Which flow would you like to proceed with?

The framing prints to the chat so the user can see all candidates at once. The AskUserQuestion tool then renders them as selectable options.

2. Issue the question

Call AskUserQuestion with one question:

question: "Which flow describes the intended scope?"
header: "Flow"
multiSelect: false
options:
  - label: <candidate[0].title (truncate to ≤ 5 words if needed)>
    description: <candidate[0].one_line_diff>
  - label: <candidate[1].title>
    description: <candidate[1].one_line_diff>
  # … one entry per candidate, max 4 total

Notes:

• AskUserQuestion allows 2–4 options. flow-detector caps at 4 candidates, so this fits without truncation.
• The "Other" escape hatch is added automatically. Do not include an explicit "Other" option.

3. Handle the answer

• User picked a numbered option → look up the corresponding candidate and pass its full_context to execution-context-builder. Done.
• User picked "Other" → prompt once with a free-text request: "Describe the intended flow in your own words." Treat the answer as a synthesized candidate (id: user-supplied, title: <user text>, full_context: <best-effort inference from the user's text + repo>). Pass it to execution-context-builder. Do not loop back.

Examples

Two candidates, user picks #1

User runs /clarify "Send message on sign-in".

Print:

This task has multiple possible flows:

1. User sign-in flow — in-app message to the signing-in user
   Recipient is the user who signed in; channel is in-app

2. Tenant audit flow — email to the tenant owner when a member signs in
   Recipient is the tenant owner; channel is email

Which flow would you like to proceed with?

Then issue one AskUserQuestion. User picks option 1 → hand candidate[0].full_context to execution-context-builder → done.

User picks "Other"

User picks Other and types: "Slack message to #engineering when an admin signs in".

Synthesize a candidate:

• entity: User (admin role)
• trigger: { event: "post-auth", timing: "after", preconditions: ["role=admin"] }
• action: { verb: "post", channel: "slack", recipient: "#engineering" }
• flow: { services: ["slack-webhook"], mode: "async", transport: "https" }
• failure_handling: { strategy: "retry", details: "3 attempts then log" }

Hand to execution-context-builder. Do not ask any follow-ups — even if some fields had to be guessed. The artifact is the deliverable; the developer can edit it directly.

Anti-Patterns

Don't	Do Instead
Ask multiple questions in sequence	One AskUserQuestion, period
Ask "and which channel?" after the user picked a flow	Each candidate already encoded the channel
Add a manual "Other" option	AskUserQuestion adds it automatically
Ask "are you sure?"	Trust the user's pick; write the artifact
Drop the framing block and go straight to the question UI	The framing gives context the question chip can't fit

Success Criteria

• Exactly one AskUserQuestion call per invocation.
• The framing block is printed before the question.
• Each option's label and description map to one candidate's title and one_line_diff.
• On "Other", a single free-text follow-up is taken; no further questions.
• The chosen full_context is passed unchanged to execution-context-builder.