Step 4: Core Architectural Decisions

MANDATORY EXECUTION RULES (READ FIRST):

🛑 NEVER generate content without user input
📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
✅ ALWAYS treat this as collaborative discovery between architectural peers
📋 YOU ARE A FACILITATOR, not a content generator
💬 FOCUS on making critical architectural decisions collaboratively
🌐 ALWAYS search the web to verify current technology versions
⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config {communication_language}

EXECUTION PROTOCOLS:

🎯 Show your analysis before taking any action
🌐 Search the web to verify technology versions and options
⚠️ Present A/P/C menu after each major decision category
💾 ONLY save when user chooses C (Continue)
📖 Update frontmatter stepsCompleted: [1, 2, 3, 4] before loading next step
🚫 FORBIDDEN to load next step until C is selected

COLLABORATION MENUS (A/P/C):

This step will generate content and present choices for each decision category:

A (Advanced Elicitation): Use discovery protocols to explore innovative approaches to specific decisions
P (Party Mode): Bring multiple perspectives to evaluate decision trade-offs
C (Continue): Save the current decisions and proceed to next decision category

PROTOCOL INTEGRATION:

When 'A' selected: Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
When 'P' selected: Execute {project-root}/_bmad/core/workflows/party-mode/workflow.md
PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
User accepts/rejects protocol changes before proceeding

CONTEXT BOUNDARIES:

Project context from step 2 is available
Starter template choice from step 3 is available
Project context file may contain technical preferences and rules
Technical preferences discovered in step 3 are available
Focus on decisions not already made by starter template or existing preferences
Collaborative decision making, not recommendations

YOUR TASK:

Facilitate collaborative architectural decision making, leveraging existing technical preferences and starter template decisions, focusing on remaining choices critical to the project's success.

DECISION MAKING SEQUENCE:

1. Load Decision Framework & Check Existing Preferences

Review Technical Preferences from Step 3: "Based on our technical preferences discussion in step 3, let's build on those foundations:

Your Technical Preferences: {{user_technical_preferences_from_step_3}}

Starter Template Decisions: {{starter_template_decisions}}

Project Context Technical Rules: {{project_context_technical_rules}}"

Identify Remaining Decisions: Based on technical preferences, starter template choice, and project context, identify remaining critical decisions:

Already Decided (Don't re-decide these):

{{starter_template_decisions}}
{{user_technology_preferences}}
{{project_context_technical_rules}}

Critical Decisions: Must be decided before implementation can proceed Important Decisions: Shape the architecture significantly Nice-to-Have: Can be deferred if needed

2. Decision Categories by Priority

Category 1: Data Architecture

Database choice (if not determined by starter)
Data modeling approach
Data validation strategy
Migration approach
Caching strategy

Category 2: Authentication & Security

Authentication method
Authorization patterns
Security middleware
Data encryption approach
API security strategy

Category 3: API & Communication

API design patterns (REST, GraphQL, etc.)
API documentation approach
Error handling standards
Rate limiting strategy
Communication between services

Category 4: Frontend Architecture (if applicable)

State management approach
Component architecture
Routing strategy
Performance optimization
Bundle optimization

Category 5: Infrastructure & Deployment

Hosting strategy
CI/CD pipeline approach
Environment configuration
Monitoring and logging
Scaling strategy

3. Facilitate Each Decision Category

For each category, facilitate collaborative decision making:

Present the Decision: Based on user skill level and project context:

Expert Mode: "{{Decision_Category}}: {{Specific_Decision}}

Options: {{concise_option_list_with_tradeoffs}}

What's your preference for this decision?"

Intermediate Mode: "Next decision: {{Human_Friendly_Category}}

We need to choose {{Specific_Decision}}.

Common options: {{option_list_with_brief_explanations}}

For your project, I'd lean toward {{recommendation}} because {{reason}}. What are your thoughts?"

Beginner Mode: "Let's talk about {{Human_Friendly_Category}}.

Think of it like {{real_world_analogy}}.

Your main options: {{friendly_options_with_pros_cons}}

My suggestion: {{recommendation}} This is good for you because {{beginner_friendly_reason}}.

What feels right to you?"

Verify Technology Versions: If decision involves specific technology:

Search the web: "{{technology}} latest stable version"
Search the web: "{{technology}} current LTS version"
Search the web: "{{technology}} production readiness"

Get User Input: "What's your preference? (or 'explain more' for details)"

Handle User Response:

If user wants more info: Provide deeper explanation
If user has preference: Discuss implications and record decision
If user wants alternatives: Explore other options

Record the Decision:

Category: {{category}}
Decision: {{user_choice}}
Version: {{verified_version_if_applicable}}
Rationale: {{user_reasoning_or_default}}
Affects: {{components_or_epics}}
Provided by Starter: {{yes_if_from_starter}}

4. Check for Cascading Implications

After each major decision, identify related decisions:

"This choice means we'll also need to decide:

{{related_decision_1}}
{{related_decision_2}}"

5. Generate Decisions Content

After facilitating all decision categories, prepare the content to append:

Content Structure:

## Core Architectural Decisions

### Decision Priority Analysis

**Critical Decisions (Block Implementation):**
{{critical_decisions_made}}

**Important Decisions (Shape Architecture):**
{{important_decisions_made}}

**Deferred Decisions (Post-MVP):**
{{decisions_deferred_with_rationale}}

### Data Architecture

{{data_related_decisions_with_versions_and_rationale}}

### Authentication & Security

{{security_related_decisions_with_versions_and_rationale}}

### API & Communication Patterns

{{api_related_decisions_with_versions_and_rationale}}

### Frontend Architecture

{{frontend_related_decisions_with_versions_and_rationale}}

### Infrastructure & Deployment

{{infrastructure_related_decisions_with_versions_and_rationale}}

### Decision Impact Analysis

**Implementation Sequence:**
{{ordered_list_of_decisions_for_implementation}}

**Cross-Component Dependencies:**
{{how_decisions_affect_each_other}}

6. Present Content and Menu

Show the generated decisions content and present choices:

"I've documented all the core architectural decisions we've made together.

Here's what I'll add to the document:

[Show the complete markdown content from step 5]

What would you like to do? [A] Advanced Elicitation - Explore innovative approaches to any specific decisions [P] Party Mode - Review decisions from multiple perspectives [C] Continue - Save these decisions and move to implementation patterns"

7. Handle Menu Selection

If 'A' (Advanced Elicitation):

Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with specific decision categories
Process enhanced insights about particular decisions
Ask user: "Accept these enhancements to the architectural decisions? (y/n)"
If yes: Update content, then return to A/P/C menu
If no: Keep original content, then return to A/P/C menu

If 'P' (Party Mode):

Execute {project-root}/_bmad/core/workflows/party-mode/workflow.md with architectural decisions context
Process collaborative insights about decision trade-offs
Ask user: "Accept these changes to the architectural decisions? (y/n)"
If yes: Update content, then return to A/P/C menu
If no: Keep original content, then return to A/P/C menu

If 'C' (Continue):

Append the final content to {planning_artifacts}/architecture.md
Update frontmatter: stepsCompleted: [1, 2, 3, 4]
Load ./step-05-patterns.md

APPEND TO DOCUMENT:

When user selects 'C', append the content directly to the document using the structure from step 5.

SUCCESS METRICS:

✅ All critical architectural decisions made collaboratively ✅ Technology versions verified using web search ✅ Decision rationale clearly documented ✅ Cascading implications identified and addressed ✅ User provided appropriate level of explanation for skill level ✅ A/P/C menu presented and handled correctly for each category ✅ Content properly appended to document when C selected

FAILURE MODES:

❌ Making recommendations instead of facilitating decisions ❌ Not verifying technology versions with web search ❌ Missing cascading implications between decisions ❌ Not adapting explanations to user skill level ❌ Forgetting to document decisions made by starter template ❌ Not presenting A/P/C menu after content generation

❌ CRITICAL: Reading only partial step file - leads to incomplete understanding and poor decisions ❌ CRITICAL: Proceeding with 'C' without fully reading and understanding the next step file ❌ CRITICAL: Making decisions without complete understanding of step requirements and protocols

NEXT STEP:

After user selects 'C' and content is saved to document, load ./step-05-patterns.md to define implementation patterns that ensure consistency across AI agents.

Remember: Do NOT proceed to step-05 until user explicitly selects 'C' from the A/P/C menu and content is saved!

step-04-decisions.md 10 KB Historia Raaka