# 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