@leeovery/claude-technical-workflows 2.0.37 → 2.0.39

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.39",
   "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

package/skills/technical-specification/references/specification-guide.md

@@ -344,31 +344,13 @@ After documenting dependencies, perform a **final comprehensive review** of the
    - Error handling, validation rules, or boundary conditions
    - Integration points or data flows mentioned but not elaborated
 
-4. **Flag what you find** - When you discover potentially missed content, present it to the user. **Do NOT add it to the specification without explicit approval.**
+4. **Collect what you find** - When you discover potentially missed content, note it for your summary. You'll present all findings together after the review is complete (see "Presenting Review Findings" below).
 
-   > **CHECKPOINT**: If you found missed content and are about to add it to the specification without presenting it first and receiving explicit approval, **STOP**. Every addition requires the present → approve → log cycle, even during final review.
+   Categorize each finding:
 
-   There are two cases:
+   **Enhancing an existing topic** - Details that belong in an already-documented section. Note which section it would enhance.
 
-   **Enhancing an existing topic** - Details that belong in an already-documented section:
-
-   > "During my final review, I found additional detail about [existing topic] that isn't captured. From [source]:
-   >
-   > [quote or summary from source material]
-   >
-   > I'd add this to the [section name] section. Would you like me to include it, or show you the full section with this addition first?"
-
-   If the user wants to see context, present the entire section with the new content clearly marked (e.g., with a comment like `<!-- NEW -->` or by calling it out before the block).
-
-   **An entirely missed topic** - Something that warrants its own section but was glossed over:
-
-   > "During my final review, I found [topic] discussed in [source] that doesn't have coverage in the specification:
-   >
-   > [quote or summary from source material]
-   >
-   > This would be a new section. Should I add it?"
-
-   In both cases, you know where the content belongs - existing topics get enhanced in place, new topics get added at the end.
+   **An entirely missed topic** - Something that warrants its own section but was glossed over. New topics get added at the end.
 
 5. **Never fabricate** - Every item you flag must trace back to specific source material. If you can't point to where it came from, don't suggest it. The goal is to catch missed content, not invent new requirements.
 
@@ -380,19 +362,56 @@ After documenting dependencies, perform a **final comprehensive review** of the
    - Integration points that seem implicit but aren't specified
    - Behaviors that are ambiguous without clarification
 
-   Present these as a batch for the user to triage:
+   Collect these alongside the missed content from step 4. They'll be presented together in the summary (see below).
+
+   This should be infrequent - most gaps will be caught from source material. But occasionally the sources themselves have blind spots worth surfacing.
+
+### Presenting Review Findings
+
+After completing your review (steps 1-7), present findings to the user in two stages:
 
-   > "I've identified some potential gaps that aren't covered in the source material:
+**Stage 1: Summary of All Findings**
+
+First, present a numbered summary of everything you found:
+
+> "I've completed my final review against all source material. I found [N] items:
+>
+> 1. **[Brief title]**
+>    [2-4 line explanation: what was missed, where it came from, what it affects]
+>
+> 2. **[Brief title]**
+>    [2-4 line explanation]
+>
+> 3. **[Brief title]**
+>    [2-4 line explanation]
+>
+> Let's work through these one at a time, starting with #1."
+
+Each item should have enough context that the user understands what they're about to discuss - not just a label, but clarity on what was missed and why it matters.
+
+**Stage 2: Process One Item at a Time**
+
+For each item, follow the **same workflow as the main specification process**:
+
+1. **Present** the item in detail - what you found, where it came from (source reference), and what you propose to add
+2. **Discuss** if needed - clarify ambiguities, answer questions, refine the content
+3. **Present for approval** - show exactly what will be written to the specification:
+
+   > "Here's what I'll add to the specification:
    >
-   > 1. **[Gap A]** - [brief description of what's unclear/missing]
-   > 2. **[Gap B]** - [brief description]
-   > 3. **[Gap C]** - [brief description]
+   > [content exactly as it would appear]
    >
-   > Are any of these areas you'd like to discuss, or are they intentionally out of scope?"
+   > **To proceed, choose one:**
+   > - **"Log it"** - I'll add the above to the specification **verbatim**
+   > - **"Adjust"** - Tell me which part to change
 
-   The user can then pick which gaps (if any) need addressing. For those they want to discuss, work through them and add to the specification with standard approval workflow.
+4. **Wait for explicit approval** - same rules as always: "Log it" or equivalent before writing
+5. **Log verbatim** when approved
+6. **Move to the next item**: "Moving to #2: [Brief title]..."
 
-   This should be infrequent - most gaps will be caught from source material. But occasionally the sources themselves have blind spots worth surfacing.
+> **CHECKPOINT**: Each review item requires the full present → approve → log cycle. Do not batch multiple items together. Do not proceed to the next item until the current one is resolved (approved, adjusted, or explicitly skipped by the user).
+
+For potential gaps (items not in source material), you're asking questions rather than proposing content. If the user wants to address a gap, discuss it, then present what you'd add for approval.
 
 ### What You're NOT Doing