gstack/docs/askuserquestion-split.md

AskUserQuestion split rule — full reference

Inline summary lives in the canonical preamble (scripts/resolvers/preamble/generate-ask-user-format.ts). That subsection is intentionally compressed because it injects into every tier-2+ skill's SKILL.md. This file is the deep reference the inline guidance points to — load it when N>4 options come up and you need worked examples or the full Hold / dependency / final-summary semantics.

The bug this prevents

Pre-rule failure mode (transcript verbatim from the user complaint that motivated this):

"I'm hitting Conductor's limit of 4 options in the AUQ, so I need to cut one. E4 (the detect-mappings codegen) is the biggest lift and probably beyond scope for v0.42 anyway — users can hand-author their mapping rules for the 9 clusters. I'll drop that and keep E1, E2, E3, and E5..."

"Conductor caps at 4 options. Trimming: E4 (detect-mappings codegen) is the largest-effort item and a natural v0.43+ follow-up — moving it to TODOS.md without asking. Re-firing with 4."

The agent unilaterally cut a real option without user input. The option set is the user's decision space; shrinking it silently is the bug.

Which shape: batched vs. split

Two compliant shapes. Pick by reading the options:

1. Batched into ≤4-groups — the options are coherent alternatives, one will be picked. Examples: "major / minor / patch / micro" for a version bump, "5 layout variants where the user picks one", "which framework: rspec / minitest / cucumber / none". Batch the top 4 into one AskUserQuestion; surface the 5th as a follow-up if none of the first 4 fit. This is the lower-friction path when applicable.

2. Split per-option — the options are independent scope items, each carrying its own include/defer/cut decision. Examples: "E1..E6, which do we ship?", "5 candidate integrations for Q3", "8 TODOs surfaced by the audit — which do we land?". Fire N sequential AskUserQuestion calls, one per option.

Default to split per-option when unsure. Batching wrong options together — shoehorning orthogonal scope items into one question — is the same failure mode as dropping.

Split per-option mechanics

Before the chain

Check for dependencies between options. If E3 requires E1, or E5 conflicts with E2, surface that in the per-option ELI10:

"Cutting this orphans E3 — they're linked."

Without dependency surfacing, the chain produces incoherent picked sets (user picks Include for E3 + Cut for E1, ships an unbuildable scope).

D-numbering

• Parent decision: D<N> where N is the global question counter.
• Each per-option call: D<N>.k for k=1..K children.
• Final summary: D<N>.final.
• Single-option revise: D<N>.revise-<k>.

Example chain for 5 options at parent D3:

D3.1 → D3.2 → D3.3 → D3.4 → D3.5 → D3.final

Per-option call shape

For each option Eₖ, fire an AskUserQuestion with:

• D<N>.k header (e.g. D3.1, D3.2 ... D3.5)
• ELI10 of just this option's scope, cost, and any dependency it carries
• Recommendation: Include / Defer / Cut, with concrete reason
• 4 buckets per option:
  • A) Include in this scope (recommended/not)
  • B) Defer to follow-up (TODOs / next version)
  • C) Cut entirely
  • D) Hold — stop the chain, discuss before deciding
• Note: options differ in kind, not coverage — no completeness score. (Include/Defer/Cut/Hold are decision actions, so the existing format rule applies: omit Completeness: N/10 and use the kind-note instead.)

Hold means stop, not queue

When the user picks Hold on any per-option call, stop the chain immediately. Do not continue asking later options behind the Hold — the user wants to discuss the picked option first. After discussion, the user resumes by saying "continue" or naming the next option to ask about.

Wrong behavior: queue E4 and E5 behind a Hold on E3, then fire them later with stale context. Right behavior: stop, let the user reset the parent decision, resume from where they left off.

Final summary

After the chain resolves (without Hold), fire D<N>.final to confirm and validate the assembled set.

Step 1 — validate dependencies. If the picked set is incoherent (e.g. E3 picked Include but its required E1 was Cut), do NOT silently accept. Re-prompt the conflict as a single AskUserQuestion:

"E3 needs E1 but you cut E1. Revise: A) keep E1 B) cut E3 too C) leave as-is and accept the broken state"

Step 2 — confirm the assembled set. If coherent:

"Here's the assembled set: E1, E2, E5. Ship this scope? A) Ship this scope (recommended) B) Revise one option (you pick which) C) Cut more"

Step 3 — targeted revise. If the user picks B, ask which option to revise, then fire ONE per-option AskUserQuestion at D<N>.revise-<k> to update just that option. Do not re-run the whole chain.

Sizing rules

• N ≤ 4: use the normal single AskUserQuestion form. Don't split.

• N = 5 or 6: split (or batch if a clean grouping exists).

• N > 6: BEFORE the chain, fire a meta-AskUserQuestion at D<N>.0:

  "About to ask N per-option questions. Options: A) Proceed with the full split (recommended only if every option is independent) B) Narrow scope first — I'll propose a smaller set C) Batch into groups of 4 instead"

  This is itself an AskUserQuestion tool call, not prose — it counts as the first prompt in the chain, not a violation of the "tool not prose" rule.

question_id rules for split chains

Each per-option AskUserQuestion emits a unique question_id of the form <skill>-split-<option-slug> where <option-slug> is the option's key kebab-cased (lowercase, hyphens, ASCII only).

Examples:

• plan-ceo-review-split-e4-detect-mappings
• ship-split-rspec
• plan-eng-review-split-add-coverage-test

Collision handling. If two options would produce the same slug, suffix with -2, -3, etc.

Length. Total length must be ≤64 chars (validated by bin/gstack-question-preference --write). Truncate the option slug if needed, preserving the <skill>-split- prefix.

AUTO_DECIDE behavior with split chains

Two-layer defense.

Layer 1 — mechanism. Each per-option question_id is unique to its option, so preferences set on one option's id cannot leak across the chain. A never-ask on ship-split-rspec does not silently approve ship-split-minitest.

Layer 2 — runtime enforcement. bin/gstack-question-preference --check detects any id matching *-split-* (the canonical slug pattern emitted by split chains) and forces ASK_NORMALLY even when a never-ask or ask-only-for-one-way preference exists for that exact id. The check emits an explanatory note when this override fires:

"split-chain per-option calls always ASK_NORMALLY; your never-ask preference does not apply to options inside a sequential split."

Result. Split-chain per-option calls are NEVER AUTO_DECIDE-eligible. This is a runtime contract, not just collision-resistance by id uniqueness. The user's option set is sacred — restoring user sovereignty over the decision space is the entire point of splitting.

Interaction with per-skill rules

This rule overrides any per-skill "batch decisions" guidance. Per-skill templates that explicitly require one-issue-per-call (e.g. plan-eng-review) are already compatible — they're a stricter special case of this rule.

Worked example: 5 platform integrations

Fixture used by test/skill-e2e-plan-ceo-split-overflow.test.ts. A plan has 5 independent chat-platform candidates:

• E1) Slack DM bot (~2 weeks, ~40% of asks)
• E2) Discord guild bot (~3 weeks, ~15%)
• E3) Microsoft Teams (~4 weeks, ~5%)
• E4) Telegram (~1 week, ~8%)
• E5) Mattermost (~2 weeks, ~3%)

User wants individual decisions per candidate, not a bundled pick. The agent should:

1. Recognize this is a 5-option independent-scope decision → split.
2. Check dependencies (none here — each platform is standalone).
3. Fire D3.1 through D3.5, one per platform, with Include / Defer / Cut / Hold buckets and an effort+demand-grounded recommendation per option.
4. After the chain, fire D3.final summarizing the assembled scope (e.g. "Ship E1 + E4 — Slack and Telegram pull most demand for least build cost. Defer the rest. A) Ship / B) Revise / C) Cut more").

Pre-fix failure shape (the bug): agent constructs a single AskUserQuestion with E1..E4 as four options, drops E5 with prose like "E5 is the smallest revenue segment, moving to TODOs". The user never got to weigh in on E5. Floor-of-4 in the E2E test catches this.