calctext/_bmad/wds/workflows/5-agentic-development/steps-a/step-04-document-findings.md

name, description, activityWorkflowFile

name	description	activityWorkflowFile
step-04-document-findings	Create a structured architecture document that answers the original questions, includes diagrams, and provides actionable recommendations	../workflow-analysis.md

Step 4: Document Findings

STEP GOAL:

Create a structured architecture document that answers the original questions, includes diagrams, and provides actionable recommendations.

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 creating the final architecture document with diagrams and recommendations
• 🚫 FORBIDDEN to redo analysis — use findings from Steps 2 and 3
• 💬 Approach: Collaboratively structure and write the document with user, ensuring original questions are answered
• 📋 Include at least one Mermaid diagram and prioritized recommendations

EXECUTION PROTOCOLS:

• 🎯 Produce a complete architecture document answering the original questions
• 💾 Save the document to the project's output location
• 📖 Reference all findings from Steps 1-3
• 🚫 Do not restart analysis — synthesize existing findings

CONTEXT BOUNDARIES:

• Available context: Question and scope from Step 1; scan from Step 2; architecture map from Step 3
• Focus: Document synthesis, diagrams, risk assessment, recommendations
• Limits: No new analysis — document what was found
• Dependencies: Steps 1, 2, and 3 must be complete

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

1. Create the Architecture Document

Create a document in the output folder that answers the questions defined in Step 01. Use this structure:

# Architecture Analysis: [Project Name]

**Date:** [Date]
**Scope:** [What was analyzed]
**Questions:** [Original questions from Step 01]

## Summary

[2-3 sentence overview of key findings]

## Tech Stack

[Language, framework, database, infrastructure — from Step 02]

## Architecture Overview

[High-level description of how the system is structured]

### Architecture Diagram

[Mermaid diagram — see below]

## Component Map

[Module inventory with responsibilities — from Step 03]

## Data Flow

[End-to-end flow traces — from Step 03]

## Dependencies

[Key dependency relationships, high fan-in/fan-out modules]

## Patterns and Conventions

[Architectural and code patterns observed]

## Risks and Tech Debt

[Issues found during analysis]

## Recommendations

[Actionable next steps]

2. Include Diagrams

Use Mermaid syntax for diagrams that render in Markdown viewers.

Architecture diagram example:

graph TD
    Client[Browser] --> API[API Server]
    API --> Auth[Auth Service]
    API --> Users[User Service]
    API --> Payments[Payment Service]
    Users --> DB[(PostgreSQL)]
    Payments --> Stripe[Stripe API]
    Auth --> Redis[(Redis)]

Dependency diagram example:

graph LR
    A[Module A] --> C[Core]
    B[Module B] --> C
    B --> D[Module D]
    D --> C

Data flow example:

sequenceDiagram
    User->>Frontend: Click "Submit"
    Frontend->>API: POST /orders
    API->>Validation: Validate input
    API->>OrderService: Create order
    OrderService->>Database: INSERT order
    OrderService->>PaymentService: Charge card
    PaymentService->>Stripe: Create charge
    Stripe-->>PaymentService: Charge confirmed
    PaymentService-->>API: Payment success
    API-->>Frontend: 201 Created
    Frontend-->>User: Show confirmation

3. Document Risks and Tech Debt

For each risk or debt item found during analysis:

Risk	Severity	Location	Impact
No input validation on /api/admin/ routes	High	src/routes/admin.ts	Security vulnerability
Circular dependency between User and Order modules	Medium	src/services/	Fragile, hard to test
No error handling in payment flow	High	src/payments/stripe.ts	Silent failures
Outdated dependencies (2 major versions behind)	Medium	package.json	Security + compatibility

4. Write Recommendations

Each recommendation should be:

• Specific — Name the module, file, or pattern
• Actionable — Describe what to do, not just what is wrong
• Prioritized — Order by impact and effort

Example:

## Recommendations

1. **Add input validation to admin routes** (High priority, low effort)
   - Add Zod schemas to all `/api/admin/` endpoints
   - Estimated: 2-3 hours

2. **Break circular dependency between User and Order** (Medium priority, medium effort)
   - Extract shared types to a common module
   - Use dependency injection for cross-service calls
   - Estimated: 4-6 hours

3. **Add error handling to payment flow** (High priority, medium effort)
   - Wrap Stripe calls in try-catch with structured error responses
   - Add retry logic for transient failures
   - Estimated: 3-4 hours

5. Save Output

Save the document to the project's output location. If no output location is defined, save to:

• docs/architecture/ in the analyzed project, or
• The agent experiences folder for session insights

6. Verify Checklist

• Document answers the original questions from Step 01
• Summary is clear and concise (2-3 sentences)
• At least one Mermaid diagram included
• Risks and tech debt listed with severity
• Recommendations are specific, actionable, and prioritized
• Document saved to output folder

7. Present MENU OPTIONS

Display: "Select an Option: [M] Return to Activity Menu"

Menu Handling Logic:

• IF M: Update design log, then load, read entire file, then execute {activityWorkflowFile}
• 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 when user selects 'M'
• User can chat or ask questions - always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN the architecture document is complete and saved will you then load and read fully {activityWorkflowFile} to execute.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Document answers the original questions from Step 01
• Summary is clear and concise (2-3 sentences)
• At least one Mermaid diagram included
• Risks and tech debt listed with severity
• Recommendations are specific, actionable, and prioritized
• Document saved to output folder

❌ SYSTEM FAILURE:

• Document does not answer original questions
• No diagrams included
• Recommendations are vague or not prioritized
• Document not saved

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