bi-agents/_bmad/wds/workflows/5-agentic-development/steps-a/step-01-define-question.md

name, description, nextStepFile

name	description	nextStepFile
step-01-define-question	Articulate exactly what you need to understand about the codebase before reading a single file	./step-02-scan-codebase.md

Step 1: Define Question

STEP GOAL:

Articulate exactly what you need to understand about the codebase before reading a single file.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are an Implementation Partner guiding structured development activities
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
• ✅ Maintain clear and structured tone throughout

Step-Specific Rules:

• 🎯 Focus only on defining clear analysis questions, scope, expected output, and time box
• 🚫 FORBIDDEN to begin scanning or reading any codebase files — that is a later step
• 💬 Approach: Help user articulate their question clearly and set boundaries before any exploration
• 📋 If user provides vague questions, help them sharpen and prioritize

EXECUTION PROTOCOLS:

• 🎯 Produce a clear, scoped analysis question with defined boundaries
• 💾 Save the question, scope, output format, and time box for subsequent steps
• 📖 Reference the category table and scope options to guide user
• 🚫 Do not open, scan, or explore any code during this step

CONTEXT BOUNDARIES:

• Available context: User's initial request or motivation for analysis
• Focus: Defining what to analyze and how to scope it
• Limits: No codebase exploration yet — purely planning
• Dependencies: None — this is the first step

Sequence of Instructions (Do not deviate, skip, or optimize)

1. Articulate the Question

Write down what you need to understand. Common analysis questions:

Category	Example Questions
Architecture	How is this application structured? What patterns does it use?
Dependencies	What does this module depend on? What would break if I change it?
Patterns	What conventions does the team follow? Where are they inconsistent?
Performance	Where are the bottlenecks? What queries are expensive?
Data flow	How does data move from user input to database and back?
Integration	What external services does this connect to? How?
Security	Where is authentication handled? Are there exposed endpoints?

Write the question in plain language. If you have multiple questions, prioritize them.

2. Define Scope

Determine what is in and out of scope:

• Entire codebase — Full architecture review (use for onboarding or documentation)
• Specific module — One feature area, service, or package
• Cross-cutting concern — Authentication, error handling, logging across the codebase
• Integration boundary — How two systems communicate

Be explicit about what you will NOT analyze. Unbounded scope leads to analysis paralysis.

3. Define Expected Output

Decide what the analysis should produce:

• Architecture map — High-level component diagram with relationships
• Dependency graph — Module dependencies, import chains
• Pattern catalog — Design patterns used, where, and how consistently
• API map — Endpoints, request/response shapes, authentication
• Data model — Entity relationships, storage patterns
• Risk assessment — Tech debt, security concerns, fragile areas

4. Set Time Box

Decide how long the analysis should take. Recommended:

Scope	Time Box
Single module	15-30 min
Feature area	30-60 min
Full codebase	1-2 hours

If the time box expires, document what you found and what remains unexplored.

5. Verify Checklist

• Question is written in plain language
• Scope boundaries are defined (what is in, what is out)
• Expected output format is chosen
• Time box is set

6. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Step 2: Scan Codebase"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then [Redisplay Menu Options]

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects 'C'
• User can chat or ask questions - always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN the user has confirmed a clear question, scope, output format, and time box will you then load and read fully {nextStepFile} to execute.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Question is written in plain language
• Scope boundaries are defined (what is in, what is out)
• Expected output format is chosen
• Time box is set

❌ SYSTEM FAILURE:

• Beginning codebase exploration before question is defined
• Proceeding without clear scope boundaries
• Skipping time box definition

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.