@leeovery/claude-technical-workflows 2.1.32 → 2.1.34

package/README.md

@@ -110,7 +110,7 @@ Each phase produces documents that feed the next. Here's the journey:
 
 **Implementation** — Executes plans via strict TDD. Tests first, then code, commit after each task. Per-task approval gates keep you in control, with auto-mode available when you trust the flow.
 
-**Review** — Validates the implementation against spec and plan. Catches drift, missing requirements, and quality issues. The spec is the source of truth here — earlier phases may contain rejected ideas that were intentionally filtered out. Produces structured feedback without fixing code directly.
+**Review** — Validates the implementation against spec and plan. Catches drift, missing requirements, and quality issues. Findings can be synthesized into remediation tasks that feed back into implementation, closing the review-implementation loop.
 
 ### Standalone Skills
 
@@ -231,8 +231,12 @@ docs/workflow/
 ├── implementation/                    # Phase 5 — directory per topic
 │   └── {topic}/
 │       └── tracking.md               #   Progress, gates, current task
-└── review/                            # Phase 6 — one file per review
-    └── {topic}.md
+└── review/                            # Phase 6 — versioned per review
+    └── {topic}/
+        └── r1/
+            ├── review.md              #   Review summary and verdict
+            ├── qa-task-1.md           #   Per-task QA verification
+            └── product-assessment.md  #   Holistic product assessment
 ```
 
 Research starts with `exploration.md` and splits into topic files as themes emerge. From specification onwards, each topic gets its own directory. Planning task storage varies by [output format](#output-formats) — the tree above shows local-markdown; Tick and Linear store tasks externally.
@@ -269,12 +273,15 @@ skills/
 
 agents/
 ├── review-task-verifier.md           # Verifies single task implementation for review
+├── review-findings-synthesizer.md   # Synthesizes review findings into remediation tasks
 ├── implementation-task-executor.md  # TDD executor for single plan tasks
 ├── implementation-task-reviewer.md  # Post-task review for spec conformance
 ├── planning-phase-designer.md       # Design phases from specification
 ├── planning-task-designer.md        # Break phases into task lists
 ├── planning-task-author.md          # Write full task detail
-└── planning-dependency-grapher.md   # Analyze task dependencies and priorities
+├── planning-dependency-grapher.md   # Analyze task dependencies and priorities
+├── planning-review-traceability.md  # Spec-to-plan traceability analysis
+└── planning-review-integrity.md     # Plan structural quality review
 
 tests/
 └── scripts/                         # Shell script tests for discovery and migrations
@@ -310,7 +317,7 @@ Sequential skills that expect files from previous phases and pass content to pro
 | [**/start-specification**](skills/start-specification/)                      | Start a specification session from existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
 | [**/start-planning**](skills/start-planning/)                                | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats. |
 | [**/start-implementation**](skills/start-implementation/)                    | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
-| [**/start-review**](skills/start-review/)                                    | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
+| [**/start-review**](skills/start-review/)                                    | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria. Findings can be synthesized into remediation tasks.                                                    |
 
 #### Utility Skills
 
@@ -354,6 +361,9 @@ Subagents that skills can spawn for parallel task execution.
 | [**planning-task-designer**](agents/planning-task-designer.md) | technical-planning | Breaks a single phase into a task list with edge cases. |
 | [**planning-task-author**](agents/planning-task-author.md) | technical-planning | Writes full detail for a single plan task. |
 | [**planning-dependency-grapher**](agents/planning-dependency-grapher.md) | technical-planning | Analyzes authored tasks to establish internal dependencies and priorities. |
+| [**planning-review-traceability**](agents/planning-review-traceability.md) | technical-planning | Spec-to-plan traceability analysis. |
+| [**planning-review-integrity**](agents/planning-review-integrity.md) | technical-planning | Plan structural quality review. |
+| [**review-findings-synthesizer**](agents/review-findings-synthesizer.md) | technical-review | Synthesizes review findings into normalized remediation tasks for plan integration. |
 
 ## Requirements
 

package/agents/implementation-analysis-task-writer.md

@@ -19,6 +19,7 @@ You receive via the orchestrator's prompt:
 4. **Plan format reading adapter path** — how to read tasks from the plan (for determining next phase number)
 5. **Plan format authoring adapter path** — how to create tasks in the plan
 6. **plan-index-schema.md** — Canonical plan index structure
+7. **Phase label** — the label for the new phase (e.g., "Analysis (Cycle 1)", "Review Remediation (Cycle 1)")
 
 ## Your Process
 
@@ -35,10 +36,10 @@ The Plan Index File (`docs/workflow/planning/{topic}/plan.md`) is the single sou
 
 Append at the end of the Plan Index File body, following the **Phase Entry** and **Task Table** templates from plan-index-schema:
 
-- Phase heading: `### Phase {N}: Analysis ({cycle description})`
+- Phase heading: `### Phase {N}: {phase_label}`
 - Phase `status`: `approved` (pre-approved by user in approval gate)
 - Phase `ext_id`: external identifier for the phase from the output format
-- Phase goal: `Address findings from implementation analysis cycle {N}.`
+- Phase goal: `Address findings from {phase_label}.`
 - Omit `approved_at` and acceptance criteria (analysis phases don't use them)
 - Task `Status`: `authored` (task files are fully written)
 - Task `Ext ID`: external identifier for the task from the output format

package/agents/review-findings-synthesizer.md

@@ -0,0 +1,112 @@
+---
+name: review-findings-synthesizer
+description: Synthesizes review findings into normalized tasks. Reads review files (QA verifications and product assessment), deduplicates, groups, normalizes using task template, and writes a staging file for orchestrator approval. Invoked by technical-review skill after review actions are initiated.
+tools: Read, Write, Glob, Grep
+model: opus
+---
+
+# Review Findings: Synthesizer
+
+You locate the review findings files using the provided paths, then read them, deduplicate and group findings, normalize into tasks, and write a staging file for user approval.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Review scope** — single or multi, with plan list
+2. **Review paths** — paths to `r{N}/` directories containing review summary, QA files, and product assessment
+3. **Specification path(s)** — the validated specification(s) for context
+4. **Cycle number** — which review remediation cycle this is
+
+## Your Process
+
+1. **Read review summary(ies)** — extract verdict, required changes, recommendations from each `review.md`
+2. **Read all QA files** — read every `qa-task-*.md` across all review paths. Extract BLOCKING ISSUES and significant NON-BLOCKING NOTES with their file:line references
+3. **Read product assessment(s)** — extract ROBUSTNESS, GAPS, and STRENGTHENING findings from `product-assessment.md`
+4. **Tag each finding with source plan** — use the directory structure of QA files to identify which plan each finding belongs to. For multi-plan reviews, QA files are stored in per-plan subdirectories within the review. Product assessment findings: tag by plan where identifiable; mark as `cross-cutting` otherwise
+5. **Deduplicate** — same issue found in QA + product assessment → one finding, note all sources
+6. **Group related findings** — multiple findings about the same concern become one task (e.g., 3 QA findings about missing error handling in the same module = 1 "add error handling" task)
+7. **Filter** — discard low-severity non-blocking findings unless they cluster into a pattern. Never discard high-severity or blocking findings.
+8. **Normalize** — convert each group into a task using the canonical task template (Problem / Solution / Outcome / Do / Acceptance Criteria / Tests)
+9. **Write report** — output to `docs/workflow/implementation/{primary-topic}/review-report-c{cycle}.md`
+10. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{primary-topic}/review-tasks-c{cycle}.md` with `status: pending` for each task
+
+## Report Format
+
+Write the report file with this structure:
+
+```markdown
+---
+scope: {scope description}
+cycle: {N}
+source: review
+total_findings: {N}
+deduplicated_findings: {N}
+proposed_tasks: {N}
+---
+# Review Report: {Scope} (Cycle {N})
+
+## Summary
+{2-3 sentence overview of findings}
+
+## Discarded Findings
+- {title} — {reason for discarding}
+```
+
+## Staging File Format
+
+Write the staging file with this structure:
+
+```markdown
+---
+scope: {scope description}
+cycle: {N}
+source: review
+total_proposed: {N}
+gate_mode: gated
+---
+# Review Tasks: {Scope} (Cycle {N})
+
+## Task 1: {title}
+status: pending
+severity: high
+plan: {plan-topic}
+sources: qa-task-3, product-assessment
+
+**Problem**: {what the review found}
+**Solution**: {what to fix}
+**Outcome**: {what success looks like}
+**Do**: {step-by-step implementation instructions}
+**Acceptance Criteria**:
+- {criterion}
+**Tests**:
+- {test description}
+
+## Task 2: {title}
+status: pending
+...
+```
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **No new features** — only address issues found in the review. Every proposed task must trace back to a specific review finding.
+2. **Never discard blocking** — blocking issues from QA always become proposed tasks.
+3. **Self-contained tasks** — every proposed task must be independently executable. No task should depend on another proposed task.
+4. **Faithful synthesis** — do not invent findings. Every proposed task must trace back to at least one QA finding or product assessment observation.
+5. **No git writes** — do not commit or stage. Writing the report and staging files are your only file writes.
+6. **Plan tagging** — every task must have a `plan:` field identifying which plan it belongs to. This is critical for multi-plan reviews where tasks are created in different plans.
+
+## Your Output
+
+Return a brief status to the orchestrator:
+
+```
+STATUS: tasks_proposed | clean
+TASKS_PROPOSED: {N}
+SUMMARY: {1-2 sentences}
+```
+
+- `tasks_proposed`: tasks written to staging file — orchestrator should present for approval
+- `clean`: no actionable findings — orchestrator should report clean result

package/agents/review-product-assessor.md

@@ -42,7 +42,7 @@ You receive via the orchestrator's prompt:
 3. **Read plan(s)** — understand what was built and the scope of each plan
 4. **Read all implementation files** — understand the full picture
 5. **Assess as a product** — evaluate holistically against focus areas
-6. **Write findings** to `docs/workflow/review/{topic-or-scope}/product-assessment.md`
+6. **Write findings** to `docs/workflow/review/{scope}/r{N}/product-assessment.md`
 
 For multi-plan/full-product scope, use a descriptive scope name (e.g., `full-product` or a hyphenated list of topic names).
 
@@ -59,7 +59,7 @@ For multi-plan/full-product scope, use a descriptive scope name (e.g., `full-pro
 
 ## Output File Format
 
-Write to `docs/workflow/review/{topic-or-scope}/product-assessment.md`:
+Write to `docs/workflow/review/{scope}/r{N}/product-assessment.md`:
 
 ```
 SCOPE: {single-plan | multi-plan | full-product}

package/agents/review-task-verifier.md

@@ -17,8 +17,10 @@ You receive:
 3. **Plan path**: The full plan for additional context
 4. **Project skill paths**: Relevant `.claude/skills/` paths for framework conventions
 5. **Review checklist path**: Path to the review checklist (`skills/technical-review/references/review-checklist.md`) — read this for detailed verification criteria
-6. **Topic name**: The plan topic (used for output file path)
-7. **Task index**: Sequential number for this task (used for output file naming)
+6. **Review scope**: Scope directory name for output path
+7. **Review number**: Version number (e.g., 1 for `r1/`)
+8. **Plan topic**: For multi-plan reviews, the plan-specific subdirectory name
+9. **Task index**: Sequential number for this task (used for output file naming)
 
 ## Your Task
 
@@ -86,7 +88,7 @@ Review the implementation as a senior architect would:
 
 ## Output File Format
 
-Write to `docs/workflow/review/{topic}/qa-task-{index}.md`:
+Write to `docs/workflow/review/{scope}/r{N}/qa-task-{index}.md`:
 
 ```
 TASK: [Task name/description]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.32",
+  "version": "2.1.34",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

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

@@ -0,0 +1,106 @@
+#!/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:
+#   - is_migrated "filepath" "migration_id"
+#   - record_migration "filepath" "migration_id"
+#   - 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"
+
+    # Use the review file as migration tracking key
+    if is_migrated "$review_file" "$MIGRATION_ID"; then
+        report_skip "$review_file"
+        continue
+    fi
+
+    # Skip if r1/ already exists (idempotent)
+    if [ -d "$r1_dir" ]; then
+        record_migration "$review_file" "$MIGRATION_ID"
+        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
+
+    record_migration "$r1_dir/review.md" "$MIGRATION_ID"
+    report_update "$r1_dir/review.md" "migrated to r1/ structure ($moved items)"
+done

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)
+@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,7 +6,26 @@
 
 After completing the steps above, this skill's purpose is fulfilled.
 
-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.
+## 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. Use the appropriate handoff format based on the gathered context (review or analysis-only).
 
 **Example handoff (single):**
 ```
@@ -30,3 +49,18 @@ Plans:
 
 Invoke the technical-review skill.
 ```
+
+**Example handoff (analysis-only):**
+```
+Analysis session for: {scope description}
+Review mode: analysis-only
+Review scope: {single | multi | all}
+Reviews:
+  - scope: {scope}
+    path: docs/workflow/review/{scope}/r{N}/
+    plans: [{plan topics}]
+    format: {format}
+    specification: {spec path}
+
+Invoke the technical-review skill.
+```

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

@@ -4,7 +4,36 @@
 
 ---
 
-This step only applies for `single` or `multi` scope chosen in Step 3.
+This step only applies for `single`, `multi`, or `all` scope chosen in Step 3.
+
+#### If scope is "analysis"
+
+Select which reviews to analyze.
+
+#### If multiple reviews exist
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Which reviews to analyze?
+
+- **`a`/`all`** — All reviewed plans
+- **`s`/`select`** — Choose specific reviews
+
+Select an option:
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+If `select`, present numbered list of reviewed plans for the user to choose from (comma-separated numbers).
+
+#### If single review exists
+
+Automatically proceed with the only available review.
+
+→ Proceed to **Step 5**.
 
 #### If scope is "all"
 

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

@@ -9,6 +9,8 @@ set -eo pipefail
 
 PLAN_DIR="docs/workflow/planning"
 SPEC_DIR="docs/workflow/specification"
+REVIEW_DIR="docs/workflow/review"
+IMPL_DIR="docs/workflow/implementation"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>
@@ -113,6 +115,134 @@ fi
 
 echo ""
 
+#
+# REVIEWS
+#
+echo "reviews:"
+
+reviewed_plan_count=0
+# Track which plan names have been reviewed (space-separated)
+reviewed_plans=""
+
+if [ -d "$REVIEW_DIR" ]; then
+    # Check for any review directories with r*/review.md
+    has_reviews="false"
+    for scope_dir in "$REVIEW_DIR"/*/; do
+        [ -d "$scope_dir" ] || continue
+        if ls -d "$scope_dir"r*/review.md >/dev/null 2>&1; then
+            has_reviews="true"
+            break
+        fi
+    done
+
+    echo "  exists: $has_reviews"
+
+    if [ "$has_reviews" = "true" ]; then
+        echo "  entries:"
+
+        for scope_dir in "$REVIEW_DIR"/*/; do
+            [ -d "$scope_dir" ] || continue
+            scope=$(basename "$scope_dir")
+
+            # Count r*/ versions
+            versions=0
+            latest_version=0
+            latest_path=""
+            for rdir in "$scope_dir"r*/; do
+                [ -d "$rdir" ] || continue
+                [ -f "${rdir}review.md" ] || continue
+                rnum=${rdir##*r}
+                rnum=${rnum%/}
+                versions=$((versions + 1))
+                if [ "$rnum" -gt "$latest_version" ] 2>/dev/null; then
+                    latest_version=$rnum
+                    latest_path="$rdir"
+                fi
+            done
+
+            [ "$versions" -eq 0 ] && continue
+
+            # Extract verdict from latest review.md
+            latest_verdict=""
+            if [ -f "${latest_path}review.md" ]; then
+                latest_verdict=$(grep -m1 '\*\*QA Verdict\*\*:' "${latest_path}review.md" 2>/dev/null | \
+                    sed -E 's/.*\*\*QA Verdict\*\*:[[:space:]]*//' || true)
+            fi
+
+            # Determine type (single/multi) from Scope line
+            review_type="single"
+            review_plans=""
+            if [ -f "${latest_path}review.md" ]; then
+                scope_line=$(grep -m1 '\*\*Scope\*\*:' "${latest_path}review.md" 2>/dev/null || true)
+                if echo "$scope_line" | grep -qi "multi-plan\|multi plan"; then
+                    review_type="multi"
+                    # Extract plan names from parentheses: Multi-Plan (plan1, plan2, plan3)
+                    review_plans=$(echo "$scope_line" | sed -E 's/.*\(([^)]+)\).*/\1/' | tr ',' '\n' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
+                elif echo "$scope_line" | grep -qi "full product"; then
+                    review_type="multi"
+                fi
+            fi
+
+            # For single-plan reviews, plan name is the scope
+            if [ "$review_type" = "single" ]; then
+                review_plans="$scope"
+            fi
+
+            # Check for synthesis: look for review-tasks-c*.md in implementation dirs
+            has_synthesis="false"
+            if [ "$review_type" = "single" ]; then
+                if ls "$IMPL_DIR/$scope"/review-tasks-c*.md >/dev/null 2>&1; then
+                    has_synthesis="true"
+                fi
+            else
+                # For multi-plan, check each plan's implementation dir
+                for plan_name in $review_plans; do
+                    plan_name=$(echo "$plan_name" | tr -d '[:space:]')
+                    if ls "$IMPL_DIR/$plan_name"/review-tasks-c*.md >/dev/null 2>&1; then
+                        has_synthesis="true"
+                        break
+                    fi
+                done
+            fi
+
+            # Track reviewed plans
+            for plan_name in $review_plans; do
+                plan_name=$(echo "$plan_name" | tr -d '[:space:]')
+                if ! echo " $reviewed_plans " | grep -q " $plan_name "; then
+                    reviewed_plans="$reviewed_plans $plan_name"
+                    reviewed_plan_count=$((reviewed_plan_count + 1))
+                fi
+            done
+
+            echo "    - scope: \"$scope\""
+            echo "      type: \"$review_type\""
+            # Format plans as YAML array
+            printf "      plans: ["
+            first="true"
+            for plan_name in $review_plans; do
+                plan_name=$(echo "$plan_name" | tr -d '[:space:]')
+                [ -z "$plan_name" ] && continue
+                if [ "$first" = "true" ]; then
+                    printf "\"%s\"" "$plan_name"
+                    first="false"
+                else
+                    printf ", \"%s\"" "$plan_name"
+                fi
+            done
+            echo "]"
+            echo "      versions: $versions"
+            echo "      latest_version: $latest_version"
+            echo "      latest_verdict: \"$latest_verdict\""
+            echo "      latest_path: \"$latest_path\""
+            echo "      has_synthesis: $has_synthesis"
+        done
+    fi
+else
+    echo "  exists: false"
+fi
+
+echo ""
+
 #
 # WORKFLOW STATE SUMMARY
 #
@@ -122,6 +252,14 @@ echo "  has_plans: $([ "$plan_count" -gt 0 ] && echo "true" || echo "false")"
 echo "  plan_count: $plan_count"
 echo "  implemented_count: $implemented_count"
 echo "  completed_count: $completed_count"
+echo "  reviewed_plan_count: $reviewed_plan_count"
+
+# Determine if all implemented plans have been reviewed
+all_reviewed="false"
+if [ "$implemented_count" -gt 0 ] && [ "$reviewed_plan_count" -ge "$implemented_count" ]; then
+    all_reviewed="true"
+fi
+echo "  all_reviewed: $all_reviewed"
 
 # Determine workflow state for routing
 if [ "$plan_count" -eq 0 ]; then

package/skills/technical-implementation/references/invoke-task-writer.md

@@ -20,6 +20,7 @@ Pass via the orchestrator's prompt:
 4. **Plan format reading adapter path** — `../../technical-planning/references/output-formats/{format}/reading.md`
 5. **Plan format authoring adapter path** — `../../technical-planning/references/output-formats/{format}/authoring.md`
 6. **plan-index-schema.md** — `../../technical-planning/references/plan-index-schema.md`
+7. **Phase label** — `Analysis (Cycle {N})`
 
 ---
 

package/skills/technical-planning/references/output-formats/tick/authoring.md

@@ -1,15 +1,22 @@
 # Tick: Authoring
 
-## Sandbox Mode and Large Descriptions
+## Descriptions: Inline Only
 
-Bash heredocs (`$(cat <<'EOF'...EOF)`) create temp files that sandbox mode blocks, resulting in empty descriptions being set silently. Do **not** use `dangerouslyDisableSandbox` — it forces user approval on every call.
+**CRITICAL**: Always pass descriptions directly as inline quoted strings. Never use workarounds.
 
-Instead, use the **Write tool + cat pattern**:
+```bash
+tick create "Title" --parent <id> --description "Full description here.
+
+Multi-line content works fine inside double quotes."
+```
 
-1. Use the **Write tool** to save the description to `$TMPDIR/tick-desc.txt` — this bypasses sandbox because it uses Claude Code's file writing, not bash
-2. Run the tick command with `--description "$(cat $TMPDIR/tick-desc.txt)"` in normal sandbox mode — `cat` just reads, no temp files needed
+**Do NOT**:
+- Use heredocs (`<<'EOF'`) — sandbox blocks the temp files they create
+- Use the Write tool to create temp files — triggers approval prompts outside the project directory
+- Use Bash functions, variables, or subshells to construct the description
+- Write temp files anywhere (including `$TMPDIR`, `/tmp`, or the working directory)
 
-This works for both `tick create --description` and `tick update --description`.
+If a description contains double quotes, escape them with `\"`. That's it.
 
 ## Task Storage
 

package/skills/technical-review/SKILL.md

@@ -49,6 +49,12 @@ having it provides better context for the review.
 
 The specification is optional — the review can proceed with just the plan.
 
+#### If review mode is "analysis-only"
+
+Analysis of existing review findings was requested. The review has already been completed.
+
+→ Go directly to **Step 6**.
+
 ---
 
 ## Resuming After Context Refresh
@@ -135,33 +141,13 @@ Load **[invoke-product-assessor.md](references/invoke-product-assessor.md)** and
 
 ## Step 5: Produce Review
 
-Aggregate findings from both stages into a review document using the **[template.md](references/template.md)**.
-
-Write the review to `docs/workflow/review/{topic}.md` (single) or `docs/workflow/review/{scope-description}.md` (multi/all).
-
-**QA Verdict** (from Step 3):
-- **Approve** — All acceptance criteria met, no blocking issues
-- **Request Changes** — Missing requirements, broken functionality, inadequate tests
-- **Comments Only** — Minor suggestions, non-blocking observations
+Load **[produce-review.md](references/produce-review.md)** and follow its instructions as written.
 
-**Product Assessment** (from Step 4) — always advisory, presented alongside the verdict.
-
-Commit: `review({topic}): complete review`
-
-Present the review to the user.
-
-Your review feedback can be:
-- Addressed by implementation (same or new session)
-- Delegated to an agent for fixes
-- Overridden by user ("ship it anyway")
-
-You produce feedback. User decides what to do with it.
+→ Proceed to **Step 6**.
 
 ---
 
-## References
+## Step 6: Review Actions
+
+Load **[review-actions-loop.md](references/review-actions-loop.md)** and follow its instructions.
 
-- **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** — How to dispatch QA verifier agents
-- **[invoke-product-assessor.md](references/invoke-product-assessor.md)** — How to dispatch the product assessor agent
-- **[template.md](references/template.md)** — Review output structure and verdict guidelines
-- **[review-checklist.md](references/review-checklist.md)** — Per-task verification criteria (read by agents), plan completion checks, writing feedback guidance

package/skills/technical-review/references/invoke-product-assessor.md

@@ -40,7 +40,7 @@ The assessor receives:
 
 **STOP.** Do not proceed until the assessor has returned.
 
-The assessor writes its findings to `docs/workflow/review/{topic-or-scope}/product-assessment.md` and returns a brief status. If the agent fails (error, timeout), record the failure and continue to the review production step with QA findings only.
+The assessor writes its findings to `docs/workflow/review/{scope}/r{N}/product-assessment.md` and returns a brief status. If the agent fails (error, timeout), record the failure and continue to the review production step with QA findings only.
 
 ---
 
@@ -54,4 +54,4 @@ FINDINGS_COUNT: {N}
 SUMMARY: {1 sentence}
 ```
 
-The full findings are in the output file. Read `docs/workflow/review/{topic-or-scope}/product-assessment.md` to incorporate into the review document.
+The full findings are in the output file. Read `docs/workflow/review/{scope}/r{N}/product-assessment.md` to incorporate into the review document.

package/skills/technical-review/references/invoke-review-synthesizer.md

@@ -0,0 +1,64 @@
+# Invoke Review Synthesizer
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+This step dispatches a `review-findings-synthesizer` agent to read review findings, deduplicate, group, and normalize them into proposed tasks.
+
+---
+
+## Determine Cycle Number
+
+Count existing `review-tasks-c*.md` files in `docs/workflow/implementation/{primary-topic}/` and add 1.
+
+```bash
+ls docs/workflow/implementation/{primary-topic}/review-tasks-c*.md 2>/dev/null | wc -l
+```
+
+---
+
+## Invoke the Agent
+
+**Agent path**: `../../../agents/review-findings-synthesizer.md`
+
+Dispatch **one agent** via the Task tool.
+
+The synthesizer receives:
+
+1. **Review scope** — single or multi, with plan list
+2. **Review paths** — paths to `r{N}/` directories (include summary, QA directory, product assessment)
+3. **Specification path(s)** — from each plan's frontmatter
+4. **Cycle number** — the review remediation cycle number
+
+---
+
+## Wait for Completion
+
+**STOP.** Do not proceed until the synthesizer has returned.
+
+If the agent fails (error, timeout), record the failure and report "synthesis failed" to the user.
+
+---
+
+## Commit Findings
+
+Commit the report and staging file (if created):
+
+```
+review({scope}): synthesis cycle {N} — findings
+```
+
+---
+
+## Expected Result
+
+The synthesizer returns:
+
+```
+STATUS: tasks_proposed | clean
+TASKS_PROPOSED: {N}
+SUMMARY: {1-2 sentences}
+```
+
+The full report is at `docs/workflow/implementation/{primary-topic}/review-report-c{N}.md`. If tasks were proposed, the staging file is at `docs/workflow/implementation/{primary-topic}/review-tasks-c{N}.md`.

package/skills/technical-review/references/invoke-review-task-writer.md

@@ -0,0 +1,44 @@
+# Invoke Review Task Writer
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+This step invokes the task writer agent to create plan tasks from approved review findings. It reuses the `implementation-analysis-task-writer` agent with a review-specific phase label.
+
+---
+
+## Determine Format
+
+Read the `format` field from the plan's frontmatter (`docs/workflow/planning/{topic}/plan.md`). This determines which output format adapters to pass to the agent.
+
+---
+
+## Invoke the Agent
+
+**Agent path**: `../../../agents/implementation-analysis-task-writer.md`
+
+Pass via the orchestrator's prompt:
+
+1. **Topic name** — the implementation topic (scopes tasks to correct plan)
+2. **Staging file path** — `docs/workflow/implementation/{topic}/review-tasks-c{cycle-number}.md`
+3. **Plan path** — the implementation plan path
+4. **Plan format reading adapter path** — `../../technical-planning/references/output-formats/{format}/reading.md`
+5. **Plan format authoring adapter path** — `../../technical-planning/references/output-formats/{format}/authoring.md`
+6. **plan-index-schema.md** — `../../technical-planning/references/plan-index-schema.md`
+7. **Phase label** — `Review Remediation (Cycle {N})`
+
+---
+
+## Expected Result
+
+The agent creates tasks in the plan for all approved entries in the staging file.
+
+Returns a brief status:
+
+```
+STATUS: complete
+TASKS_CREATED: {N}
+PHASE: {N}
+SUMMARY: {1 sentence}
+```

package/skills/technical-review/references/invoke-task-verifiers.md

@@ -32,10 +32,16 @@ From each plan in scope, list every task across all phases:
 
 ## Create Output Directory
 
-For each topic in scope, ensure the review output directory exists:
+Ensure the review output directory exists:
 
 ```bash
-mkdir -p docs/workflow/review/{topic}
+mkdir -p docs/workflow/review/{scope}/r{N}
+```
+
+For multi-plan reviews, also create per-plan subdirectories:
+
+```bash
+mkdir -p docs/workflow/review/{scope}/r{N}/{plan-topic}
 ```
 
 ---
@@ -60,8 +66,10 @@ Each verifier receives:
 3. **Plan path** — the full plan for phase context
 4. **Project skill paths** — from Step 2 discovery
 5. **Review checklist path** — `skills/technical-review/references/review-checklist.md`
-6. **Topic name** — for output file path
-7. **Task index** — sequential number for file naming (1, 2, 3...)
+6. **Review scope** — scope directory name for output path
+7. **Review number** — version number (e.g., 1 for `r1/`)
+8. **Plan topic** — for multi-plan reviews, the plan-specific subdirectory name
+9. **Task index** — sequential number for file naming (1, 2, 3...)
 
 If any verifier fails (error, timeout), record the failure and continue — aggregate what's available.
 
@@ -77,7 +85,7 @@ FINDINGS_COUNT: {N blocking issues}
 SUMMARY: {1 sentence}
 ```
 
-Full findings are written to `docs/workflow/review/{topic}/qa-task-{index}.md`.
+Full findings are written to `docs/workflow/review/{scope}/r{N}/qa-task-{index}.md` (single-plan) or `docs/workflow/review/{scope}/r{N}/{plan-topic}/qa-task-{index}.md` (multi-plan).
 
 ---
 
@@ -85,7 +93,7 @@ Full findings are written to `docs/workflow/review/{topic}/qa-task-{index}.md`.
 
 Once all batches have completed:
 
-1. Read all `docs/workflow/review/{topic}/qa-task-*.md` files
+1. Read all `docs/workflow/review/{scope}/r{N}/qa-task-*.md` files (and `{scope}/r{N}/{plan-topic}/qa-task-*.md` for multi-plan)
 2. Synthesize findings from file contents:
    - Collect all tasks with `STATUS: Incomplete` or `STATUS: Issues Found` as blocking issues
    - Collect all test issues (under/over-tested)

package/skills/technical-review/references/produce-review.md

@@ -0,0 +1,27 @@
+# Produce Review
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+Aggregate findings from both stages into a review document using the **[template.md](template.md)**.
+
+Write the review to `docs/workflow/review/{scope}/r{N}/review.md`. The review scope `{scope}` is the topic name (single) or a descriptive scope name (multi/all). The review number `r{N}` is passed in from the entry point.
+
+**QA Verdict** (from Step 3):
+- **Approve** — All acceptance criteria met, no blocking issues
+- **Request Changes** — Missing requirements, broken functionality, inadequate tests
+- **Comments Only** — Minor suggestions, non-blocking observations
+
+**Product Assessment** (from Step 4) — always advisory, presented alongside the verdict.
+
+Commit: `review({topic}): complete review`
+
+Present the review to the user.
+
+Your review feedback can be:
+- Addressed by implementation (same or new session)
+- Delegated to an agent for fixes
+- Overridden by user ("ship it anyway")
+
+You produce feedback. User decides what to do with it.

package/skills/technical-review/references/review-actions-loop.md

@@ -0,0 +1,303 @@
+# Review Actions Loop
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+After a review is complete, this loop synthesizes findings into actionable tasks.
+
+Stages A through E run sequentially. Always start at **A. Verdict Gate**.
+
+```
+A. Verdict gate (check verdicts, offer synthesis)
+B. Dispatch review synthesizer → invoke-review-synthesizer.md
+C. Approval gate (present tasks, approve/skip/comment)
+D. Create tasks in plan → invoke-review-task-writer.md
+E. Re-open implementation + plan mode handoff
+```
+
+---
+
+## A. Verdict Gate
+
+Check the verdict(s) from the review(s) being analyzed.
+
+#### If all verdicts are "Approve" with no required changes
+
+> *Output the next fenced block as a code block:*
+
+```
+No actionable findings. All reviews passed with no required changes.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If any verdict is "Request Changes"
+
+Blocking issues exist. Synthesis is strongly recommended.
+
+> *Output the next fenced block as a code block:*
+
+```
+The review found blocking issues that require changes.
+Synthesizing findings into actionable tasks is recommended.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Synthesize findings into tasks *(recommended)*
+- **`n`/`no`** — Skip synthesis
+
+Proceed with synthesis?
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If yes
+
+→ Proceed to **B. Dispatch Review Synthesizer**.
+
+#### If no
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If verdict is "Comments Only"
+
+Non-blocking improvements only. Synthesis is optional.
+
+> *Output the next fenced block as a code block:*
+
+```
+The review found non-blocking suggestions only.
+You can synthesize these into tasks or skip.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Synthesize findings into tasks
+- **`n`/`no`** — Skip synthesis *(default)*
+
+Synthesize non-blocking findings?
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If yes
+
+→ Proceed to **B. Dispatch Review Synthesizer**.
+
+#### If no
+
+**STOP.** Do not proceed — terminal condition.
+
+---
+
+## B. Dispatch Review Synthesizer
+
+Load **[invoke-review-synthesizer.md](invoke-review-synthesizer.md)** and follow its instructions.
+
+**STOP.** Do not proceed until the synthesizer has returned.
+
+#### If STATUS is "clean"
+
+> *Output the next fenced block as a code block:*
+
+```
+No actionable tasks synthesized.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If STATUS is "tasks_proposed"
+
+→ Proceed to **C. Approval Gate**.
+
+---
+
+## C. Approval Gate
+
+Read the staging file from `docs/workflow/implementation/{primary-topic}/review-tasks-c{cycle-number}.md`.
+
+Check `gate_mode` in the staging file frontmatter (`gated` or `auto`).
+
+Present an overview. For multi-plan reviews, group tasks by plan:
+
+> *Output the next fenced block as a code block:*
+
+```
+Review synthesis cycle {N}: {K} proposed tasks
+
+{plan-topic}:
+  1. {title} ({severity})
+  2. {title} ({severity})
+
+{plan-topic-2}:
+  3. {title} ({severity})
+```
+
+Then present each task with `status: pending` individually:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+**Task {current}/{total}: {title}** ({severity}) — Plan: {plan-topic}
+Sources: {sources}
+
+**Problem**: {problem}
+**Solution**: {solution}
+**Outcome**: {outcome}
+
+**Do**:
+{steps}
+
+**Acceptance Criteria**:
+{criteria}
+
+**Tests**:
+{tests}
+```
+
+#### If gate_mode is "gated"
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`a`/`approve`** — Approve this task
+- **`auto`** — Approve this and all remaining tasks automatically
+- **`s`/`skip`** — Skip this task
+- **Comment** — Revise based on feedback
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user input.
+
+#### If gate_mode is "auto"
+
+> *Output the next fenced block as a code block:*
+
+```
+Task {current} of {total}: {title} — approved (auto).
+```
+
+→ Continue to next task without stopping.
+
+---
+
+Process user input:
+
+#### If `approve`
+
+Update `status: approved` in the staging file.
+
+→ Present the next pending task, or proceed to routing below if all tasks processed.
+
+#### If `auto`
+
+Update `status: approved` in the staging file. Update `gate_mode: auto` in the staging file frontmatter.
+
+→ Continue processing remaining tasks without stopping.
+
+#### If `skip`
+
+Update `status: skipped` in the staging file.
+
+→ Present the next pending task, or proceed to routing below if all tasks processed.
+
+#### If comment
+
+Revise the task content in the staging file based on the user's feedback. Re-present this task.
+
+---
+
+After all tasks processed:
+
+→ If any tasks have `status: approved`, proceed to **D. Create Tasks in Plan**.
+
+→ If all tasks were skipped:
+
+Commit the staging file updates:
+
+```
+review({scope}): synthesis cycle {N} — tasks skipped
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+---
+
+## D. Create Tasks in Plan
+
+For each plan that has approved tasks in the staging file, invoke the task writer.
+
+Process plans sequentially — each writes to a different plan.
+
+For each plan:
+
+1. Filter staging file to tasks with `plan: {plan-topic}` and `status: approved`
+2. Load **[invoke-review-task-writer.md](invoke-review-task-writer.md)** and follow its instructions
+3. Wait for the task writer to return before processing the next plan
+
+**STOP.** Do not proceed until all task writers have returned.
+
+Commit all changes (staging file, plan tasks, Plan Index Files):
+
+```
+review({scope}): add review remediation ({K} tasks across {P} plans)
+```
+
+→ Proceed to **E. Re-open Implementation + Plan Mode Handoff**.
+
+---
+
+## E. Re-open Implementation + Plan Mode Handoff
+
+For each plan that received new tasks:
+
+1. Read the implementation tracking file at `docs/workflow/implementation/{topic}/tracking.md`
+2. Update frontmatter:
+   - `status: in-progress`
+   - Remove `completed` field (if present)
+   - `updated: {today's date}`
+   - `analysis_cycle: 0`
+3. Commit tracking changes:
+
+```
+review({scope}): re-open implementation tracking
+```
+
+Then enter plan mode and write the following plan:
+
+```
+# Review Actions Complete: {scope}
+
+Review findings have been synthesized into {N} implementation tasks.
+
+## Summary
+
+{Per-plan summary, e.g., "tick-core: 3 tasks in Phase 9", "installation: 1 task in Phase 6"}
+
+## Instructions
+
+1. Invoke `/start-implementation`
+2. The skill will detect the new tasks and start executing them
+
+## Context
+
+- Plans updated: {list of plan topics}
+- Tasks created: {total count}
+- Implementation tracking: re-opened for each plan
+
+## How to proceed
+
+Clear context and continue. Claude will start implementation
+and pick up the new review remediation tasks automatically.
+```
+
+Exit plan mode. The user will approve and clear context, and the fresh session will pick up with `/start-implementation` routing to the new tasks.