@leeovery/claude-technical-workflows 2.1.33 → 2.1.35

package/skills/migrate/scripts/migrations/005-plan-external-deps-frontmatter.sh

@@ -30,8 +30,6 @@
 #   - "- ~~{topic}: {description}~~ → satisfied externally" → state: satisfied_externally
 #
 # This script is sourced by migrate.sh and has access to:
-#   - is_migrated "filepath" "migration_id"
-#   - record_migration "filepath" "migration_id"
 #   - report_update "filepath" "description"
 #   - report_skip "filepath"
 #
@@ -122,15 +120,8 @@ for file in "$PLAN_DIR"/*.md; do
         *-review-*|*-tracking*) continue ;;
     esac
 
-    # Check if already migrated via tracking
-    if is_migrated "$file" "$MIGRATION_ID"; then
-        report_skip "$file"
-        continue
-    fi
-
     # Check if file has YAML frontmatter
     if ! head -1 "$file" 2>/dev/null | grep -q "^---$"; then
-        record_migration "$file" "$MIGRATION_ID"
         report_skip "$file"
         continue
     fi
@@ -138,7 +129,6 @@ for file in "$PLAN_DIR"/*.md; do
     # Check if external_dependencies already exists in frontmatter
     frontmatter=$(extract_frontmatter_005 "$file")
     if echo "$frontmatter" | grep -q "^external_dependencies:"; then
-        record_migration "$file" "$MIGRATION_ID"
         report_skip "$file"
         continue
     fi
@@ -226,8 +216,6 @@ ${new_deps_block}"
         echo "$new_body"
     } > "$file"
 
-    record_migration "$file" "$MIGRATION_ID"
-
     if $has_deps; then
         report_update "$file" "migrated external dependencies to frontmatter"
     else

package/skills/migrate/scripts/migrations/006-directory-restructure.sh

@@ -12,8 +12,6 @@
 # Updates plan frontmatter `specification` field to use new directory paths.
 #
 # This script is sourced by migrate.sh and has access to:
-#   - is_migrated "filepath" "migration_id"
-#   - record_migration "filepath" "migration_id"
 #   - report_update "filepath" "description"
 #   - report_skip "filepath"
 #
@@ -33,19 +31,11 @@ if [ -d "$SPEC_DIR" ]; then
 
         # Skip if already a directory (already migrated)
         if [ -d "$SPEC_DIR/$name" ] && [ -f "$SPEC_DIR/$name/specification.md" ]; then
-            new_path="$SPEC_DIR/$name/specification.md"
-            if ! is_migrated "$new_path" "$MIGRATION_ID"; then
-                record_migration "$new_path" "$MIGRATION_ID"
-            fi
-            report_skip "$new_path"
+            report_skip "$SPEC_DIR/$name/specification.md"
             continue
         fi
 
         new_path="$SPEC_DIR/$name/specification.md"
-        if is_migrated "$new_path" "$MIGRATION_ID"; then
-            report_skip "$new_path"
-            continue
-        fi
 
         # Create topic directory
         mkdir -p "$SPEC_DIR/$name"
@@ -63,7 +53,6 @@ if [ -d "$SPEC_DIR" ]; then
             report_update "$SPEC_DIR/$name/$new_tracking_name" "moved tracking file into topic directory"
         done
 
-        record_migration "$new_path" "$MIGRATION_ID"
         report_update "$new_path" "restructured to topic directory"
     done
 fi
@@ -79,19 +68,11 @@ if [ -d "$PLAN_DIR" ]; then
 
         # Skip if already a directory with plan.md
         if [ -d "$PLAN_DIR/$name" ] && [ -f "$PLAN_DIR/$name/plan.md" ]; then
-            new_path="$PLAN_DIR/$name/plan.md"
-            if ! is_migrated "$new_path" "$MIGRATION_ID"; then
-                record_migration "$new_path" "$MIGRATION_ID"
-            fi
-            report_skip "$new_path"
+            report_skip "$PLAN_DIR/$name/plan.md"
             continue
         fi
 
         new_path="$PLAN_DIR/$name/plan.md"
-        if is_migrated "$new_path" "$MIGRATION_ID"; then
-            report_skip "$new_path"
-            continue
-        fi
 
         # Create topic directory (may already exist for local-markdown tasks)
         mkdir -p "$PLAN_DIR/$name"
@@ -108,7 +89,6 @@ if [ -d "$PLAN_DIR" ]; then
             report_update "$PLAN_DIR/$name/$new_tracking_name" "moved tracking file into topic directory"
         done
 
-        record_migration "$new_path" "$MIGRATION_ID"
         report_update "$new_path" "restructured to topic directory"
     done
 fi

package/skills/migrate/scripts/migrations/007-tasks-subdirectory.sh

@@ -24,8 +24,6 @@
 # Idempotent: skips if tasks/ already exists and contains .md files.
 #
 # This script is sourced by migrate.sh and has access to:
-#   - is_migrated "filepath" "migration_id"
-#   - record_migration "filepath" "migration_id"
 #   - report_update "filepath" "description"
 #   - report_skip "filepath"
 #
@@ -44,12 +42,6 @@ for topic_dir in "$PLAN_DIR"/*/; do
     topic=$(basename "$topic_dir")
     marker="${topic_dir}plan.md"
 
-    # Use plan.md as the migration tracking key
-    if is_migrated "$marker" "$MIGRATION_ID"; then
-        report_skip "$marker"
-        continue
-    fi
-
     # Skip if no plan.md exists (not a valid topic directory)
     if [ ! -f "$marker" ]; then
         continue
@@ -59,14 +51,7 @@ for topic_dir in "$PLAN_DIR"/*/; do
     task_files=("$topic_dir${topic}-"*.md)
     if [ ! -f "${task_files[0]}" ]; then
         # No task files — format may not be local-markdown, or tasks already moved
-        # Check if tasks/ already has files (idempotent check)
-        if [ -d "${topic_dir}tasks" ] && ls -1 "${topic_dir}tasks/"*.md >/dev/null 2>&1; then
-            record_migration "$marker" "$MIGRATION_ID"
-            report_skip "$marker"
-        else
-            record_migration "$marker" "$MIGRATION_ID"
-            report_skip "$marker"
-        fi
+        report_skip "$marker"
         continue
     fi
 
@@ -81,6 +66,5 @@ for topic_dir in "$PLAN_DIR"/*/; do
         moved=$((moved + 1))
     done
 
-    record_migration "$marker" "$MIGRATION_ID"
     report_update "$marker" "moved $moved task file(s) to tasks/ subdirectory"
 done

package/skills/migrate/scripts/migrations/008-review-directory-structure.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+#
+# 008-review-directory-structure.sh
+#
+# Moves existing flat review files into a versioned r1/ directory structure.
+#
+# Previous layout:
+#   review/
+#   ├── tick-core.md                     # Summary at root
+#   ├── tick-core/                       # QA files + product assessment
+#   │   ├── qa-task-1.md
+#   │   └── product-assessment.md
+#   ├── doctor-installation-migration.md # Multi-plan summary
+#   ├── installation/                    # Per-plan QA (ambiguous)
+#   │   └── qa-task-1.md
+#
+# New layout:
+#   review/
+#   ├── tick-core/
+#   │   └── r1/
+#   │       ├── review.md
+#   │       ├── qa-task-1.md
+#   │       └── product-assessment.md
+#   ├── doctor-installation-migration/
+#   │   └── r1/
+#   │       ├── review.md
+#   │       ├── product-assessment.md
+#   │       └── installation/
+#   │           └── qa-task-1.md
+#
+# Idempotent: skips if r1/ already exists.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="008"
+REVIEW_DIR="docs/workflow/review"
+
+# Skip if no review directory
+if [ ! -d "$REVIEW_DIR" ]; then
+    return 0
+fi
+
+for review_file in "$REVIEW_DIR"/*.md; do
+    [ -f "$review_file" ] || continue
+
+    scope=$(basename "$review_file" .md)
+    scope_dir="$REVIEW_DIR/$scope"
+    r1_dir="$scope_dir/r1"
+
+    # Skip if r1/ already exists (idempotent)
+    if [ -d "$r1_dir" ]; then
+        report_skip "$review_file"
+        continue
+    fi
+
+    # Create r1/ directory
+    mkdir -p "$r1_dir"
+
+    # Move the summary file to r1/review.md
+    mv "$review_file" "$r1_dir/review.md"
+    moved=1
+
+    # If a matching directory exists, move its contents into r1/
+    if [ -d "$scope_dir" ]; then
+        # Move qa-task-*.md files
+        for qa_file in "$scope_dir"/qa-task-*.md; do
+            [ -f "$qa_file" ] || continue
+            mv "$qa_file" "$r1_dir/"
+            moved=$((moved + 1))
+        done
+
+        # Move product-assessment.md
+        if [ -f "$scope_dir/product-assessment.md" ]; then
+            mv "$scope_dir/product-assessment.md" "$r1_dir/"
+            moved=$((moved + 1))
+        fi
+
+        # Move per-plan QA subdirectories (multi-plan reviews)
+        for subdir in "$scope_dir"/*/; do
+            [ -d "$subdir" ] || continue
+            subdir_name=$(basename "$subdir")
+            # Skip the r1 directory we just created
+            [ "$subdir_name" = "r1" ] && continue
+            # Only move directories that contain qa-task files
+            if ls -1 "$subdir"/qa-task-*.md >/dev/null 2>&1; then
+                mv "$subdir" "$r1_dir/"
+                moved=$((moved + 1))
+            fi
+        done
+    fi
+
+    report_update "$r1_dir/review.md" "migrated to r1/ structure ($moved items)"
+done

package/skills/migrate/scripts/migrations/009-review-per-plan-storage.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# 009-review-per-plan-storage.sh
+#
+# Restructures review directories to per-plan storage.
+#
+# Handles three patterns:
+#
+# 1. Product assessment files inside review versions — deleted (feature removed)
+#
+# 2. Multi-plan review with per-plan QA subdirectories:
+#    review/{scope}/r{N}/{plan}/qa-task-*.md → review/{plan}/r{N}/qa-task-*.md
+#
+# 3. Orphaned per-plan directories at review root (no r{N}/ structure):
+#    review/{topic}/qa-task-*.md → review/{topic}/r1/qa-task-*.md
+#
+# Idempotent: skips directories that already have proper r{N}/ structure.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="009"
+REVIEW_DIR="docs/workflow/review"
+
+# Skip if no review directory
+if [ ! -d "$REVIEW_DIR" ]; then
+    return 0
+fi
+
+#
+# Phase 1: Delete product-assessment.md files (feature removed)
+#
+for rdir in "$REVIEW_DIR"/*/r*/; do
+    [ -d "$rdir" ] || continue
+    pa_file="${rdir}product-assessment.md"
+    [ -f "$pa_file" ] || continue
+    rm "$pa_file"
+    report_update "$pa_file" "removed product assessment (feature removed)"
+done
+
+#
+# Phase 2: Move per-plan QA subdirectories from multi-plan reviews
+#
+# Detect multi-plan reviews: r{N}/ directories that contain subdirectories
+# with qa-task-*.md files (not just qa-task files at the r{N} level)
+#
+for scope_dir in "$REVIEW_DIR"/*/; do
+    [ -d "$scope_dir" ] || continue
+    scope=$(basename "$scope_dir")
+
+    for rdir in "$scope_dir"r*/; do
+        [ -d "$rdir" ] || continue
+        rnum=${rdir##*r}
+        rnum=${rnum%/}
+
+        # Look for per-plan subdirectories containing qa-task files
+        for plan_subdir in "$rdir"*/; do
+            [ -d "$plan_subdir" ] || continue
+            plan_name=$(basename "$plan_subdir")
+
+            # Only process directories that have qa-task files
+            ls -1 "$plan_subdir"/qa-task-*.md >/dev/null 2>&1 || continue
+
+            # Create destination: review/{plan}/r{N}/
+            dest_dir="$REVIEW_DIR/$plan_name/r${rnum}"
+            mkdir -p "$dest_dir"
+
+            # Move QA files
+            moved=0
+            for qa_file in "$plan_subdir"/qa-task-*.md; do
+                [ -f "$qa_file" ] || continue
+                mv "$qa_file" "$dest_dir/"
+                moved=$((moved + 1))
+            done
+
+            # Remove empty source directory
+            rmdir "$plan_subdir" 2>/dev/null || true
+
+            if [ "$moved" -gt 0 ]; then
+                report_update "$dest_dir" "moved $moved QA files from multi-plan review $scope/r${rnum}"
+            fi
+        done
+    done
+done
+
+#
+# Phase 3: Fix orphaned per-plan directories (QA files at root, no r{N}/)
+#
+# Pattern: review/{topic}/qa-task-*.md (no r1/ directory)
+#
+for topic_dir in "$REVIEW_DIR"/*/; do
+    [ -d "$topic_dir" ] || continue
+    topic=$(basename "$topic_dir")
+
+    # Skip if r1/ already exists with content
+    if [ -d "${topic_dir}r1" ]; then
+        continue
+    fi
+
+    # Check for QA files directly in the topic directory
+    ls -1 "$topic_dir"/qa-task-*.md >/dev/null 2>&1 || continue
+
+    # Create r1/ and move QA files
+    mkdir -p "${topic_dir}r1"
+    moved=0
+    for qa_file in "${topic_dir}"qa-task-*.md; do
+        [ -f "$qa_file" ] || continue
+        mv "$qa_file" "${topic_dir}r1/"
+        moved=$((moved + 1))
+    done
+
+    if [ "$moved" -gt 0 ]; then
+        report_update "${topic_dir}r1" "moved $moved orphaned QA files into r1/"
+    fi
+done

package/skills/migrate/scripts/migrations/010-gitignore-sessions.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# 010-cache-state-restructure.sh
+#
+# Restructures docs/workflow/.cache/ → .state/ + .cache/:
+#   - .state/ = committed persistent workflow state (analysis files)
+#   - .cache/ = gitignored ephemeral runtime data (sessions)
+#
+# Steps:
+#   1. Move analysis files from .cache/ → .state/ (if they exist)
+#   2. Clean up orphaned .cache/migrations / .cache/migrations.log
+#   3. Add docs/workflow/.cache/ to .gitignore
+#   4. Remove old docs/workflow/.cache/sessions/ entry from .gitignore
+#
+# Idempotent: safe to run multiple times.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+
+STATE_DIR="docs/workflow/.state"
+CACHE_DIR="docs/workflow/.cache"
+GITIGNORE=".gitignore"
+NEW_ENTRY="docs/workflow/.cache/"
+OLD_ENTRY="docs/workflow/.cache/sessions/"
+
+# --- Step 1: Move analysis files from .cache/ to .state/ ---
+
+ANALYSIS_FILES=(
+    "discussion-consolidation-analysis.md"
+    "research-analysis.md"
+)
+
+for file in "${ANALYSIS_FILES[@]}"; do
+    if [ -f "$CACHE_DIR/$file" ]; then
+        mkdir -p "$STATE_DIR"
+        mv "$CACHE_DIR/$file" "$STATE_DIR/$file"
+        report_update "$STATE_DIR/$file" "moved from .cache/"
+    fi
+done
+
+# --- Step 2: Clean up orphaned migration tracking in .cache/ ---
+
+for old_file in "$CACHE_DIR/migrations" "$CACHE_DIR/migrations.log"; do
+    if [ -f "$old_file" ]; then
+        rm "$old_file"
+        report_update "$old_file" "removed orphaned tracking file"
+    fi
+done
+
+# --- Step 3: Add docs/workflow/.cache/ to .gitignore ---
+
+if [ -f "$GITIGNORE" ] && grep -qxF "$NEW_ENTRY" "$GITIGNORE"; then
+    report_skip "$GITIGNORE"
+else
+    echo "$NEW_ENTRY" >> "$GITIGNORE"
+    report_update "$GITIGNORE" "added .cache/ to gitignore"
+fi
+
+# --- Step 4: Remove old sessions/ entry from .gitignore (now redundant) ---
+
+if [ -f "$GITIGNORE" ] && grep -qF "$OLD_ENTRY" "$GITIGNORE"; then
+    # Remove the old entry (and its comment if present)
+    grep -vF "$OLD_ENTRY" "$GITIGNORE" > "${GITIGNORE}.tmp"
+    mv "${GITIGNORE}.tmp" "$GITIGNORE"
+    report_update "$GITIGNORE" "removed redundant sessions/ entry"
+fi

package/skills/start-discussion/SKILL.md

@@ -2,7 +2,7 @@
 name: start-discussion
 description: "Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p docs/workflow/.state), Bash(rm docs/workflow/.state/research-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
 hooks:
   PreToolUse:
     - hooks:

package/skills/start-discussion/references/handle-selection.md

@@ -56,7 +56,7 @@ Refreshing analysis...
 
 Delete the cache file:
 ```bash
-rm docs/workflow/.cache/research-analysis.md
+rm docs/workflow/.state/research-analysis.md
 ```
 
 → Return to **Step 3** to re-analyze.

package/skills/start-discussion/references/research-analysis.md

@@ -14,7 +14,7 @@ Use `cache.status` from discovery to determine the approach:
 Using cached research analysis (unchanged since {cache.generated})
 ```
 
-Load the topics from `docs/workflow/.cache/research-analysis.md` and proceed.
+Load the topics from `docs/workflow/.state/research-analysis.md` and proceed.
 
 #### If cache.status is "stale" or "none"
 
@@ -40,10 +40,10 @@ Read each research file and extract key themes and potential discussion topics.
 
 Ensure the cache directory exists:
 ```bash
-mkdir -p docs/workflow/.cache
+mkdir -p docs/workflow/.state
 ```
 
-Create/update `docs/workflow/.cache/research-analysis.md`:
+Create/update `docs/workflow/.state/research-analysis.md`:
 
 ```markdown
 ---

package/skills/start-discussion/scripts/discovery.sh

@@ -10,7 +10,7 @@ set -eo pipefail
 
 RESEARCH_DIR="docs/workflow/research"
 DISCUSSION_DIR="docs/workflow/discussion"
-CACHE_FILE="docs/workflow/.cache/research-analysis.md"
+CACHE_FILE="docs/workflow/.state/research-analysis.md"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>

package/skills/start-review/SKILL.md

@@ -77,10 +77,16 @@ Parse the discovery output to understand:
 - `files` - list of plans with: name, topic, status, date, format, specification, specification_exists, plan_id (if present)
 - `count` - total number of plans
 
+**From `reviews` section:**
+- `exists` - whether any reviews exist
+- `entries` - list of reviews with: scope, type, plans, versions, latest_version, latest_verdict, latest_path, has_synthesis
+
 **From `state` section:**
 - `scenario` - one of: `"no_plans"`, `"single_plan"`, `"multiple_plans"`
 - `implemented_count` - plans with implementation_status != "none"
 - `completed_count` - plans with implementation_status == "completed"
+- `reviewed_plan_count` - plans that have been reviewed
+- `all_reviewed` - whether all implemented plans have reviews
 
 **IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state - the script provides everything needed.
 
@@ -110,9 +116,50 @@ to build it.
 
 **STOP.** Do not proceed — terminal condition.
 
+#### If all_reviewed is true
+
+All implemented plans have been reviewed.
+
+> *Output the next fenced block as a code block:*
+
+```
+Review Overview
+
+All {N} implemented plans have been reviewed.
+
+1. {topic:(titlecase)}
+   └─ Review: r{N} ({verdict})
+   └─ Synthesis: @if(has_synthesis) completed @else pending @endif
+
+2. ...
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+All plans have been reviewed.
+
+- **`a`/`analysis`** — Synthesize findings from existing reviews into tasks
+- **`r`/`re-review`** — Re-review a plan (creates new review version)
+
+Select an option:
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If analysis
+
+→ Proceed to **Step 4** with scope set to "analysis".
+
+#### If re-review
+
+→ Proceed to **Step 3**, incrementing the review version for the selected plan.
+
 #### If scenario is "single_plan" or "multiple_plans"
 
-Plans exist.
+Plans exist (some may have reviews, some may not).
 
 → Proceed to **Step 3** to present options.
 
@@ -136,19 +183,4 @@ Load **[select-plans.md](references/select-plans.md)** and follow its instructio
 
 ## Step 5: Invoke the Skill
 
-Before invoking the processing skill, save a session bookmark.
-
-> *Output the next fenced block as a code block:*
-
-```
-Saving session state so Claude can pick up where it left off if the conversation is compacted.
-```
-
-```bash
-.claude/hooks/workflows/write-session-state.sh \
-  "{topic}" \
-  "skills/technical-review/SKILL.md" \
-  "docs/workflow/review/{topic}.md"
-```
-
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-review/references/display-plans.md

@@ -21,6 +21,7 @@ Review Overview
    └─ Plan: concluded ({format})
    └─ Implementation: {impl_status:[completed|in-progress]}
    └─ Spec: {spec:[exists|missing]}
+   └─ Review: @if(has_review) r{N} ({verdict}) @else (none) @endif
 
 2. ...
 ```
@@ -54,6 +55,10 @@ Key:
   Implementation status:
     completed   — all tasks implemented
     in-progress — implementation still ongoing
+
+  Review status:
+    r{N}        — review version number
+    (none)      — not yet reviewed
 ```
 
 **Then route based on what's reviewable:**
@@ -90,11 +95,14 @@ Scope: single
 
 ```
 · · · · · · · · · · · ·
-What scope would you like to review?
+What would you like to do?
 
 - **`s`/`single`** — Review one plan's implementation
-- **`m`/`multi`** — Review selected plans together (cross-cutting)
-- **`a`/`all`** — Review all implemented plans (full product)
+- **`m`/`multi`** — Review selected plans
+- **`a`/`all`** — Review all implemented plans
+@if(has_any_review) - **`analysis`** — Synthesize findings from existing reviews into tasks @endif
+
+Select an option:
 · · · · · · · · · · · ·
 ```
 

package/skills/start-review/references/invoke-skill.md

@@ -6,27 +6,55 @@
 
 After completing the steps above, this skill's purpose is fulfilled.
 
+## Save Session Bookmark
+
+> *Output the next fenced block as a code block:*
+
+```
+Saving session state so Claude can pick up where it left off if the conversation is compacted.
+```
+
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-review/SKILL.md" \
+  "docs/workflow/review/{scope}/r{N}/review.md"
+```
+
+---
+
+## Invoke the Skill
+
 Invoke the [technical-review](../../technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
-**Example handoff (single):**
+Each plan is reviewed independently. When multiple plans are selected, pass all plans in the handoff — the orchestrator will loop through them one at a time.
+
+**Example handoff:**
 ```
-Review session for: {topic}
-Review scope: single
-Plan: docs/workflow/planning/{topic}/plan.md
-Format: {format}
-Plan ID: {plan_id} (if applicable)
-Specification: {specification} (exists: {true|false})
+Review session
+Plans to review:
+  - topic: {topic-1}
+    plan: docs/workflow/planning/{topic-1}/plan.md
+    format: {format}
+    plan_id: {plan_id} (if applicable)
+    specification: {specification} (exists: {true|false})
+    review_version: r{N}
+  - topic: {topic-2}
+    plan: docs/workflow/planning/{topic-2}/plan.md
+    format: {format}
+    specification: {specification} (exists: {true|false})
+    review_version: r{N}
 
 Invoke the technical-review skill.
 ```
 
-**Example handoff (multi/all):**
+**Example handoff (analysis-only):**
 ```
-Review session for: {scope description}
-Review scope: {multi | all}
-Plans:
-  - docs/workflow/planning/{topic-1}/plan.md (format: {format}, spec: {spec})
-  - docs/workflow/planning/{topic-2}/plan.md (format: {format}, spec: {spec})
+Analysis session for: {topic}
+Review mode: analysis-only
+Review path: docs/workflow/review/{topic}/r{N}/
+Format: {format}
+Specification: {spec path}
 
 Invoke the technical-review skill.
 ```