questioning-flow

name: questioning-flow description: Adaptive project initialization questioning that captures vision, requirements, and preferences triggers: [start, initialize, project, question, discovery, setup] token_cost: low summary: "Guided questioning flow for new project initialization. Extracts vision, requirements, constraints, and architecture preferences through structured conversation. Generates PROJECT.md, ROADMAP.md, STATE.md."

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

Omission rule: If a section has no content (e.g., no constraints mentioned), omit the content entirely rather than writing "N/A" or "None." Leave the placeholder unfilled so the template renders cleanly with just the heading.

Section 4: Phase Decomposition Guidelines

After all three stages are complete, decompose the captured requirements into phases for ROADMAP.md.

Decomposition Process

1. Group by dependency and domain — requirements that depend on each other or share a domain belong in the same phase. Foundation before features. Features before polish.

2. Order phases by dependency chain:

   • Infrastructure/setup phases first
   • Core functionality next
   • User-facing features after core is stable
   • Polish, optimization, and launch last

3. Size each phase by coherent work boundaries:

   • Use dependency order, domain ownership, verification scope, and traceability to estimate plans
   • Simple phases may need one plan; complex phases may need many plans
   • Do not create extra phases only to avoid adding plans to the current phase

4. Name phases descriptively — use what the phase delivers, not a number:

   • Good: "API Foundation", "User Dashboard", "Launch Prep"
   • Bad: "Phase 1", "Setup", "Stuff"

5. Assign agents per phase — use the recommendation algorithm in agent-registry.md Section 3. For each phase:

   • Parse the phase's requirements against agent task type tags
   • Select 2-4 agents per phase following the registry's matching, ranking, and capping rules
   • Ensure mandatory roles are covered (testing agent for code phases, coordinator for cross-division work)

6. Define success criteria — each phase needs testable, observable completion conditions:

   • Good: "API returns valid JSON for all /users endpoints with 200 status"
   • Bad: "API works"

7. Estimate plan count per phase:

   • Count the requirements in the phase
   • Group into as many plans as dependency, ownership, verification, and traceability boundaries require
   • Apply planning.max_tasks_per_plan only as the per-plan task cap
   • Record the estimate in the phase detail block; plan counts are estimates, not caps

Phase Detail Format

For each phase, produce a block matching the roadmap template pattern:

### Phase N: {phase_name}
**Goal**: One sentence describing what this phase delivers.
**Requirements**: R1, R2, R3 (reference the requirements list items)
**Recommended Agents**: agent-id-1, agent-id-2 (from agent-registry)
**Success Criteria**:
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
**Plans**: {estimated_plan_count}

Phase Checklist Format

- [ ] Phase 1: {phase_name} ({plan_count} plans)
- [ ] Phase 2: {phase_name} ({plan_count} plans)

Planning Depth Adjustments

Section 5: Edge Cases

User wants to skip questions

Accept it. Infer reasonable defaults from whatever context they provided. Record all assumptions as decisions in {decisions_table} with rationale "Inferred — user skipped detailed questioning." Apply default workflow preferences (Guided, Standard, Balanced).

User provides a PRD, spec, or requirements document

If the user pastes or references an existing document:

1. Parse it to extract: project name, description, target users, requirements, constraints, and any stated technical decisions.
2. Summarize what you extracted and confirm: "I pulled the following from your doc — anything to adjust?"
3. Skip directly to Stage 3 (workflow preferences). Do not re-ask questions the document already answers.
4. Record "Imported from user-provided specification" in {decisions_table}.

Existing .planning/ directory detected

The start.md command handles the overwrite warning. If the user confirms reinitialize, proceed with a clean questioning flow. Do not attempt to merge with existing state — it's a fresh start.

Unclear or overly broad project scope

Push for specificity. Use:

"That's broad — if you could only ship ONE thing first, what would it be?"

If the user remains vague after two attempts, scope to what's concrete and note "Scope requires further refinement" in {constraints}.

Non-code project

Legion supports marketing, design, content, and research projects. If the project has no code component:

• Skip all technical stack questions in Stage 2
• Skip {architecture_notes} — omit the section
• Focus phase decomposition on deliverables (content pieces, design assets, campaign milestones)
• Agent recommendations will naturally draw from marketing, design, product, and support divisions

Single-phase project

If requirements are small enough for one phase, that's fine. Create a single phase with 1-2 plans. Don't pad with artificial phases.

User changes their mind mid-flow

If the user contradicts something from an earlier stage, update the captured data. Always use the latest stated preference. Note the pivot in {decisions_table} if it's significant.