@leeovery/claude-technical-workflows 2.1.34 → 2.1.35

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

@@ -31,8 +31,6 @@
 # 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"
 #
@@ -52,15 +50,8 @@ for review_file in "$REVIEW_DIR"/*.md; do
     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
@@ -101,6 +92,5 @@ for review_file in "$REVIEW_DIR"/*.md; do
         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/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/references/display-plans.md

@@ -98,8 +98,8 @@ Scope: single
 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

@@ -25,42 +25,36 @@ Saving session state so Claude can pick up where it left off if the conversation
 
 ## 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).
+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):**
-```
-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})
-
-Invoke the technical-review skill.
-```
+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 (multi/all):**
+**Example handoff:**
 ```
-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})
+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 (analysis-only):**
 ```
-Analysis session for: {scope description}
+Analysis session for: {topic}
 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}
+Review path: docs/workflow/review/{topic}/r{N}/
+Format: {format}
+Specification: {spec path}
 
 Invoke the technical-review skill.
 ```

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

@@ -37,7 +37,7 @@ Automatically proceed with the only available review.
 
 #### If scope is "all"
 
-All reviewable plans are included. No selection needed.
+All reviewable plans are included. No selection needed. Each plan will be reviewed independently.
 
 → Proceed directly to **Step 5**.
 

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

@@ -127,9 +127,9 @@ 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
+    for topic_dir in "$REVIEW_DIR"/*/; do
+        [ -d "$topic_dir" ] || continue
+        if ls -d "$topic_dir"r*/review.md >/dev/null 2>&1; then
             has_reviews="true"
             break
         fi
@@ -140,15 +140,14 @@ if [ -d "$REVIEW_DIR" ]; then
     if [ "$has_reviews" = "true" ]; then
         echo "  entries:"
 
-        for scope_dir in "$REVIEW_DIR"/*/; do
-            [ -d "$scope_dir" ] || continue
-            scope=$(basename "$scope_dir")
-
+        for topic_dir in "$REVIEW_DIR"/*/; do
+            [ -d "$topic_dir" ] || continue
+            topic=$(basename "$topic_dir")
             # Count r*/ versions
             versions=0
             latest_version=0
             latest_path=""
-            for rdir in "$scope_dir"r*/; do
+            for rdir in "$topic_dir"r*/; do
                 [ -d "$rdir" ] || continue
                 [ -f "${rdir}review.md" ] || continue
                 rnum=${rdir##*r}
@@ -169,67 +168,19 @@ if [ -d "$REVIEW_DIR" ]; then
                     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
+            # Check for synthesis: look for review-tasks-c*.md in implementation dir
             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
+            if ls "$IMPL_DIR/$topic"/review-tasks-c*.md >/dev/null 2>&1; then
+                has_synthesis="true"
             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
+            if ! echo " $reviewed_plans " | grep -q " $topic "; then
+                reviewed_plans="$reviewed_plans $topic"
+                reviewed_plan_count=$((reviewed_plan_count + 1))
+            fi
 
-            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 "    - topic: \"$topic\""
             echo "      versions: $versions"
             echo "      latest_version: $latest_version"
             echo "      latest_verdict: \"$latest_verdict\""

package/skills/start-specification/SKILL.md

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

package/skills/start-specification/references/analysis-flow.md

@@ -65,10 +65,10 @@ When forming groupings:
 
 Create the cache directory if needed:
 ```bash
-mkdir -p docs/workflow/.cache
+mkdir -p docs/workflow/.state
 ```
 
-Write to `docs/workflow/.cache/discussion-consolidation-analysis.md`:
+Write to `docs/workflow/.state/discussion-consolidation-analysis.md`:
 
 ```markdown
 ---

package/skills/start-specification/references/display-analyze.md

@@ -87,7 +87,7 @@ Proceed with analysis?
 
 If cache is stale, delete it first:
 ```bash
-rm docs/workflow/.cache/discussion-consolidation-analysis.md
+rm docs/workflow/.state/discussion-consolidation-analysis.md
 ```
 
 → Load **[analysis-flow.md](analysis-flow.md)** and follow its instructions.

package/skills/start-specification/references/display-groupings.md

@@ -8,7 +8,7 @@ Shows when cache is valid (directly from routing) or after analysis completes. T
 
 ## A. Load Groupings
 
-Load groupings from `docs/workflow/.cache/discussion-consolidation-analysis.md`. Parse the `### {Name}` headings and their discussion lists.
+Load groupings from `docs/workflow/.state/discussion-consolidation-analysis.md`. Parse the `### {Name}` headings and their discussion lists.
 
 → Proceed to **B. Determine Discussion Status**.
 
@@ -160,7 +160,7 @@ Every meta option (Unify, Re-analyze) MUST include its description lines.
 
 #### If user picks "Unify all"
 
-Update the cache: rewrite `docs/workflow/.cache/discussion-consolidation-analysis.md` with a single "Unified" grouping containing all concluded discussions. Keep the same checksum, update the generated timestamp. Add note: `Custom groupings confirmed by user (unified).`
+Update the cache: rewrite `docs/workflow/.state/discussion-consolidation-analysis.md` with a single "Unified" grouping containing all concluded discussions. Keep the same checksum, update the generated timestamp. Add note: `Custom groupings confirmed by user (unified).`
 
 Spec name: "Unified". Sources: all concluded discussions.
 
@@ -170,7 +170,7 @@ Spec name: "Unified". Sources: all concluded discussions.
 
 Delete the cache:
 ```bash
-rm docs/workflow/.cache/discussion-consolidation-analysis.md
+rm docs/workflow/.state/discussion-consolidation-analysis.md
 ```
 
 → Load **[analysis-flow.md](analysis-flow.md)** and follow its instructions.

package/skills/start-specification/references/display-specs-menu.md

@@ -139,7 +139,7 @@ Menu descriptions are wrapped in backticks to visually distinguish them from the
 
 If cache is stale, delete it first:
 ```bash
-rm docs/workflow/.cache/discussion-consolidation-analysis.md
+rm docs/workflow/.state/discussion-consolidation-analysis.md
 ```
 
 → Load **[analysis-flow.md](analysis-flow.md)** and follow its instructions.

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

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

package/skills/technical-planning/SKILL.md

@@ -59,7 +59,7 @@ this, or is there a more complete version?
 Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:
 
 1. **Re-read this skill file completely.** Do not rely on your summary of it. The full process, steps, and rules must be reloaded.
-2. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
+2. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress. Check for scratch files at `docs/workflow/.cache/planning/{topic}/`. If a scratch file exists, you are mid-authoring for that phase — resume the approval loop in author-tasks.md.
 3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
 4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
 5. **Check `task_list_gate_mode`, `author_gate_mode`, and `finding_gate_mode`** in the Plan Index File frontmatter — if `auto`, the user previously opted in during this session. Preserve these values.
@@ -126,8 +126,9 @@ Reset `task_list_gate_mode`, `author_gate_mode`, and `finding_gate_mode` to `gat
 
 1. Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the format's **[authoring.md](references/output-formats/{format}/authoring.md)**
 2. Follow the authoring file's cleanup instructions to remove Authored Tasks for this topic
-3. Delete the Plan Index File
-4. Commit: `planning({topic}): restart planning`
+3. Delete the scratch directory if it exists: `rm -rf docs/workflow/.cache/planning/{topic}/`
+4. Delete the Plan Index File
+5. Commit: `planning({topic}): restart planning`
 
 → Proceed to **Step 1**.