@leeovery/claude-technical-workflows 2.0.37 → 2.0.38

package/commands/workflow/start-specification.md

@@ -56,12 +56,13 @@ This outputs structured YAML. Parse it to understand:
 - Specifications with `status: superseded` should be noted but excluded from active counts
 
 **From `cache` section:**
-- Whether a consolidation analysis cache exists
-- The `anchored_names` list - these are grouping names that have existing specifications and MUST be preserved in any regeneration
-
-**From `cache_validity` section:**
-- Whether the cache is still valid (`is_valid: true/false`)
-- The reason if invalid
+- `status` - one of three values:
+  - `"valid"` - cache exists and checksums match (safe to load)
+  - `"stale"` - cache exists but discussions have changed (needs re-analysis)
+  - `"none"` - no cache file exists
+- `reason` - explanation of the status
+- `generated` - when the cache was created (null if none)
+- `anchored_names` - grouping names that have existing specifications and MUST be preserved in any regeneration
 
 **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.
 
@@ -145,7 +146,31 @@ Proceeding with this discussion.
 
 #### If MULTIPLE concluded discussions exist with NO existing specifications
 
-No existing specs to continue - proceed directly to analysis.
+Check `cache.status` from discovery.
+
+##### If `cache.status: "valid"`
+
+```
+{N} concluded discussions found.
+
+Previous analysis available from {cache.generated}. Loading groupings...
+```
+
+→ Skip directly to **Step 7: Present Grouping Options**.
+
+##### If `cache.status: "stale"`
+
+```
+{N} concluded discussions found.
+
+Note: A previous grouping analysis exists but is now outdated - discussion documents have changed since it was created. Re-analysis is required, but existing specification names will be preserved where groupings overlap.
+
+Analyzing discussions for natural groupings...
+```
+
+→ Proceed to **Step 4: Gather Analysis Context**.
+
+##### If `cache.status: "none"`
 
 ```
 {N} concluded discussions found.
@@ -157,6 +182,39 @@ Analyzing discussions for natural groupings...
 
 #### If MULTIPLE concluded discussions exist WITH existing specifications
 
+Check `cache.status` from discovery to determine which options to present.
+
+##### If `cache.status: "valid"`
+
+```
+What would you like to do?
+
+1. **Continue an existing specification** - Resume work on a spec in progress
+2. **Select from groupings** - Choose from previously analyzed groupings ({cache.generated})
+3. **Re-analyze groupings** - Fresh analysis of discussion relationships
+
+Which approach?
+```
+
+**STOP.** Wait for user response.
+
+##### If `cache.status: "stale"`
+
+```
+What would you like to do?
+
+Note: A previous grouping analysis exists but is now outdated - discussion documents have changed since it was created. Re-analysis is required, but existing specification names will be preserved where groupings overlap.
+
+1. **Continue an existing specification** - Resume work on a spec in progress
+2. **Assess for groupings** - Re-analyze discussions for combinations
+
+Which approach?
+```
+
+**STOP.** Wait for user response.
+
+##### If `cache.status: "none"`
+
 ```
 What would you like to do?
 
@@ -179,7 +237,22 @@ Which specification would you like to continue?
 
 **STOP.** Wait for user to pick, then skip to **Step 9**.
 
-#### If "Assess for groupings"
+#### If "Select from groupings" (valid cache path)
+
+Load groupings from cache and → Skip directly to **Step 7: Present Grouping Options**.
+
+(Context was already gathered when the analysis was created - no need to ask again.)
+
+#### If "Re-analyze groupings"
+
+Delete the existing cache to force regeneration:
+```bash
+rm docs/workflow/.cache/discussion-consolidation-analysis.md
+```
+
+→ Proceed to **Step 4: Gather Analysis Context**.
+
+#### If "Assess for groupings" (no valid cache path)
 
 → Proceed to **Step 4: Gather Analysis Context**.
 
@@ -202,25 +275,25 @@ For example:
 
 ---
 
-## Step 5: Check Cache Validity
+## Step 5: Check Cache Status
 
-Check the `cache_validity.is_valid` value from the discovery state.
+Check `cache.status` from discovery.
 
-#### If cache is valid
+#### If `cache.status: "valid"`
 
 ```
 Using cached analysis
 
-Discussion documents unchanged since last analysis ({cached_date}).
+Discussion documents unchanged since last analysis ({cache.generated}).
 Loading previously identified groupings...
 ```
 
 Load groupings from cache and → Skip to **Step 7: Present Grouping Options**.
 
-#### If cache is invalid or missing
+#### If `cache.status: "stale"` or `"none"`
 
 ```
-{Reason from cache_validity.reason}
+{cache.reason}
 
 Analyzing discussions...
 ```

package/package.json

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

package/scripts/specification-discovery.sh

@@ -121,16 +121,35 @@ echo ""
 #
 # CACHE STATE
 #
+# status: "valid" | "stale" | "none"
+#   - valid: cache exists and checksums match
+#   - stale: cache exists but discussions have changed
+#   - none: no cache file exists
+#
 echo "cache:"
 
 if [ -f "$CACHE_FILE" ]; then
-    echo "  exists: true"
-
     cached_checksum=$(extract_field "$CACHE_FILE" "checksum")
     cached_date=$(extract_field "$CACHE_FILE" "generated")
 
-    echo "  cached_checksum: \"${cached_checksum:-unknown}\""
-    echo "  cached_date: \"${cached_date:-unknown}\""
+    # Determine status based on checksum comparison
+    if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ]; then
+        current_checksum=$(cat "$DISCUSSION_DIR"/*.md 2>/dev/null | md5sum | cut -d' ' -f1)
+
+        if [ "$cached_checksum" = "$current_checksum" ]; then
+            echo "  status: \"valid\""
+            echo "  reason: \"checksums match\""
+        else
+            echo "  status: \"stale\""
+            echo "  reason: \"discussions have changed since cache was generated\""
+        fi
+    else
+        echo "  status: \"stale\""
+        echo "  reason: \"no discussions to compare\""
+    fi
+
+    echo "  checksum: \"${cached_checksum:-unknown}\""
+    echo "  generated: \"${cached_date:-unknown}\""
 
     # Extract anchored names (groupings that have existing specs)
     # These are the grouping names from the cache that have corresponding specs
@@ -152,16 +171,17 @@ if [ -f "$CACHE_FILE" ]; then
         echo "    []  # No anchored names found"
     fi
 else
-    echo "  exists: false"
-    echo "  cached_checksum: null"
-    echo "  cached_date: null"
+    echo "  status: \"none\""
+    echo "  reason: \"no cache exists\""
+    echo "  checksum: null"
+    echo "  generated: null"
     echo "  anchored_names: []"
 fi
 
 echo ""
 
 #
-# CURRENT CHECKSUM
+# CURRENT STATE
 #
 echo "current_state:"
 
@@ -184,32 +204,3 @@ else
     echo "  discussions_checksum: null"
     echo "  concluded_discussion_count: 0"
 fi
-
-echo ""
-
-#
-# CHECKSUM COMPARISON
-#
-echo "cache_validity:"
-
-if [ -f "$CACHE_FILE" ]; then
-    cached_checksum=$(extract_field "$CACHE_FILE" "checksum")
-
-    if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ]; then
-        current_checksum=$(cat "$DISCUSSION_DIR"/*.md 2>/dev/null | md5sum | cut -d' ' -f1)
-
-        if [ "$cached_checksum" = "$current_checksum" ]; then
-            echo "  is_valid: true"
-            echo "  reason: \"checksums match\""
-        else
-            echo "  is_valid: false"
-            echo "  reason: \"discussions have changed since cache was generated\""
-        fi
-    else
-        echo "  is_valid: false"
-        echo "  reason: \"no discussions to compare\""
-    fi
-else
-    echo "  is_valid: false"
-    echo "  reason: \"no cache exists\""
-fi