BMAD-METHOD/.bmad/bmm/workflows/document-project/workflows/deep-dive-instructions.md

Deep-Dive Documentation Instructions

This workflow performs exhaustive deep-dive documentation of specific areas Called by: ../document-project/instructions.md router Handles: deep_dive mode only

Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN. Load existing project structure from index.md and project-parts.json (if exists) Load source tree analysis to understand available areas Analyze existing documentation to suggest deep-dive options

What area would you like to deep-dive into?

Suggested Areas Based on Project Structure:

{{#if has_api_routes}}

API Routes ({{api_route_count}} endpoints found)

{{#each api_route_groups}} {{group_index}}. {{group_name}} - {{endpoint_count}} endpoints in {{path}} {{/each}} {{/if}}

{{#if has_feature_modules}}

Feature Modules ({{feature_count}} features)

{{#each feature_modules}} {{module_index}}. {{module_name}} - {{file_count}} files in {{path}} {{/each}} {{/if}}

{{#if has_ui_components}}

UI Component Areas

{{#each component_groups}} {{group_index}}. {{group_name}} - {{component_count}} components in {{path}} {{/each}} {{/if}}

{{#if has_services}}

Services/Business Logic

{{#each service_groups}} {{service_index}}. {{service_name}} - {{path}} {{/each}} {{/if}}

Or specify custom:

• Folder path (e.g., "client/src/features/dashboard")
• File path (e.g., "server/src/api/users.ts")
• Feature name (e.g., "authentication system")

Enter your choice (number or custom path):

Parse user input to determine: - target_type: "folder" | "file" | "feature" | "api_group" | "component_group" - target_path: Absolute path to scan - target_name: Human-readable name for documentation - target_scope: List of all files to analyze

Store as {{deep_dive_target}}

Display confirmation: Target: {{target_name}} Type: {{target_type}} Path: {{target_path}} Estimated files to analyze: {{estimated_file_count}}

This will read EVERY file in this area. Proceed? [y/n]

Return to Step 13a (select different area)

Set scan_mode = "exhaustive" Initialize file_inventory = [] You must read every line of every file in scope and capture a plain-language explanation (what the file does, side effects, why it matters) that future developer agents can act on. No shortcuts. Get complete recursive file list from {{target_path}} Filter out: node_modules/, .git/, dist/, build/, coverage/, *.min.js, *.map For EVERY remaining file in folder: - Read complete file contents (all lines) - Extract all exports (functions, classes, types, interfaces, constants) - Extract all imports (dependencies) - Identify purpose from comments and code structure - Write 1-2 sentences (minimum) in natural language describing behaviour, side effects, assumptions, and anything a developer must know before modifying the file - Extract function signatures with parameter types and return types - Note any TODOs, FIXMEs, or comments - Identify patterns (hooks, components, services, controllers, etc.) - Capture per-file contributor guidance: `contributor_note`, `risks`, `verification_steps`, `suggested_tests` - Store in file_inventory Read complete file at {{target_path}} Extract all information as above Read all files it imports (follow import chain 1 level deep) Find all files that import this file (dependents via grep) Store all in file_inventory Identify all route/controller files in API group Read all route handlers completely Read associated middleware, controllers, services Read data models and schemas used Extract complete request/response schemas Document authentication and authorization requirements Store all in file_inventory Search codebase for all files related to feature name Include: UI components, API endpoints, models, services, tests Read each file completely Store all in file_inventory Get all component files in group Read each component completely Extract: Props interfaces, hooks used, child components, state management Store all in file_inventory

For each file in file*inventory, document: - File Path: Full path - Purpose: What this file does (1-2 sentences) - Lines of Code: Total LOC - Exports: Complete list with signatures

• Functions: functionName(param: Type): ReturnType - Description _ Classes: ClassName - Description with key methods _ Types/Interfaces: TypeName - Description _ Constants: CONSTANT_NAME: Type - Description - Imports/Dependencies: What it uses and why - Used By: Files that import this (dependents) - Key Implementation Details: Important logic, algorithms, patterns - State Management: If applicable (Redux, Context, local state) - Side Effects: API calls, database queries, file I/O, external services - Error Handling: Try/catch blocks, error boundaries, validation - Testing: Associated test files and coverage - Comments/TODOs: Any inline documentation or planned work

comprehensive_file_inventory

Build dependency graph for scanned area: - Create graph with files as nodes - Add edges for import relationships - Identify circular dependencies if any - Find entry points (files not imported by others in scope) - Find leaf nodes (files that don't import others in scope)

Trace data flow through the system: - Follow function calls and data transformations - Track API calls and their responses - Document state updates and propagation - Map database queries and mutations

Identify integration points: - External APIs consumed - Internal APIs/services called - Shared state accessed - Events published/subscribed - Database tables accessed

dependency_graph data_flow_analysis integration_points

Search codebase OUTSIDE scanned area for: - Similar file/folder naming patterns - Similar function signatures - Similar component structures - Similar API patterns - Reusable utilities that could be used

Identify code reuse opportunities: - Shared utilities available - Design patterns used elsewhere - Component libraries available - Helper functions that could apply

Find reference implementations: - Similar features in other parts of codebase - Established patterns to follow - Testing approaches used elsewhere

related_code_references reuse_opportunities

Create documentation filename: deep-dive-{{sanitized_target_name}}.md Aggregate contributor insights across files: - Combine unique risk/gotcha notes into {{risks_notes}} - Combine verification steps developers should run before changes into {{verification_steps}} - Combine recommended test commands into {{suggested_tests}}

Load complete deep-dive template from: {installed_path}/templates/deep-dive-template.md Fill template with all collected data from steps 13b-13d Write filled template to: {output_folder}/deep-dive-{{sanitized_target_name}}.md Validate deep-dive document completeness

deep_dive_documentation

Update state file: - Add to deep_dive_targets array: {"target_name": "{{target_name}}", "target_path": "{{target_path}}", "files_analyzed": {{file_count}}, "output_file": "deep-dive-{{sanitized_target_name}}.md", "timestamp": "{{now}}"} - Add output to outputs_generated - Update last_updated timestamp

Read existing index.md

Check if "Deep-Dive Documentation" section exists

Add new section after "Generated Documentation":

Deep-Dive Documentation

Detailed exhaustive analysis of specific areas:

</action>

Add link to new deep-dive doc:

• {{target_name}} Deep-Dive - Comprehensive analysis of {{target_description}} ({{file_count}} files, {{total_loc}} LOC) - Generated {{date}}

  Update index metadata: Last Updated: {{date}} Deep-Dives: {{deep_dive_count}}

  Save updated index.md

  updated_index

Display summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Deep-Dive Documentation Complete! ✓

Generated: {output_folder}/deep-dive-{{target_name}}.md Files Analyzed: {{file_count}} Lines of Code Scanned: {{total_loc}} Time Taken: ~{{duration}}

Documentation Includes:

• Complete file inventory with all exports
• Dependency graph and data flow
• Integration points and API contracts
• Testing analysis and coverage
• Related code and reuse opportunities
• Implementation guidance

Index Updated: {output_folder}/index.md now includes link to this deep-dive

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Would you like to:

1. Deep-dive another area - Analyze another feature/module/folder
2. Finish - Complete workflow

Your choice [1/2]:

Clear current deep_dive_target Go to Step 13a (select new area) Display final message:

All deep-dive documentation complete!

Master Index: {output_folder}/index.md Deep-Dives Generated: {{deep_dive_count}}

These comprehensive docs are now ready for:

• Architecture review
• Implementation planning
• Code understanding
• Brownfield PRD creation

Thank you for using the document-project workflow! Exit workflow