Files

Brian Madison ab05cdcdd2 \split analyze workflow

2025-10-12 01:39:24 -05:00

53 KiB

Raw Blame History

Document Project Workflow Instructions

The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/document-project/workflow.yaml CSV files are loaded conditionally based on workflow state - NOT all at once

SMART LOADING STRATEGY: Check state file FIRST before loading any CSV files

Check for existing state file at: {output_folder}/project-scan-report.json

Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification Extract cached project_type_id(s) from state file if present Calculate age of state file (current time - last_updated)

I found an in-progress workflow state from {{last_updated}}.

Current Progress:

Mode: {{mode}}
Scan Level: {{scan_level}}
Completed Steps: {{completed_steps_count}}/{{total_steps}}
Last Step: {{current_step}}
Project Type(s): {{cached_project_types}}

Would you like to:

Resume from where we left off - Continue from step {{current_step}}
Start fresh - Archive old state and begin new scan
Cancel - Exit without changes

Your choice [1/2/3]:

<check if="user selects 1">
  <action>Set resume_mode = true</action>
  <action>Load findings summaries from state file</action>
  <action>Load cached project_type_id(s) from state file</action>

  <critical>CONDITIONAL CSV LOADING FOR RESUME:</critical>
  <action>For each cached project_type_id, load ONLY the corresponding row from: {documentation_requirements_csv}</action>
  <action>Skip loading project-types.csv and architecture_registry.csv (not needed on resume)</action>
  <action>Store loaded doc requirements for use in remaining steps</action>

  <action>Set current_step = {{resume_point}}</action>
  <action>Display: "Resuming from {{current_step}} with cached project type(s): {{cached_project_types}}"</action>
  <action>Jump to {{current_step}}</action>
</check>

<check if="user selects 2">
  <action>Create archive directory: {output_folder}/.archive/</action>
  <action>Move old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
  <action>Set resume_mode = false</action>
  <action>Continue to Step 0.5</action>
</check>

<check if="user selects 3">
  <action>Display: "Exiting workflow without changes."</action>
  <action>Exit workflow</action>
</check>

Display: "Found old state file (>24 hours). Starting fresh scan." Archive old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json Set resume_mode = false Continue to Step 0.5 CSV LOADING STRATEGY - Understanding the Documentation Requirements System:

Display explanation to user:

How Project Type Detection Works:

This workflow uses 3 CSV files to intelligently document your project:

project-types.csv ({project_types_csv})
- Contains 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
- Each type has detection_keywords used to identify project type from codebase
- Used ONLY during initial project classification (Step 1)
documentation-requirements.csv ({documentation_requirements_csv})
- 24-column schema that defines what to look for in each project type
- Columns include: requires_api_scan, requires_data_models, requires_ui_components, etc.
- Contains file patterns (key_file_patterns, critical_directories, test_file_patterns, etc.)
- Acts as a "scan guide" - tells the workflow WHERE to look and WHAT to document
- Example: For project_type_id="web", requires_api_scan=true, so workflow scans api/ folder
architecture-registry.csv ({architecture_registry_csv})
- Maps detected tech stacks to architecture templates
- Used to select appropriate architecture document template
- Only loaded when generating architecture documentation (Step 8)

When Each CSV is Loaded:

Fresh Start (initial_scan): Load project-types.csv → detect type → load corresponding doc requirements row
Resume: Load ONLY the doc requirements row(s) for cached project_type_id(s)
Full Rescan: Same as fresh start (may re-detect project type)
Deep Dive: Load ONLY doc requirements for the part being deep-dived

Now loading CSV files for fresh start... Load project-types.csv from: {project_types_csv} Store all 12 project types with their detection_keywords for use in Step 1 Display: "Loaded 12 project type definitions"

Load documentation-requirements.csv from: {documentation_requirements_csv} Store all rows indexed by project_type_id for later lookup Display: "Loaded documentation requirements for 12 project types"

Load architecture-registry.csv from: {architecture_registry_csv} Store architecture templates for later matching in Step 3 Display: "Loaded architecture template registry"

Display: "✓ CSV data files loaded successfully. Ready to begin project analysis."

Check if {output_folder}/index.md exists Read existing index.md to extract metadata (date, project structure, parts count) Store as {{existing_doc_date}}, {{existing_structure}}

I found existing documentation generated on {{existing_doc_date}}.

What would you like to do?

Re-scan entire project - Update all documentation with latest changes
Deep-dive into specific area - Generate detailed documentation for a particular feature/module/folder
Cancel - Keep existing documentation as-is

Your choice [1/2/3]:

Set workflow_mode = "full_rescan" Continue to scan level selection below Set workflow_mode = "deep_dive" Set scan_level = "exhaustive" Initialize state file with mode=deep_dive, scan_level=exhaustive Jump to Step 13 Display message: "Keeping existing documentation. Exiting workflow." Exit workflow Set workflow_mode = "initial_scan" Continue to scan level selection below

Select Scan Level

Choose your scan depth level:

1. Quick Scan (2-5 minutes) [DEFAULT]

Pattern-based analysis without reading source files
Scans: Config files, package manifests, directory structure
Best for: Quick project overview, initial understanding
File reading: Minimal (configs, README, package.json, etc.)

2. Deep Scan (10-30 minutes)

Reads files in critical directories based on project type
Scans: All critical paths from documentation requirements
Best for: Comprehensive documentation for brownfield PRD
File reading: Selective (key files in critical directories)

3. Exhaustive Scan (30-120 minutes)

Reads ALL source files in project
Scans: Every source file (excludes node_modules, dist, build)
Best for: Complete analysis, migration planning, detailed audit
File reading: Complete (all source files)

Your choice [1/2/3] (default: 1):

Set scan_level = "quick" Display: "Using Quick Scan (pattern-based, no source file reading)" Set scan_level = "deep" Display: "Using Deep Scan (reading critical files per project type)" Set scan_level = "exhaustive" Display: "Using Exhaustive Scan (reading all source files)"

Initialize state file: {output_folder}/project-scan-report.json Every time you touch the state file, record: step id, human-readable summary (what you actually did), precise timestamp, and any outputs written. Vague phrases are unacceptable. Write initial state: { "workflow_version": "1.2.0", "timestamps": {"started": "{{current_timestamp}}", "last_updated": "{{current_timestamp}}"}, "mode": "{{workflow_mode}}", "scan_level": "{{scan_level}}", "project_root": "{{project_root_path}}", "output_folder": "{{output_folder}}", "completed_steps": [], "current_step": "step_1", "findings": {}, "outputs_generated": ["project-scan-report.json"], "resume_instructions": "Starting from step 1" } Continue with standard workflow from Step 1

Ask user: "What is the root directory of the project to document?" (default: current working directory) Store as {{project_root_path}}

Scan {{project_root_path}} for key indicators:

Directory structure (presence of client/, server/, api/, src/, app/, etc.)
Key files (package.json, go.mod, requirements.txt, etc.)
Technology markers matching detection_keywords from project-types.csv

Detect if project is:

Monolith: Single cohesive codebase
Monorepo: Multiple parts in one repository
Multi-part: Separate client/server or similar architecture

List detected parts with their paths I detected multiple parts in this project: {{detected_parts_list}}

Is this correct? Should I document each part separately? [y/n]

Set repository_type = "monorepo" or "multi-part" For each detected part: - Identify root path - Run project type detection against project-types.csv - Store as part in project_parts array

Ask user to specify correct parts and their paths

Set repository_type = "monolith" Create single part in project_parts array with root_path = {{project_root_path}} Run project type detection against project-types.csv

For each part, match detected technologies and keywords against project-types.csv Assign project_type_id to each part Load corresponding documentation_requirements row for each part

I've classified this project: {{project_classification_summary}}

Does this look correct? [y/n/edit]

project_structure project_parts_metadata

IMMEDIATELY update state file with step completion:

Add to completed_steps: {"step": "step_1", "status": "completed", "timestamp": "{{now}}", "summary": "Classified as {{repository_type}} with {{parts_count}} parts"}
Update current_step = "step_2"
Update findings.project_classification with high-level summary only
CACHE project_type_id(s): Add project_types array: [{"part_id": "{{part_id}}", "project_type_id": "{{project_type_id}}", "display_name": "{{display_name}}"}]
This cached data prevents reloading all CSV files on resume - we can load just the needed documentation_requirements row(s)
Update last_updated timestamp
Write state file

PURGE detailed scan results from memory, keep only summary: "{{repository_type}}, {{parts_count}} parts, {{primary_tech}}"

For each part, scan for existing documentation using patterns: - README.md, README.rst, README.txt - CONTRIBUTING.md, CONTRIBUTING.rst - ARCHITECTURE.md, ARCHITECTURE.txt, docs/architecture/ - DEPLOYMENT.md, DEPLOY.md, docs/deployment/ - API.md, docs/api/ - Any files in docs/, documentation/, .github/ folders

Create inventory of existing_docs with:

File path
File type (readme, architecture, api, etc.)
Which part it belongs to (if multi-part)

I found these existing documentation files: {{existing_docs_list}}

Are there any other important documents or key areas I should focus on while analyzing this project? [Provide paths or guidance, or type 'none']

Store user guidance as {{user_context}}

existing_documentation_inventory user_provided_context

Update state file:

Add to completed_steps: {"step": "step_2", "status": "completed", "timestamp": "{{now}}", "summary": "Found {{existing_docs_count}} existing docs"}
Update current_step = "step_3"
Update last_updated timestamp

PURGE detailed doc contents from memory, keep only: "{{existing_docs_count}} docs found"

For each part in project_parts: - Load key_file_patterns from documentation_requirements - Scan part root for these patterns - Parse technology manifest files (package.json, go.mod, requirements.txt, etc.) - Extract: framework, language, version, database, dependencies - Build technology_table with columns: Category, Technology, Version, Justification

Match detected tech stack against architecture_registry_csv:

Use project_type_id + languages + architecture_style tags
Find closest matching architecture template
Store as {{architecture_match}} for each part

technology_stack architecture_template_matches

Update state file:

Add to completed_steps: {"step": "step_3", "status": "completed", "timestamp": "{{now}}", "summary": "Tech stack: {{primary_framework}}"}
Update current_step = "step_4"
Update findings.technology_stack with summary per part
Update last_updated timestamp

PURGE detailed tech analysis from memory, keep only: "{{framework}} on {{language}}"

BATCHING STRATEGY FOR DEEP/EXHAUSTIVE SCANS

This step requires file reading. Apply batching strategy:

Identify subfolders to process based on: - scan_level == "deep": Use critical_directories from documentation_requirements - scan_level == "exhaustive": Get ALL subfolders recursively (excluding node_modules, .git, dist, build, coverage)

For each subfolder to scan: 1. Read all files in subfolder (consider file size - use judgment for files >5000 LOC) 2. Extract required information based on conditional flags below 3. IMMEDIATELY write findings to appropriate output file 4. Validate written document (section-level validation) 5. Update state file with batch completion 6. PURGE detailed findings from context, keep only 1-2 sentence summary 7. Move to next subfolder

Track batches in state file: findings.batches_completed: [ {"path": "{{subfolder_path}}", "files_scanned": {{count}}, "summary": "{{brief_summary}}"} ]

Use pattern matching only - do NOT read source files Use glob/grep to identify file locations and patterns Extract information from filenames, directory structure, and config files only

For each part, check documentation_requirements boolean flags and execute corresponding scans:

Scan for API routes and endpoints using integration_scan_patterns Look for: controllers/, routes/, api/, handlers/, endpoints/ Use glob to find route files, extract patterns from filenames and folder structure Read files in batches (one subfolder at a time) Extract: HTTP methods, paths, request/response types from actual code

Build API contracts catalog IMMEDIATELY write to: {outputfolder}/api-contracts-{part_id}.md Validate document has all required sections Update state file with output generated PURGE detailed API data, keep only: "{{api_count}} endpoints documented" api_contracts{part_id}

Scan for data models using schema_migration_patterns Look for: models/, schemas/, entities/, migrations/, prisma/, ORM configs Identify schema files via glob, parse migration file names for table discovery Read model files in batches (one subfolder at a time) Extract: table names, fields, relationships, constraints from actual code

Build database schema documentation IMMEDIATELY write to: {outputfolder}/data-models-{part_id}.md Validate document completeness Update state file with output generated PURGE detailed schema data, keep only: "{{table_count}} tables documented" data_models{part_id}

Analyze state management patterns Look for: Redux, Context API, MobX, Vuex, Pinia, Provider patterns Identify: stores, reducers, actions, state structure state_management_patterns_{part_id} Inventory UI component library Scan: components/, ui/, widgets/, views/ folders Categorize: Layout, Form, Display, Navigation, etc. Identify: Design system, component patterns, reusable elements ui_component_inventory_{part_id} Look for hardware schematics using hardware_interface_patterns This appears to be an embedded/hardware project. Do you have: - Pinout diagrams - Hardware schematics - PCB layouts - Hardware documentation

If yes, please provide paths or links. [Provide paths or type 'none'] Store hardware docs references hardwaredocumentation{part_id}

Scan and catalog assets using asset_patterns Categorize by: Images, Audio, 3D Models, Sprites, Textures, etc. Calculate: Total size, file counts, formats used asset_inventory_{part_id}

Scan for additional patterns based on doc requirements:

config_patterns → Configuration management
auth_security_patterns → Authentication/authorization approach
entry_point_patterns → Application entry points and bootstrap
shared_code_patterns → Shared libraries and utilities
async_event_patterns → Event-driven architecture
ci_cd_patterns → CI/CD pipeline details
localization_patterns → i18n/l10n support

Apply scan_level strategy to each pattern scan (quick=glob only, deep/exhaustive=read files)

comprehensiveanalysis{part_id}

Update state file:

Add to completed_steps: {"step": "step_4", "status": "completed", "timestamp": "{{now}}", "summary": "Conditional analysis complete, {{files_generated}} files written"}
Update current_step = "step_5"
Update last_updated timestamp
List all outputs_generated

PURGE all detailed scan results from context. Keep only summaries:

"APIs: {{api_count}} endpoints"
"Data: {{table_count}} tables"
"Components: {{component_count}} components"

For each part, generate complete directory tree using critical_directories from doc requirements

Annotate the tree with:

Purpose of each critical directory
Entry points marked
Key file locations highlighted
Integration points noted (for multi-part projects)

Show how parts are organized and where they interface

Create formatted source tree with descriptions:

project-root/
├── client/          # React frontend (Part: client)
│   ├── src/
│   │   ├── components/  # Reusable UI components
│   │   ├── pages/       # Route-based pages
│   │   └── api/         # API client layer → Calls server/
├── server/          # Express API backend (Part: api)
│   ├── src/
│   │   ├── routes/      # REST API endpoints
│   │   ├── models/      # Database models
│   │   └── services/    # Business logic

source_tree_analysis critical_folders_summary

IMMEDIATELY write source-tree-analysis.md to disk Validate document structure Update state file:

Add to completed_steps: {"step": "step_5", "status": "completed", "timestamp": "{{now}}", "summary": "Source tree documented"}
Update current_step = "step_6"
Add output: "source-tree-analysis.md" PURGE detailed tree from context, keep only: "Source tree with {{folder_count}} critical folders"

Scan for development setup using key_file_patterns and existing docs: - Prerequisites (Node version, Python version, etc.) - Installation steps (npm install, etc.) - Environment setup (.env files, config) - Build commands (npm run build, make, etc.) - Run commands (npm start, go run, etc.) - Test commands using test_file_patterns

Look for deployment configuration using ci_cd_patterns:

Dockerfile, docker-compose.yml
Kubernetes configs (k8s/, helm/)
CI/CD pipelines (.github/workflows/, .gitlab-ci.yml)
Deployment scripts
Infrastructure as Code (terraform/, pulumi/)

Extract contribution guidelines: - Code style rules - PR process - Commit conventions - Testing requirements

development_instructions deployment_configuration contribution_guidelines

Update state file:

Add to completed_steps: {"step": "step_6", "status": "completed", "timestamp": "{{now}}", "summary": "Dev/deployment guides written"}
Update current_step = "step_7"
Add generated outputs to list PURGE detailed instructions, keep only: "Dev setup and deployment documented"

Analyze how parts communicate: - Scan integration_scan_patterns across parts - Identify: REST calls, GraphQL queries, gRPC, message queues, shared databases - Document: API contracts between parts, data flow, authentication flow

Create integration_points array with:

from: source part
to: target part
type: REST API, GraphQL, gRPC, Event Bus, etc.
details: Endpoints, protocols, data formats

IMMEDIATELY write integration-architecture.md to disk Validate document completeness

integration_architecture

Update state file:

Add to completed_steps: {"step": "step_7", "status": "completed", "timestamp": "{{now}}", "summary": "Integration architecture documented"}
Update current_step = "step_8" PURGE integration details, keep only: "{{integration_count}} integration points"

For each part in project_parts: - Use matched architecture template from Step 3 as base structure - Fill in all sections with discovered information: * Executive Summary * Technology Stack (from Step 3) * Architecture Pattern (from registry match) * Data Architecture (from Step 4 data models scan) * API Design (from Step 4 API scan if applicable) * Component Overview (from Step 4 component scan if applicable) * Source Tree (from Step 5) * Development Workflow (from Step 6) * Deployment Architecture (from Step 6) * Testing Strategy (from test patterns) - Generate: architecture.md (no part suffix) - Generate: architecture-{part_id}.md for each part

For each architecture file generated:

IMMEDIATELY write architecture file to disk
Validate against architecture template schema
Update state file with output
PURGE detailed architecture from context, keep only: "Architecture for {{part_id}} written"

architecture_document

Update state file:

Add to completed_steps: {"step": "step_8", "status": "completed", "timestamp": "{{now}}", "summary": "Architecture docs written for {{parts_count}} parts"}
Update current_step = "step_9"

Generate project-overview.md with: - Project name and purpose (from README or user input) - Executive summary - Tech stack summary table - Architecture type classification - Repository structure (monolith/monorepo/multi-part) - Links to detailed docs

Generate source-tree-analysis.md with:

Full annotated directory tree from Step 5
Critical folders explained
Entry points documented
Multi-part structure (if applicable)

IMMEDIATELY write project-overview.md to disk Validate document sections

Generate source-tree-analysis.md (if not already written in Step 5) IMMEDIATELY write to disk and validate

Generate component-inventory.md (or per-part versions) with:

All discovered components from Step 4
Categorized by type
Reusable vs specific components
Design system elements (if found) IMMEDIATELY write each component inventory to disk and validate

Generate development-guide.md (or per-part versions) with:

Prerequisites and dependencies
Environment setup instructions
Local development commands
Build process
Testing approach and commands
Common development tasks IMMEDIATELY write each development guide to disk and validate

Generate deployment-guide.md with: - Infrastructure requirements - Deployment process - Environment configuration - CI/CD pipeline details IMMEDIATELY write to disk and validate Generate contribution-guide.md with: - Code style and conventions - PR process - Testing requirements - Documentation standards IMMEDIATELY write to disk and validate Generate api-contracts.md (or per-part) with: - All API endpoints - Request/response schemas - Authentication requirements - Example requests IMMEDIATELY write to disk and validate Generate data-models.md (or per-part) with: - Database schema - Table relationships - Data models and entities - Migration strategy IMMEDIATELY write to disk and validate Generate integration-architecture.md with: - How parts communicate - Integration points diagram/description - Data flow between parts - Shared dependencies IMMEDIATELY write to disk and validate

Generate project-parts.json metadata file: json { "repository_type": "monorepo", "parts": [ ... ], "integration_points": [ ... ] } IMMEDIATELY write to disk

supporting_documentation

Update state file:

Add to completed_steps: {"step": "step_9", "status": "completed", "timestamp": "{{now}}", "summary": "All supporting docs written"}
Update current_step = "step_10"
List all newly generated outputs

PURGE all document contents from context, keep only list of files generated

Create index.md with intelligent navigation based on project structure Generate simple index with: - Project name and type - Quick reference (tech stack, architecture type) - Links to all generated docs - Links to discovered existing docs - Getting started section Generate comprehensive index with: - Project overview and structure summary - Part-based navigation section - Quick reference by part - Cross-part integration links - Links to all generated and existing docs - Getting started per part

Include in index.md:

Project Documentation Index

Project Overview

Type: {{repository_type}} {{#if multi-part}}with {{parts.length}} parts{{/if}}
Primary Language: {{primary_language}}
Architecture: {{architecture_type}}

Quick Reference

Tech Stack: {{tech_stack_summary}}
Entry Point: {{entry_point}}
Architecture Pattern: {{architecture_pattern}} {{else}} {{#each parts}}

{{part_name}} ({{part_id}})

Type: {{project_type}}
Tech Stack: {{tech_stack}}
Root: {{root_path}} {{/each}} {{/if}}

Generated Documentation

Project Overview
[Architecture](./architecture{{#if multi-part}}-{part_id}{{/if}}.md)
Source Tree Analysis
[Component Inventory](./component-inventory{{#if multi-part}}-{part_id}{{/if}}.md)
[Development Guide](./development-guide{{#if multi-part}}-{part_id}{{/if}}.md) {{#if deployment_found}}- Deployment Guide{{/if}} {{#if contribution_found}}- Contribution Guide{{/if}} {{#if api_documented}}- [API Contracts](./api-contracts{{#if multi-part}}-{part_id}{{/if}}.md){{/if}} {{#if data_models_documented}}- [Data Models](./data-models{{#if multi-part}}-{part_id}{{/if}}.md){{/if}} {{#if multi-part}}- Integration Architecture{{/if}}

Existing Documentation

{{title}} - {{description}} {{/each}}

Getting Started

IMMEDIATELY write index.md to disk Validate index has all required sections and links are valid

index

Update state file:

Add to completed_steps: {"step": "step_10", "status": "completed", "timestamp": "{{now}}", "summary": "Master index generated"}
Update current_step = "step_11"
Add output: "index.md"

PURGE index content from context

Show summary of all generated files: Generated in {{output_folder}}/: {{file_list_with_sizes}}

Run validation checklist from {validation}

Documentation generation complete!

Summary:

Project Type: {{project_type_summary}}
Parts Documented: {{parts_count}}
Files Generated: {{files_count}}
Total Lines: {{total_lines}}

Would you like to:

Review any specific section [type section name]
Add more detail to any area [type area name]
Generate additional documentation [describe what]
Finalize and complete [type 'done']

Your choice:

Make requested modifications and regenerate affected files Proceed to completion

Update state file:

Add to completed_steps: {"step": "step_11", "status": "completed", "timestamp": "{{now}}", "summary": "Validation complete"}
Update current_step = "step_12"

Create final summary report Compile verification recap variables: - Set {{verification_summary}} to the concrete tests, validations, or scripts you executed (or "none run"). - Set {{open_risks}} to any remaining risks or TODO follow-ups (or "none"). - Set {{next_checks}} to recommended actions before merging/deploying (or "none").

Display completion message:

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

Project Documentation Complete! ✓

Location: {{output_folder}}/

Master Index: {{output_folder}}/index.md 👆 This is your primary entry point for AI-assisted development

Generated Documentation: {{generated_files_list}}

Next Steps:

Review the index.md to familiarize yourself with the documentation structure
When creating a brownfield PRD, point the PRD workflow to: {{output_folder}}/index.md
For UI-only features: Reference {{output_folder}}/architecture-{{ui_part_id}}.md
For API-only features: Reference {{output_folder}}/architecture-{{api_part_id}}.md
For full-stack features: Reference both part architectures + integration-architecture.md

Verification Recap:

Tests/extractions executed: {{verification_summary}}
Outstanding risks or follow-ups: {{open_risks}}
Recommended next checks before PR: {{next_checks}}

Brownfield PRD Command: When ready to plan new features, run the PRD workflow and provide this index as input.

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

FINALIZE state file:

Add to completed_steps: {"step": "step_12", "status": "completed", "timestamp": "{{now}}", "summary": "Workflow complete"}
Update timestamps.completed = "{{now}}"
Update current_step = "completed"
Write final state file

Display: "State file saved: {{output_folder}}/project-scan-report.json"

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:

API Routes ({{api_route_count}} endpoints found)

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

Feature Modules ({{feature_count}} features)

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

UI Component Areas

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

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 Use template from: {installed_path}/templates/deep-dive-template.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}}

Generate complete documentation with:

{{target_name}} - Deep Dive Documentation

Generated: {{date}} Scope: {{target_path}} Files Analyzed: {{file_count}} Lines of Code: {{total_loc}} Workflow Mode: Exhaustive Deep-Dive

Overview

Purpose: {{target_purpose}} Key Responsibilities: {{responsibilities}} Integration Points: {{integration_summary}}

Complete File Inventory

Purpose: {{purpose}} Lines of Code: {{loc}} File Type: {{file_type}}

What Future Contributors Must Know: {{contributor_note}}

Exports: {{#each exports}}

{{signature}} - {{description}} {{/each}}

Dependencies: {{#each imports}}

{{import_path}} - {{reason}} {{/each}}

Used By: {{#each dependents}}

{{dependent_path}} {{/each}}

Key Implementation Details:

{{key_code_snippet}}

Patterns Used: {{#each patterns}}

{{pattern_name}}: {{pattern_description}} {{/each}}

State Management: {{state_approach}}

Side Effects: {{#each side_effects}}

{{effect_type}}: {{effect_description}} {{/each}}

Error Handling: {{error_handling_approach}}

Testing:

Test File: {{test_file_path}}
Coverage: {{coverage_percentage}}%
Test Approach: {{test_approach}}

Comments/TODOs: {{#each todos}}

Line {{line_number}}: {{todo_text}} {{/each}}

Contributor Checklist

Risks & Gotchas: {{risks_notes}}
Pre-change Verification Steps: {{verification_steps}}
Suggested Tests Before PR: {{suggested_tests}}

Architecture & Design Patterns

Code Organization

Design Patterns

{{pattern_name}}: {{usage_description}} {{/each}}

State Management Strategy

Error Handling Philosophy

Testing Strategy

Data Flow

Data Entry Points

{{entry_name}}: {{entry_description}} {{/each}}

Data Transformations

{{transformation_name}}: {{transformation_description}} {{/each}}

Data Exit Points

{{exit_name}}: {{exit_description}} {{/each}}

Integration Points

APIs Consumed

{{api_endpoint}}: {{api_description}}
- Method: {{method}}
- Authentication: {{auth_requirement}}
- Response: {{response_schema}} {{/each}}

APIs Exposed

{{api_endpoint}}: {{api_description}}
- Method: {{method}}
- Request: {{request_schema}}
- Response: {{response_schema}} {{/each}}

Shared State

{{state_name}}: {{state_description}}
- Type: {{state_type}}
- Accessed By: {{accessors}} {{/each}}

Events

{{event_name}}: {{event_description}}
- Type: {{publish_or_subscribe}}
- Payload: {{payload_schema}} {{/each}}

Database Access

{{table_name}}: {{operation_type}}
- Queries: {{query_patterns}}
- Indexes Used: {{indexes}} {{/each}}

Dependency Graph

Entry Points (Not Imported by Others in Scope)

{{file_path}} {{/each}}

Leaf Nodes (Don't Import Others in Scope)

{{file_path}} {{/each}}

Circular Dependencies

{{#if has_circular_dependencies}} ⚠️ Circular dependencies detected: {{#each circular_deps}}

{{cycle_description}} {{/each}} {{else}} ✓ No circular dependencies detected {{/if}}

Testing Analysis

Test Coverage Summary

Statements: {{statements_coverage}}%
Branches: {{branches_coverage}}%
Functions: {{functions_coverage}}%
Lines: {{lines_coverage}}%

Test Files

{{test_file_path}}
- Tests: {{test_count}}
- Approach: {{test_approach}}
- Mocking Strategy: {{mocking_strategy}} {{/each}}

Test Utilities Available

{{utility_name}}: {{utility_description}} {{/each}}

Testing Gaps

{{gap_description}} {{/each}}

Similar Features Elsewhere

{{feature_name}} ({{feature_path}})
- Similarity: {{similarity_description}}
- Can Reference For: {{reference_use_case}} {{/each}}

Reusable Utilities Available

{{utility_name}} ({{utility_path}})
- Purpose: {{utility_purpose}}
- How to Use: {{usage_example}} {{/each}}

Patterns to Follow

{{pattern_name}}: Reference {{reference_file}} for implementation {{/each}}

Implementation Notes

Code Quality Observations

{{observation}} {{/each}}

TODOs and Future Work

{{file_path}}:{{line_number}}: {{todo_text}} {{/each}}

Known Issues

{{issue_description}} {{/each}}

Optimization Opportunities

{{optimization_suggestion}} {{/each}}

Technical Debt

{{debt_description}} {{/each}}

Modification Guidance

To Add New Functionality

To Modify Existing Functionality

To Remove/Deprecate

Testing Checklist for Changes

{{checklist_item}} {{/each}}

Generated by document-project workflow (deep-dive mode) Base Documentation: docs/index.md Scan Date: {{date}} Analysis Mode: Exhaustive

Save documentation 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:

Deep-dive another area - Analyze another feature/module/folder
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

53 KiB Raw Blame History

Document Project Workflow Instructions

Project Documentation Index

Project Overview

Quick Reference

{{part_name}} ({{part_id}})

Generated Documentation

Existing Documentation

Getting Started

Project Documentation Complete! ✓

API Routes ({{api_route_count}} endpoints found)

Feature Modules ({{feature_count}} features)

UI Component Areas

Services/Business Logic

{{target_name}} - Deep Dive Documentation

Overview

Complete File Inventory

{{file_path}}

Contributor Checklist

Architecture & Design Patterns

Code Organization

Design Patterns

State Management Strategy

Error Handling Philosophy

Testing Strategy

Data Flow

Data Entry Points

Data Transformations

Data Exit Points

Integration Points

APIs Consumed

APIs Exposed

Shared State

Events

Database Access

Dependency Graph

Entry Points (Not Imported by Others in Scope)

Leaf Nodes (Don't Import Others in Scope)

Circular Dependencies

Testing Analysis

Test Coverage Summary

Test Files

Test Utilities Available

Testing Gaps

Related Code & Reuse Opportunities

Similar Features Elsewhere

Reusable Utilities Available

Patterns to Follow

Implementation Notes

Code Quality Observations

TODOs and Future Work

Known Issues

Optimization Opportunities

Technical Debt

Modification Guidance

To Add New Functionality

To Modify Existing Functionality

To Remove/Deprecate

Testing Checklist for Changes

Deep-Dive Documentation

Deep-Dive Documentation Complete! ✓

53 KiB

Raw Blame History