Design Dialogue

Design Dialogue Skill

Standard workflow only. If task_complexity is simple and workflow mode is Express, do not activate this skill. Simple tasks use the Express workflow, which does not activate design-dialogue. Return to the Express Workflow section.

Activate this skill when beginning Phase 1 of Maestro orchestration. Use the plan mode tool from get_runtime_context (loaded at session start, step 0). If your runtime provides a Plan Mode surface, enter it now by calling enter_plan_mode. If Plan Mode is unavailable or the transition fails, continue without it and use the user-prompt tool from runtime context with type: 'yesno' for design approvals and type: 'choice' for approach selection. This skill provides the structured methodology for conducting design conversations that converge on approved architectural designs.

User confirmation sequence: Phase 1 entry may trigger a Plan Mode confirmation when enter_plan_mode is available. That confirmation is expected; do not treat it as redundant or skip it. If your runtime does not provide Plan Mode, move directly into the depth selector and approval prompts.

Design Depth Gate

Before asking any design questions, present the user with a depth selector to control the level of reasoning rigour applied throughout the design phase. Use ask_user with type: 'choice' to offer three modes. Lead with Standard as the recommended default.

Modes:

• Quick — Current reasoning behavior. One question per topic, pros/cons on approaches, standard design sections. No enrichment steps, no decision matrix, no reasoning annotations. Choose this when you already have clarity and want to move fast. (The depth selector prompt itself is the only new conversational step — once Quick is selected, all subsequent behavior matches pre-change behavior exactly.)
• Standard (Recommended) — Adds assumption surfacing after each answer and a decision matrix during approach evaluation. Design sections gain rationale annotations tying decisions to project context. The default for most work.
• Deep — Full treatment. Follow-up probing into implications, assumption surfacing with confirmation, trade-off narration on each choice, decision matrix with scoring, rationale annotations, per-decision alternatives, and full requirement traceability. Choose this for high-stakes or ambiguous tasks.

Depth propagation: Remember the user's chosen depth mode and apply it consistently to all subsequent steps in this skill. The depth mode is not re-prompted — it is set once and carried forward. If the user's answer to the depth prompt is ambiguous, default to Standard.

Depth vs. complexity: Depth and complexity guidance (simple/medium/complex) are orthogonal. Complexity controls which sections appear and word count per section. Depth controls reasoning richness within each section. They compose independently — a user may select Deep depth on a Simple complexity task or Quick depth on a Complex task. Both are valid choices.

Frontmatter: Record the chosen depth in the design document frontmatter as design_depth: quick | standard | deep. Also record task_complexity: simple | medium | complex in the design document frontmatter after design_depth.

First-Turn Contract: On the first turn, Maestro presents the complexity classification result (classified per the complexity classification section in the orchestrator) and the depth selector with a complexity-informed recommendation. For simple tasks, auto-select Quick and inform the user: "This looks straightforward — using Quick depth. Say 'deeper' if you want more analysis." For medium tasks, recommend Standard. For complex tasks, recommend Standard or Deep. The first actual design question moves to the second turn.

Repository Grounding Protocol

Before you start narrowing the architecture for work that touches an existing codebase, decide whether the task is already grounded.

Use the built-in codebase_investigator when any of the following are true:

• The request targets an existing project or subsystem
• The current architecture, impacted modules, or integration seams are unclear
• You need concrete validation commands, conventions, or ownership boundaries before presenting approaches

Ask the investigator for:

• The current architecture slice relevant to the task
• The most likely impacted modules and files
• Existing naming, layering, and testing conventions to preserve
• Integration points and dependency edges the design must respect
• Validation commands already used by the repo
• Parallelization or file-conflict risks that should shape the later implementation plan

Skip codebase_investigator for greenfield tasks, documentation-only work, or scopes that are already well understood from direct file reads in the current turn.

Use the investigator's output to:

• Tailor follow-up questions to the actual codebase
• Avoid proposing approaches that conflict with existing boundaries
• Cite concrete modules/files when explaining trade-offs

Question Framework

Principles

• Ask one question at a time — never batch multiple questions
• Prefer multiple choice format with 2-4 options over open-ended questions
• For every choice presented, include brief pros and cons so the user can make an informed decision — never present bare options without trade-off context
• Lead with your recommended option and explain the rationale
• Wait for user response before proceeding to next question
• Adapt follow-up questions based on previous answers

Required Coverage Areas

Ask questions in this order to progressively narrow the design space:

1. Problem Scope & Boundaries

   • What specific problem are we solving?
   • What is explicitly out of scope?
   • What are the expected inputs and outputs?

2. Technical Constraints & Limitations

   • Existing technology stack and infrastructure
   • Compatibility requirements with existing systems
   • Performance budgets (latency, throughput, resource limits)
   • Team expertise and familiarity

3. Technology Preferences

   • Language and framework preferences
   • Database and storage requirements
   • Third-party service dependencies
   • Build and deployment toolchain

4. Quality Requirements

   • Performance targets (response time, concurrent users)
   • Security requirements (authentication, authorization, data protection)
   • Scalability expectations (growth projections, peak loads)
   • Reliability requirements (uptime, disaster recovery)

5. Deployment Context

   • Target environment (cloud provider, on-premise, hybrid)
   • CI/CD pipeline requirements
   • Monitoring and observability needs
   • Operational constraints (team size, on-call, maintenance windows)

Coverage Scaling by Complexity

Scale question coverage based on task_complexity:

• simple: Ask questions from Area 1 (Problem Scope & Boundaries) only. Skip Areas 2-5.
• medium: Ask questions from Areas 1-3 (Scope, Constraints, Tech Preferences). Skip Areas 4-5.
• complex: Ask questions from all 5 areas (current behavior).

Question Format

Prompt the user for a choice using the user-prompt tool from runtime context. Use type: 'choice' for structured selections with 2-4 options. Each option should have a short label (1-5 words) and a description explaining when it makes sense and its trade-offs. Include your recommendation rationale in the question text so the user has context before choosing.

Enrichment Protocol

After the user answers each question, apply depth-gated enrichment steps before advancing to the next topic:

Quick mode: No enrichment steps. Accept the answer and proceed to the next question. Current behavior preserved.

Standard mode: After each user answer, state the assumptions you are making based on their response in 1-2 sentences, then ask the user to confirm or correct before proceeding. Example flow: question → answer → "Based on your answer, I'm assuming X and Y — correct?" → confirmation → next question.

Deep mode: After each user answer: (a) state and confirm assumptions as in Standard mode, (b) narrate the trade-offs of the choice in 1-2 sentences ("That choice means we gain A but give up B"), (c) if the answer has non-obvious implications (e.g., a technology choice that constrains future scaling options or creates a vendor lock-in dependency), ask one follow-up probing question before moving to the next topic. Cap at one follow-up per question.

Adaptive elision: If the user's answer is concrete, specific, and requires no inference (e.g., "What language?" → "TypeScript, same as the rest of the repo"), the assumption surfacing and trade-off narration steps may be skipped even in Deep mode. Only apply enrichment when there are genuine assumptions to surface or trade-offs to narrate. Do not elide when the answer implies unstated architectural trade-offs even if the answer itself is short (e.g., "REST" implies choices about state management, versioning, and contract evolution that are worth surfacing).

Approach Presentation

When to Present Approaches

Present 2-3 architectural approaches after gathering sufficient requirements (typically after covering scope, constraints, and technology preferences).

If codebase_investigator was used, present approaches only after incorporating its findings into the trade-off analysis. Do not treat the existing codebase structure as optional context.

Approach Format

For each approach, provide:

### Approach [N]: [Descriptive Name]

**Summary**: [2-3 sentence overview]

**Architecture**:
[Component diagram or description showing key components and their relationships]

**Pros**:
- [Concrete advantage with context]
- [Another advantage]

**Cons**:
- [Concrete disadvantage with context]
- [Another disadvantage]

**Best When**: [Specific conditions where this approach excels]

**Risk Level**: Low | Medium | High

Presentation Rules

• Always lead with your recommended approach
• Explain why the recommended approach best fits the gathered requirements
• Highlight the key differentiator between approaches
• After presenting all approaches, explicitly ask the user to choose
• Accept user's choice without pushback, even if it differs from your recommendation

Recommendation Philosophy

• Always identify the ideal long-term solution — the approach that is architecturally sound, maintainable, and future-proof. Present it clearly so the user understands what "right" looks like.
• When the long-term solution requires large-scale changes that are disproportionate to the task at hand, also present a pragmatic alternative that accomplishes the goal without major disruption. Be explicit about the trade-off: "The ideal solution is X (because...), but a pragmatic path is Y (because the scope of X is disproportionate to the current need)."
• Never default to the quick fix without surfacing the long-term option. The user should always know what they're trading away. But equally, never recommend a large-scale refactor when the task can be accomplished safely with a targeted change.
• Label each approach honestly: which is the long-term investment, which is the pragmatic path, and which (if any) is a stopgap that will create debt.