@cloudkinetix/bmad-enhanced

# Task: Generate Pre-Execution Report > 📋 **Pre-Flight Documentation** - Creates comprehensive report and execution plan before parallel development begins ## Description Generates a detailed pre-execution report and machine-readable execution plan for parallel development runs. This provides transparency, enables user review, and creates an audit trail for potential rollbacks. ## Purpose - **Transparency**: Show users exactly what will be executed - **Risk Assessment**: Identify potential issues before they occur - **Audit Trail**: Document decisions for future reference - **Rollback Support**: Enable clean rollback with documented steps - **User Confidence**: Let users review and approve execution plans ## Input Requirements ```yaml command: Original /parallel-dev command from user work_items: - description: User's work description worktree: Worktree name validation_results: Results from story validation conflict_analysis: Results from conflict detection wave_plan: Proposed execution waves ``` ## Process Flow ### Step 1: Initialize Run Context ```yaml [[LLM: Create unique run ID and setup directory structure]] GENERATE_RUN_ID: format: YYYYMMDD-HHMMSS-RANDOM example: 20250703-151230-abc123 CREATE_RUN_DIRECTORY: path: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/ subdirs: - reports/ - logs/ - backups/ ``` ### Step 2: Gather System State ```yaml [[LLM: Collect current system state for report]] SYSTEM_STATE: - Git branch status - Test suite status - Disk space available - Recent commit history - Active worktrees VALIDATION_STATE: - Critical issues: count - Warnings: list with override status - Suggestions: list - Overall risk assessment SEMANTIC_ANALYSIS: - Invoke LLM dependency analyzer - Gather hidden dependencies - Assess architectural impacts - Calculate confidence metrics ``` ### Step 3: Analyze Work Items with Semantic Intelligence ```yaml [[LLM: Deep semantic analysis of each work item]] FOR_EACH_WORK_ITEM: semantic_analysis: - Code purpose understanding - API contract impacts - Hidden dependencies - Business logic connections - Architectural implications traditional_analysis: - Complexity estimation - File impact prediction - Conflict zones - Direct dependencies - Risk factors assign: - Innovation dimension - Agent specifications - Success criteria - Confidence levels ``` ### Step 4: Generate Execution Plan JSON ```yaml [[LLM: Create machine-readable execution plan]] EXECUTION_PLAN: schema_version: "1.0" run_id: {{generated-id}} work_items: - Complete specifications - Validation results - Agent configurations wave_plan: - Execution waves with rationale - Conflict resolutions - Timing estimates execution_commands: - Pre-computed git commands - Task agent prompts - Cleanup procedures rollback_info: - Strategy selection - Manual steps if needed - Recovery commands VALIDATE_AGAINST_SCHEMA: - Load templates/execution-plan-schema.json - Validate generated plan structure - Ensure all required fields present - Verify enum values are valid - Fail task if validation errors SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/execution-plan.json ``` ### Step 5: Generate Human-Readable Report ```yaml [[LLM: Create markdown report from template]] REPORT_SECTIONS: - Executive Summary with Go/No-Go recommendation - Quick Decision Matrix - 🧠 Semantic Dependency Analysis (NEW) - Detailed Work Item Analysis - Wave Planning with visual representation - Risk Assessment (High/Medium/Low) - Resource Requirements - Pre-Flight Checklist - Execution Plan summary - Approval section ENHANCE_WITH: - Visual indicators (✅ ⚠️ ❌) - Clear formatting - Actionable insights - Override documentation - Semantic analysis integration - Confidence indicators - Links to detailed reports SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/pre-execution-report.md GENERATE_SEMANTIC_REPORTS: - Invoke generate-semantic-analysis-report task - Create semantic-analysis.md - Create user-review.md - Create dependency-matrix.json ``` ### Step 6: Generate Rollback Guide ```yaml [[LLM: Create rollback documentation]] ROLLBACK_GUIDE: - Quick rollback commands - Strategy selection (automated vs manual) - Step-by-step procedures - Troubleshooting section - Verification steps - Recovery data SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/rollback-guide.md ``` ### Step 7: Create Execution Script ```yaml [[LLM: Optional - create executable script]] EXECUTION_SCRIPT: #!/bin/bash # Auto-generated execution script for run {{run-id}} # Pre-flight checks {{validation commands}} # Setup worktrees {{worktree creation commands}} # Wave execution {{wave execution logic}} # Cleanup {{cleanup commands}} SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/execute.sh CHMOD: +x ``` ## Output Structure ``` .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/ ├── pre-execution-report.md # Enhanced with semantic analysis ├── semantic-analysis.md # Detailed dependency analysis ├── user-review.md # Interactive review document ├── dependency-matrix.json # Machine-readable dependencies ├── execution-plan.json # Machine-readable plan ├── rollback-guide.md # Rollback documentation ├── execute.sh # Optional execution script └── metadata.json # Run metadata ``` ## Integration Points ### With Validation System - Incorporates validation results - Documents override justifications - Tracks warning acknowledgments ### With Conflict Analysis - Uses conflict detection results - Explains wave planning decisions - Shows file overlap clearly ### With Parallel Executor - Provides execution plan - Pre-computed agent prompts - Wave sequencing logic ## Example Usage ```bash # User command /parallel-dev "Fix login" bg-1 "Add charts" ft-2 # System generates report Generating pre-execution report... ✅ Validation complete (1 warning overridden) ✅ Conflict analysis complete (no conflicts) ✅ Execution plan created 📄 Report generated: .bmad-workspace/ck-parallel-dev/runs/20250703-151230-abc123/pre-execution-report.md Review the report above. Proceed with execution? (y/N) ``` ## Report Highlights ### Executive Summary Section ```markdown **Go/No-Go Recommendation**: PROCEED ✅ **Risk Level**: LOW **Estimated Duration**: 45 minutes **Total Work Items**: 2 **Execution Waves**: 1 (all parallel) **Semantic Analysis Confidence**: 85% All validations passed. No file conflicts detected. 3 hidden dependencies identified and mitigated. System resources adequate. Recommended to proceed. ``` ### Quick Decision Matrix ```markdown | Criteria | Status | Impact | | ----------------------- | ------ | -------- | | All validations passed | ✅ | Critical | | No file conflicts | ✅ | Critical | | Tests currently passing | ✅ | Warning | | Disk space available | ✅ | Info | ``` ### Risk Assessment ```markdown ### 🟢 Low Risks - Normal development risks only - All work items independent - Rollback straightforward ### 🧠 Semantic Analysis Insights - **Hidden Dependencies Found**: 3 - **Architectural Impacts**: Minor - **API Contract Changes**: None - **Confidence Level**: 85% [View Full Semantic Analysis](./semantic-analysis.md) [Provide Feedback on Analysis](./user-review.md) ``` ## Best Practices 1. **Always Generate**: Never skip report generation 2. **User Review**: Always prompt for approval 3. **Archive Reports**: Keep for audit trail 4. **Update Templates**: Improve based on usage 5. **Track Metrics**: Monitor override patterns ## Error Handling ### Report Generation Fails - Abort execution immediately - Show error clearly with context - Suggest manual execution steps - Log error to .bmad-workspace/ck-parallel-dev/errors.log ### Disk Space Issues - Check available space before generating - Warn in report if < 100MB free - Calculate space needs (estimate 5MB per run) - Suggest cleanup with specific commands ### Template Missing ```yaml TEMPLATE_FALLBACK: - Try loading from templates/ directory - If missing, check for embedded templates - If still missing, use minimal defaults: pre_execution_report: - Basic executive summary - Simple work item list - Minimal risk assessment execution_plan: - Required fields only - Basic wave structure rollback_guide: - Manual rollback steps only - Log warning about missing templates - Continue execution with degraded functionality ``` ### Schema Validation Fails - Log specific validation errors - Show which fields are invalid - Provide example of correct format - Abort if critical fields missing - Allow override with --skip-validation flag ## Success Metrics - Reports generated < 10 seconds - User understanding > 90% - Rollback success rate > 95% - Override patterns tracked - Process improvements identified