/review-workflow-phases-1-4

PR/MR Review: Workflow Phases 1-4

Phases 1 through 4 of the review workflow: scope establishment, version validation, slop detection, code analysis, and review output.

> **See Also**: > [Main Command](../../pr-review.md) | > [Workflow Index](review-workflow.md) | > [Phases 5-6](review-workflow-phases-5-6.md) | > [Enforcement](review-workflow-enforcement.md) | > [Framework](review-framework.md) | > [Configuration](review-configuration.md)

**Platform Note**: Commands below show GitHub (`gh`) examples. Check session context for `git_platform:` and consult `Skill(leyline:git-platform)` for GitLab (`glab`) / Bitbucket equivalents.

Workflow

Phase 1: Scope Establishment (Sanctum)

1. **Discover Scope Artifacts**

   # Search in priority order:
   1. docs/plans/*-<branch-name>*.md
   2. plan.md or spec.md
   3. tasks.md with completed items
   4. PR description and commit history

2. **Check Existing Backlog for Context**

   # Check for existing backlog files to avoid duplicate issue creation
   ls docs/backlog/*.md 2>/dev/null
   # Key files to check:
   # - docs/backlog/queue.md - Active backlog items with worthiness scores
   # - docs/backlog/technical-debt.md - Known technical debt items

If these files exist:

• Cross-reference out-of-scope items against existing entries
• Avoid creating duplicate GitHub issues for items already tracked
• Link new issues to related existing items when appropriate

3. **Establish Requirements Baseline**

   This PR aims to: [extracted from artifacts]

   Requirements:
   1. [Requirement from plan]
   2. [Requirement from spec]
   3. [Requirement from tasks]

Phase 1.5: Version Validation (MANDATORY)

**CRITICAL: This phase is MANDATORY for all PR reviews unless explicitly bypassed.**

Before proceeding to code analysis, validate version consistency across all version-bearing files.

**Bypass Conditions (any of):**

• CLI flag: `--skip-version-check` provided
• GitHub label: PR has `skip-version-check` label
• PR description: Contains `[skip-version-check]` marker

**Validation Process:**

1. **Check if bypass requested**

   # Check CLI flag (handled by command parsing)
   SKIP_VERSION_CHECK=false

   # Check PR label
   if gh pr view $PR_NUMBER --json labels --jq '.labels[].name' | grep -q "skip-version-check"; then
     SKIP_VERSION_CHECK=true
     echo "⚠️ Version validation bypassed via GitHub label"
   fi

   # Check PR description
   if gh pr view $PR_NUMBER --json body --jq '.body' | grep -q "\[skip-version-check\]"; then
     SKIP_VERSION_CHECK=true
     echo "⚠️ Version validation bypassed via PR description marker"
   fi

2. **Detect version changes in PR diff**

   # Key version files to check
   VERSION_FILES=(
     ".claude-plugin/marketplace.json"
     "CHANGELOG.md"
     "CHANGELOG"
     "package.json"
     "pyproject.toml"
     "Cargo.toml"
     "setup.py"
     "VERSION"
   )

   VERSION_CHANGED=false
   for file in "${VERSION_FILES[@]}"; do
     if gh pr diff $PR_NUMBER --name-only | grep -qF "$file"; then
       # Check if version-related lines changed
       if gh pr diff $PR_NUMBER | grep -qE "^\+.*version|^\+.*## \["; then
         VERSION_CHANGED=true
         echo "Version change detected in $file"
         break
       fi
     fi
   done

   # If no version changed and not a release PR, skip validation
   if [[ "$VERSION_CHANGED" == "false" ]]; then
     echo "✅ Version validation: N/A (no version files changed)"
     # Skip to Phase 2
   fi

3. **Run detailed version validation**

If version files changed, invoke the version validation module:

   # Load module
   # See: plugins/sanctum/skills/pr-review/modules/version-validation.md

   # Project type detection
   PROJECT_TYPE=""
   if [[ -f ".claude-plugin/marketplace.json" ]]; then
     PROJECT_TYPE="claude-marketplace"
   elif [[ -f "pyproject.toml" ]]; then
     PROJECT_TYPE="python"
   elif [[ -f "package.json" ]]; then
     PROJECT_TYPE="node"
   elif [[ -f "Cargo.toml" ]]; then
     PROJECT_TYPE="rust"
   fi

   # Run validations based on project type

4. **For Claude Marketplace Projects**

   if [[ "$PROJECT_TYPE" == "claude-marketplace" ]]; then
     echo "### Version Validation: Claude Marketplace"

     # Get ecosystem version from pyproject.toml (source of truth)
     ECOSYSTEM_VERSION=$(grep -E '^version\s*=' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
     echo "Ecosystem version (pyproject.toml): $ECOSYSTEM_VERSION"

     # Check CHANGELOG has entry for new version
     if [[ -f "CHANGELOG.md" ]]; then
       if ! grep -q "\[$ECOSYSTEM_VERSION\]" CHANGELOG.md; then
         echo "[B-VERSION] CHANGELOG.md missing entry for version $ECOSYSTEM_VERSION"
         echo "  Fix: Add release entry to CHANGELOG.md"
       else
         echo "  ✓ CHANGELOG.md has entry for $ECOSYSTEM_VERSION"
       fi
     fi

     # Check pyproject.toml versions across all plugins
     PYPROJECT_MISMATCHES=()
     for pyproject in plugins/*/pyproject.toml; do
       PLUGIN_NAME=$(dirname "$pyproject" | xargs basename)
       PLUGIN_VERSION=$(grep -E '^version\s*=' "$pyproject" | head -1 | sed 's/.*"\(.*\)".*/\1/')

       if [[ "$PLUGIN_VERSION" != "$ECOSYSTEM_VERSION" ]]; then
         PYPROJECT_MISMATCHES+=("$PLUGIN_NAME: pyproject=$PLUGIN_VERSION, expected=$ECOSYSTEM_VERSION")
         echo "[B-VERSION] pyproject.toml version mismatch for $PLUGIN_NAME"
         echo "  Expected: $ECOSYSTEM_VERSION"
         echo "  Actual (plugins/$PLUGIN_NAME/pyproject.toml): $PLUGIN_VERSION"
         echo "  Fix: Update plugin pyproject.toml to match ecosystem version"
       fi
     done

     # Check plugin.json versions match pyproject.toml (BLOCKING)
     PLUGIN_JSON_MISMATCHES=()
     for plugin_json in plugins/*/.claude-plugin/plugin.json; do
       PLUGIN_NAME=$(dirname "$(dirname "$plugin_json")" | xargs basename)
       JSON_VERSION=$(jq -r