# Workflow to detect and fix documentation drift in the Prodigy book
# This workflow analyzes the codebase and updates book/src/*.md files
# to reflect the latest supported features and syntax.

name: prodigy-book-docs-drift-detection
mode: mapreduce

# Environment variables for parameterization
env:
  # Project configuration
  PROJECT_NAME: "Debtmap"
  PROJECT_CONFIG: ".prodigy/book-config.json"
  FEATURES_PATH: ".prodigy/book-analysis/features.json"

  # Book-specific settings
  BOOK_DIR: "book"
  ANALYSIS_DIR: ".prodigy/book-analysis"
  CHAPTERS_FILE: "workflows/data/prodigy-chapters.json"

  # Workflow settings
  MAX_PARALLEL: "3"

# Setup phase: Analyze codebase for feature coverage
setup:
  - shell: "mkdir -p $ANALYSIS_DIR"

  # Step 1: Analyze codebase for workflow features, command types, and configuration
  # Note: May not commit if features haven't changed since last analysis
  - claude: "/prodigy-analyze-features-for-book --project $PROJECT_NAME --config $PROJECT_CONFIG"

  # Step 2: Detect documentation gaps and create missing chapters/subsections
  # Also generates flattened-items.json for map phase (single-file chapters + subsections with parent metadata)
  # Note: May not commit if no gaps found, which is a successful outcome
  - claude: "/prodigy-detect-documentation-gaps --project $PROJECT_NAME --config $PROJECT_CONFIG --features $FEATURES_PATH --chapters $CHAPTERS_FILE --book-dir $BOOK_DIR"

  # Step 3: Analyze chapter sizes and structural complexity
  # Identifies oversized chapters that should be split into subsections
  # Generates structure-report.json with recommendations
  - claude: "/prodigy-analyze-chapter-structure --project $PROJECT_NAME --book-dir $BOOK_DIR --chapters $CHAPTERS_FILE --output $ANALYSIS_DIR/structure-report.json"

  # Step 4: Automatically split all oversized chapters into subsections
  # This runs BEFORE map phase so agents process optimally-sized chapters
  # Reads structure-report.json and orchestrates splitting of high-priority chapters
  # NOTE: This command creates a comprehensive commit in Phase 7 after splitting all chapters
  #       OR exits successfully if no chapters need splitting (valid success state)
  - claude: "/prodigy-split-oversized-chapters --project $PROJECT_NAME --chapters $CHAPTERS_FILE --book-dir $BOOK_DIR --structure-report $ANALYSIS_DIR/structure-report.json"

  # Step 5: Regenerate flattened-items.json after structure changes
  # This ensures map phase processes all chapters (including newly split subsections)
  - claude: "/prodigy-detect-documentation-gaps --project $PROJECT_NAME --config $PROJECT_CONFIG --features $FEATURES_PATH --chapters $CHAPTERS_FILE --book-dir $BOOK_DIR"

# Map phase: Analyze and fix each book chapter/subsection for drift
map:
  input: "${ANALYSIS_DIR}/flattened-items.json"
  json_path: "$[*]"

  agent_template:
    # Step 1: Analyze the chapter/subsection for drift (subsection-aware command)
    - claude: "/prodigy-analyze-subsection-drift --project $PROJECT_NAME --json '${item}' --features $FEATURES_PATH"
      commit_required: true

    # Step 2: Fix the drift in this chapter/subsection (subsection-aware command)
    - claude: "/prodigy-fix-subsection-drift --project $PROJECT_NAME --json '${item}'"
      commit_required: true
      validate:
        claude: "/prodigy-validate-doc-fix --project $PROJECT_NAME --json '${item}' --output .prodigy/validation-result.json"
        result_file: ".prodigy/validation-result.json"
        threshold: 100  # Documentation must meet 100% quality standards
        on_incomplete:
          claude: "/prodigy-complete-doc-fix --project $PROJECT_NAME --json '${item}' --gaps ${validation.gaps}"
          max_attempts: 3
          fail_workflow: false  # Continue even if we can't reach 100%
          commit_required: true  # Require commit to verify improvements were made

  max_parallel: ${MAX_PARALLEL}

# Reduce phase: Validate and handle any merge conflicts
reduce:
  # Rebuild the book to ensure all chapters compile together
  - shell: "cd book && mdbook build"
    on_failure:
      # Only needed if there are build errors (broken links, etc)
      claude: "/prodigy-fix-book-build-errors --project $PROJECT_NAME"
      commit_required: true

  # Holistic validation - detect cross-cutting issues map phase can't see
  - claude: "/prodigy-validate-book-holistically --project $PROJECT_NAME --book-dir $BOOK_DIR --output $ANALYSIS_DIR/validation.json --auto-fix true"
    commit_required: true

  # Clean up temporary analysis files (keep validation report for review)
  - shell: "rm -rf ${ANALYSIS_DIR}/features.json ${ANALYSIS_DIR}/flattened-items.json ${ANALYSIS_DIR}/drift-*.json"
  - shell: "git add -A && git commit -m 'chore: remove temporary book analysis files for ${PROJECT_NAME}' || true"
 

# Error handling
error_policy:
  on_item_failure: dlq
  continue_on_failure: true
  max_failures: 2
  error_collection: aggregate
