9thlevelsoftware/legion/questioning-flow

Questioning Flow

Adaptive conversation engine for /legion:start. Captures everything needed to populate PROJECT.md, ROADMAP.md, and STATE.md templates through a 3-stage dialogue.

Section 1: Questioning Philosophy

1. Vision first, technology second — understand what the user wants to exist before asking how to build it.
2. Adaptive depth — follow the user's energy. If they go deep on a topic, explore it. If they give a terse answer, move on.
3. Infer where possible, confirm where uncertain — don't ask questions the user already answered implicitly. State your inference and let them correct it.
4. Always close with a bounded choice (CLAUDE.md mandate) — every user-facing question MUST invoke adapter.ask_user (AskUserQuestion on Claude Code) with a finite option set. Free-text prompts are not permitted. When the concept space is unbounded, include an Other / Add details option that opens a single free-text capture via adapter.prompt_free_text — never end a turn with an open prose prompt.
5. Target 5-8 total exchanges — not 20 questions. Combine related questions. Skip what's already clear.
6. Summarize between stages with a closure question — after each stage, reflect back what you captured and close with a bounded confirmation: Looks correct / Correct a specific field / Add missing detail / Cancel. Never close a summary with an open "Anything to add?" prompt.

Section 2: Conversation Flow

Stage 1: Vision & Identity (1-3 exchanges)

Purpose: Capture {project_name}, {project_description}, {value_proposition}, {target_users}.

Open with an `adapter.ask_user` (AskUserQuestion) call — not a bare prose prompt. Example option set for the opener:

From the captured text, extract what you can. Then ask only what's still missing — each follow-up MUST be an adapter.ask_user call with a bounded option set (not a prose question):

Only open a free-text primitive when the user explicitly selects an Other/Refine/Describe option — never as the default prompt.

After Stage 1 — Summarize, then close with a bounded adapter.ask_user confirmation:

Display the summary as plain text:

"Here's what I'm understanding: [project_name] is [project_description]. It's for [target_users] and the core value is [value_proposition]."

Then invoke adapter.ask_user with these options (exact schema — no free-text default):

Wait for a selection. Do NOT emit an open "Anything to correct or add?" prompt — that is a CLAUDE.md violation.

Stage 2: Requirements & Constraints (2-4 exchanges)

Purpose: Capture {requirements_list}, {out_of_scope}, {constraints}, {architecture_notes}, {decisions_table}.

Core capture — always via `adapter.ask_user`:

For must-have features:

For out-of-scope:

Adaptive follow-ups — after detecting project type in Stage 1, invoke one adapter.ask_user call per slot with option lists inferred from the stack — never a free-prose question. Examples:

Rule: If you cannot enumerate 2-5 plausible options for a slot, do not ask — skip the slot and let the phase planner capture it later.

General optional slots — each invoked via adapter.ask_user when relevant (skip the slot entirely if not):

• constraints — options: None, Timeline, Budget, Hosting, Language/stack, Other (specify)
• risk — options: 3-5 inferred risks + Other (specify) + No major unknowns
• existing-assets — options: Existing repo, Existing designs, Existing content, Nothing yet, Other (specify)
• timeline — options: No deadline, Soft (weeks), Firm (date — specify), Urgent (this week)

After Stage 2 — Summarize as plain text, then close with a bounded adapter.ask_user confirmation:

Summary display:

"Here's the v1 scope I captured: [bullet list]. Out of scope: [items]."

Close with:

Do NOT close with an open "Any adjustments?" prompt — that is a CLAUDE.md violation.

Stage 3: Workflow Preferences (1-2 exchanges)

Purpose: Capture execution mode, planning depth, and cost profile. These shape how ROADMAP.md phases are structured and how agents execute.

Present three structured choices. Use clear descriptions so the user can choose quickly.

Question 1 — Execution Mode:

• Guided (Recommended): Legion recommends actions, you approve before each step. Best for first-time use or high-stakes projects.
• Autonomous: Legion plans and executes, you review at checkpoints. Best for trusted workflows or time pressure.
• Collaborative: Work alongside agents with high interaction. Best when you want to stay hands-on.

Question 2 — Planning Depth:

• Standard (Recommended): Balanced planning and execution. 3-6 phases. Good for most projects.
• Quick Sketch: Minimal planning, start building fast. 2-3 phases. Good for prototypes or explorations.
• Deep Analysis: Thorough research and planning before execution. 6+ phases. Good for complex or unfamiliar domains.

Question 3 — Cost Profile:

• Balanced (Recommended): Opus for planning, Sonnet for execution, Haiku for checks. Best cost/quality ratio.
• Economy: Sonnet for planning and execution, Haiku for checks. Lower cost, still capable.
• Premium: Opus for planning and execution, Sonnet for checks. Maximum quality, higher cost.

Record choices as decisions in {decisions_table}:

| Execution mode | [user rationale or "default"] | [chosen mode] |
| Planning depth | [user rationale or "default"] | [chosen depth] |
| Cost profile   | [user rationale or "default"] | [chosen profile] |

Section 3: Output Structure

Placeholder Mapping

Formatting Rules

Requirements — each requirement is a checkbox item:

-[ ] User authentication with email/password
-[ ] Dashboard showing key metrics
-[ ] Export data as CSV

Decisions — each decision is a table row:

| Tech stack | Team familiarity and ecosystem maturity | Next.js + PostgreSQL |
| Execution mode | First project with Legion | Guided |

Out of scope / Constraints — plain bullet lists:

-Mobile app (web-first for v1)
-Multi-language support