@cloudkinetix/bmad-enhanced/expansion-packs/ck-parallel-dev/utils/report-manager.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# Parallel-Dev Report Management Utility

> 📊 **Report Manager** - Manage pre-execution reports, execution plans, and audit trails

## Purpose

Provides utilities for managing the reports generated by parallel-dev runs, including:

- Listing and searching runs
- Viewing reports and execution status
- Cleaning up old runs
- Archiving important runs
- Analyzing patterns for process improvement

## Commands

### List All Runs

```bash
# List all parallel-dev runs
ls -la .bmad-workspace/ck-parallel-dev/runs/

# List with human-readable dates
find .bmad-workspace/ck-parallel-dev/runs -maxdepth 1 -type d -name "2*" | sort -r | head -20

# Show runs with status
for dir in .bmad-workspace/ck-parallel-dev/runs/*/; do
    if [[ -f "$dir/execution-plan.json" ]]; then
        echo -n "$(basename $dir): "
        jq -r '.validation_results.recommendation' "$dir/execution-plan.json" 2>/dev/null || echo "UNKNOWN"
    fi
done
```

### View Latest Run

```bash
# Create symlink to latest run (run after each execution)
ln -sfn "$(ls -t .bmad-workspace/ck-parallel-dev/runs/ | grep -E '^[0-9]{8}-[0-9]{6}' | head -1)" .bmad-workspace/ck-parallel-dev/runs/latest

# View latest report
cat .bmad-workspace/ck-parallel-dev/runs/latest/pre-execution-report.md

# Check latest status
jq '.validation_results' .bmad-workspace/ck-parallel-dev/runs/latest/execution-plan.json
```

### Search Runs

```bash
# Find runs with warnings
find .bmad-workspace/ck-parallel-dev/runs -name "execution-plan.json" -exec grep -l '"overrides_used": [1-9]' {} \; | xargs -I {} dirname {}

# Find failed runs
find .bmad-workspace/ck-parallel-dev/runs -name "execution-plan.json" -exec grep -l '"recommendation": "ABORT"' {} \; | xargs -I {} dirname {}

# Find runs by date
ls .bmad-workspace/ck-parallel-dev/runs/ | grep "^20250703"  # All runs from July 3, 2025
```

## Report Analysis Tasks

### Analyze Override Patterns

```yaml
[[LLM: Analyze which validation warnings are most frequently overridden]]

TASK: Override Pattern Analysis

1. Scan all execution plans for overrides:
   find .bmad-workspace/ck-parallel-dev/runs -name "execution-plan.json" | \
   xargs jq '.work_items[].validation_status.warnings[] | select(.overridden == true)'

2. Group by rule type and count occurrences

3. Analyze justifications for common patterns

4. Generate recommendations:
   - Rules that may be too strict
   - Teams that override frequently
   - Common justification themes

OUTPUT: Override analysis report with actionable insights
```

### Generate Run Summary

```yaml
[[LLM: Create summary of recent parallel-dev activity]]

TASK: Run Summary Generation

1. Collect data from last 30 days of runs
2. Calculate metrics:
   - Total runs
   - Success rate
   - Average execution time
   - Most common issues
   - Rollback frequency

3. Identify trends:
   - Increasing/decreasing success rate
   - Common failure patterns
   - Peak usage times

OUTPUT: Executive summary with charts and recommendations
```

### Cleanup Old Runs

```bash
#!/bin/bash
# Clean up runs older than 30 days

RETENTION_DAYS=30
ARCHIVE_DIR=".bmad-workspace/ck-parallel-dev/archive"

# Create archive directory
mkdir -p "$ARCHIVE_DIR"

# Find old runs
find .bmad-workspace/ck-parallel-dev/runs -maxdepth 1 -type d -name "2*" -mtime +$RETENTION_DAYS | while read -r dir; do
    run_id=$(basename "$dir")

    # Archive important files
    if [[ -f "$dir/execution-plan.json" ]]; then
        # Check if this was a failed or interesting run
        recommendation=$(jq -r '.validation_results.recommendation' "$dir/execution-plan.json" 2>/dev/null)

        if [[ "$recommendation" == "ABORT" ]] || [[ -f "$dir/rollback-executed" ]]; then
            # Archive the entire run
            echo "Archiving important run: $run_id"
            tar -czf "$ARCHIVE_DIR/$run_id.tar.gz" -C "$dir" .
        fi
    fi

    # Remove the run directory
    echo "Removing old run: $run_id"
    rm -rf "$dir"
done

echo "Cleanup complete. Retained runs from last $RETENTION_DAYS days."
```

### Archive Important Run

```bash
#!/bin/bash
# Archive a specific run for long-term storage

RUN_ID="${1:-latest}"
ARCHIVE_DIR=".bmad-workspace/ck-parallel-dev/archive"

# Resolve run directory
if [[ "$RUN_ID" == "latest" ]]; then
    RUN_DIR=".bmad-workspace/ck-parallel-dev/runs/latest"
    RUN_ID=$(readlink "$RUN_DIR" | xargs basename)
else
    RUN_DIR=".bmad-workspace/ck-parallel-dev/runs/$RUN_ID"
fi

if [[ ! -d "$RUN_DIR" ]]; then
    echo "Run not found: $RUN_ID"
    exit 1
fi

# Create archive
mkdir -p "$ARCHIVE_DIR"
tar -czf "$ARCHIVE_DIR/$RUN_ID.tar.gz" -C "$RUN_DIR" .

# Add metadata
cat > "$ARCHIVE_DIR/$RUN_ID.meta" <<EOF
archived_at: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
original_path: $RUN_DIR
size: $(du -sh "$ARCHIVE_DIR/$RUN_ID.tar.gz" | cut -f1)
reason: ${2:-"Manual archive"}
EOF

echo "Archived run $RUN_ID to $ARCHIVE_DIR/$RUN_ID.tar.gz"
```

### Restore Archived Run

```bash
#!/bin/bash
# Restore an archived run

RUN_ID="$1"
ARCHIVE_DIR=".bmad-workspace/ck-parallel-dev/archive"
RESTORE_DIR=".bmad-workspace/ck-parallel-dev/runs/$RUN_ID-restored"

if [[ ! -f "$ARCHIVE_DIR/$RUN_ID.tar.gz" ]]; then
    echo "Archive not found: $RUN_ID"
    exit 1
fi

# Restore
mkdir -p "$RESTORE_DIR"
tar -xzf "$ARCHIVE_DIR/$RUN_ID.tar.gz" -C "$RESTORE_DIR"

echo "Restored run to: $RESTORE_DIR"
```

## Integration with parallel-dev Command

### Status Command Implementation

When user runs `/parallel-dev:status`, show:

```
Current Parallel-Dev Status
━━━━━━━━━━━━━━━━━━━━━━━━━

Active Worktrees:
- bg-login (parallel/bg-login) - ../bg-login
- ft-dash (parallel/ft-dash) - ../ft-dash

Recent Runs:
- 20250703-151230-abc123 ✅ COMPLETED (2 items, 45 min)
- 20250703-143015-def456 ⚠️ PARTIAL (3 items, 1 failed)
- 20250703-120530-ghi789 ✅ COMPLETED (4 items, 62 min)

Latest Run: .bmad-workspace/ck-parallel-dev/runs/latest -> 20250703-151230-abc123

Storage Usage: 124 MB (23 runs)
```

### Report Command

```bash
# View specific report
/parallel-dev:report 20250703-151230-abc123

# View latest report
/parallel-dev:report latest

# List all reports
/parallel-dev:report --list
```

## Best Practices

1. **Regular Cleanup**: Run cleanup weekly to manage disk space
2. **Archive Important Runs**: Keep failed runs and rollbacks for analysis
3. **Analyze Patterns**: Monthly review of override patterns
4. **Document Lessons**: Update validation rules based on patterns
5. **Monitor Storage**: Set alerts for .bmad-workspace/ck-parallel-dev/ directory size

## Troubleshooting

### Corrupted Reports

```bash
# Validate JSON files
find .bmad-workspace/ck-parallel-dev/runs -name "*.json" -exec jq empty {} \; -print 2>&1 | grep -B1 "parse error"

# Remove corrupted runs
rm -rf .bmad-workspace/ck-parallel-dev/runs/[corrupted-run-id]
```

### Missing Reports

```bash
# Check if reports were generated
ls -la .bmad-workspace/ck-parallel-dev/runs/*/pre-execution-report.md

# Regenerate latest symlink
rm -f .bmad-workspace/ck-parallel-dev/runs/latest
ln -sfn "$(ls -t .bmad-workspace/ck-parallel-dev/runs/ | grep -E '^[0-9]{8}-[0-9]{6}' | head -1)" .bmad-workspace/ck-parallel-dev/runs/latest
```

## Report Metrics Dashboard

```yaml
[[LLM: When asked for metrics, generate a dashboard view]]

PARALLEL-DEV METRICS DASHBOARD
════════════════════════════════

Last 30 Days:
┌─────────────────┬────────┐
│ Total Runs      │   47   │
│ Success Rate    │  91%   │
│ Avg Duration    │ 38 min │
│ Rollbacks       │   2    │
└─────────────────┴────────┘

Top Override Rules:
1. NO_DEV_NOTES (23 times)
2. MISSING_TEST_SPECS (15 times)
3. HIGH_COMPLEXITY (8 times)

Busiest Days:
Mon: ████████████ 12 runs
Tue: ████████ 8 runs
Wed: ██████████ 10 runs

Recommendations:
- Consider relaxing NO_DEV_NOTES for bug fixes
- Schedule heavy parallel work for Mondays
- Archive runs older than 30 days (save 89 MB)
```