@leeovery/claude-technical-workflows 2.0.25 → 2.0.26

package/commands/workflow:start-specification.md

@@ -1,5 +1,5 @@
 ---
-description: Start a specification session from an existing discussion. Discovers available discussions, checks for existing specifications, and invokes the technical-specification skill.
+description: Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill.
 ---
 
 Invoke the **technical-specification** skill for this conversation.
@@ -17,7 +17,7 @@ This is **Phase 3** of the six-phase workflow:
 | 5. Implementation | DOING - tests first, then code | |
 | 6. Review | VALIDATING - check work against artifacts | |
 
-**Stay in your lane**: Validate and refine discussion content into a standalone specification. Don't jump to planning, phases, tasks, or code. The specification is the "line in the sand" - everything after this has hard dependencies on it.
+**Stay in your lane**: Validate and refine discussion content into standalone specifications. Don't jump to planning, phases, tasks, or code. The specification is the "line in the sand" - everything after this has hard dependencies on it.
 
 ---
 
@@ -46,40 +46,221 @@ Scan the codebase for discussions and specifications:
 3. **Check for existing specifications**: Look in `docs/workflow/specification/`
    - Identify discussions that don't have corresponding specifications
 
+4. **Check for cached consolidation analysis** (if multiple discussions):
+   - Check if `docs/workflow/.cache/discussion-consolidation-analysis.md` exists
+   - If it exists, read it to get the stored checksum from the frontmatter
+
+5. **Compute current discussions checksum** (if multiple concluded discussions):
+   - Run exactly: `cat docs/workflow/discussion/*.md 2>/dev/null | md5sum | cut -d' ' -f1`
+   - IMPORTANT: Use this exact command - glob expansion is alphabetically sorted by default
+   - Do NOT modify or "simplify" this command - checksum must be deterministic
+   - Store this value to compare with the cached checksum
+
 ## Step 2: Check Prerequisites
 
 **If no discussions exist:**
 
 ```
-⚠️ No discussions found in docs/workflow/discussion/
+No discussions found in docs/workflow/discussion/
 
 The specification phase requires a completed discussion. Please run /workflow:start-discussion first to document the technical decisions, edge cases, and rationale before creating a specification.
 ```
 
 Stop here and wait for the user to acknowledge.
 
-## Step 3: Present Options to User
+## Step 3: Present Options
 
-Show what you found using a list like below:
+Show what you found:
 
 ```
-📂 Discussions found:
-  ✅ {topic-1} - Concluded - ready for specification
-  ⚠️ {topic-2} - Exploring - not ready for specification
-  ✅ {topic-3} - Concluded - specification exists
-
-Which discussion would you like to create a specification for?
+Discussions found:
+  {topic-1} - Concluded - ready for specification
+  {topic-2} - Exploring - not ready for specification
+  {topic-3} - Concluded - specification exists
 ```
 
 **Important:** Only concluded discussions should proceed to specification. If a discussion is still exploring, advise the user to complete the discussion phase first.
 
-Ask: **Which discussion would you like to specify?**
+**If only ONE concluded discussion is ready:** Skip to Step 4 (single-source path).
+
+**If MORE THAN ONE concluded discussion is ready:** Proceed to Step 3A (consolidation assessment).
+
+---
+
+## Step 3A: Consolidation Assessment (Multiple Discussions)
+
+When multiple concluded discussions exist, offer to assess how they should be organized into specifications.
+
+```
+You have {N} concluded discussions ready for specification.
+
+Would you like me to assess how these might be combined into specifications?
+
+1. **Yes, assess them** - I'll analyze all discussions for natural groupings
+2. **No, proceed individually** - Create specifications 1:1 with discussions
+
+Which approach?
+```
+
+**If user chooses individual:** Skip to Step 4 and ask which discussion to specify.
+
+**If user chooses assessment:** Proceed to Step 3A.1.
+
+### Step 3A.1: Gather Context for Analysis
+
+Before analyzing, ask:
+
+```
+Before I analyze the discussions, is there anything about your project structure or how these topics relate that would help me group them appropriately?
+```
+
+Wait for response.
+
+### Step 3A.2: Check Cache Validity
+
+Compare the current discussions checksum (computed in Step 1.5) with the cached checksum:
+
+**If cache exists AND checksums match:**
+```
+Using cached analysis
+
+Discussion documents unchanged since last analysis ({date from cache}).
+Loading previously identified groupings...
+
+To force a fresh analysis, enter: refresh
+```
+
+Then load the groupings from the cache file and skip to Step 3A.4 (Present Options).
+
+**If cache missing OR checksums differ:**
+```
+Analyzing discussions...
+```
+
+Proceed to Step 3A.3 (Full Analysis).
+
+### Step 3A.3: Full Analysis (when cache invalid)
+
+**This step is critical. You MUST read every concluded discussion document thoroughly.**
+
+For each concluded discussion:
+1. Read the ENTIRE document (not just frontmatter)
+2. Understand the decisions, systems, and concepts it defines
+3. Note dependencies on or references to other discussions
+4. Identify shared data structures, entities, or behaviors
+
+Then analyze coupling between discussions:
+- **Data coupling**: Discussions that define or depend on the same data structures
+- **Behavioral coupling**: Discussions where one's implementation requires another
+- **Conceptual coupling**: Discussions that address different facets of the same problem
+
+Group discussions that are tightly coupled - they should become a single specification because their decisions are inseparable.
+
+**Save to cache:**
+After analysis, ensure `.cache` directory exists: `mkdir -p docs/workflow/.cache`
+
+Create/update `docs/workflow/.cache/discussion-consolidation-analysis.md`:
+
+```markdown
+---
+checksum: {computed_checksum}
+generated: {ISO date}
+discussion_files:
+  - {topic1}.md
+  - {topic2}.md
+---
+
+# Discussion Consolidation Analysis
+
+## Recommended Groupings
+
+### {Suggested Specification Name}
+- **{topic-a}**: {why it belongs in this group}
+- **{topic-b}**: {why it belongs in this group}
+- **{topic-c}**: {why it belongs in this group}
+
+**Coupling**: {Brief explanation of what binds these together - shared data, dependencies, etc.}
+
+### {Another Specification Name}
+- **{topic-d}**: {why it belongs}
+- **{topic-e}**: {why it belongs}
+
+**Coupling**: {Brief explanation}
+
+## Independent Discussions
+- **{topic-f}**: {Why this stands alone - no strong coupling to others}
+
+## Analysis Notes
+{Any additional context about the relationships discovered}
+```
+
+### Step 3A.4: Present Options
+
+Present the analysis and options:
+
+**If using cached analysis:**
+```
+Cached analysis (discussions unchanged since {date})
+
+{Display the Recommended Groupings section from cache}
+
+How would you like to proceed?
+
+1. **Combine as recommended** - Create specifications per the groupings above
+2. **Combine differently** - Tell me your preferred groupings
+3. **Single specification** - Consolidate all discussions into one spec
+4. **Individual specifications** - Create 1:1 (I'll ask which to start with)
+
+(Or enter 'refresh' to re-analyze)
+```
+
+**If fresh analysis:**
+```
+Analysis complete (cached for future sessions)
+
+{Display the Recommended Groupings section}
+
+How would you like to proceed?
+
+1. **Combine as recommended** - Create specifications per the groupings above
+2. **Combine differently** - Tell me your preferred groupings
+3. **Single specification** - Consolidate all discussions into one spec
+4. **Individual specifications** - Create 1:1 (I'll ask which to start with)
+```
+
+Wait for user to choose.
+
+### Step 3A.5: Handle Choices
+
+**If "Combine as recommended":**
+- Confirm the first specification to create
+- Proceed to Step 4 with the grouped sources
+
+**If "Combine differently":**
+- Ask user to describe their preferred groupings
+- Confirm understanding
+- Proceed to Step 4 with user-specified sources
+
+**If "Single specification":**
+- Use "unified" as the specification name (output: `docs/workflow/specification/unified.md`)
+- Proceed to Step 4 with all discussions as sources
+
+**If "Individual specifications":**
+- Ask which discussion to specify first
+- Proceed to Step 4 with single source
+
+**If "refresh":**
+- Delete the cache file: `rm docs/workflow/.cache/discussion-consolidation-analysis.md`
+- Return to Step 3A.3 (Full Analysis)
+- Inform user: "Refreshing analysis..."
+
+---
 
 ## Step 4: Gather Additional Context
 
 Ask:
 - Any additional context or priorities to consider?
-- Any constraints or changes since the discussion concluded?
+- Any constraints or changes since the discussion(s) concluded?
 - Are there any existing partial plans or related documentation I should review?
 
 ## Step 5: Invoke the Skill
@@ -88,7 +269,7 @@ After completing the steps above, this command's purpose is fulfilled.
 
 Invoke the [technical-specification](../skills/technical-specification/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:**
+**Example handoff (single source):**
 ```
 Specification session for: {topic}
 Source: docs/workflow/discussion/{topic}.md
@@ -98,7 +279,26 @@ Additional context: {summary of user's answers from Step 4}
 Invoke the technical-specification skill.
 ```
 
+**Example handoff (multiple sources):**
+```
+Specification session for: {specification-name}
+
+Sources:
+- docs/workflow/discussion/{topic-1}.md
+- docs/workflow/discussion/{topic-2}.md
+- docs/workflow/discussion/{topic-3}.md
+
+Output: docs/workflow/specification/{specification-name}.md
+Additional context: {summary of user's answers from Step 4}
+
+Invoke the technical-specification skill.
+```
+
+---
+
 ## Notes
 
 - Ask questions clearly and wait for responses before proceeding
-- The specification phase validates and refines discussion content into a standalone document
+- The specification phase validates and refines discussion content into standalone documents
+- When multiple sources are provided, the skill will extract exhaustively from ALL of them
+- Attribution in the specification should trace content back to its source discussion(s)

package/package.json

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

package/skills/technical-specification/SKILL.md

@@ -19,8 +19,8 @@ Either way: Transform unvalidated reference material into a specification that's
 
 ### What This Skill Needs
 
-- **Source material** (required) - The content to synthesize into a specification. Can be:
-  - Discussion documents or research notes
+- **Source material** (required) - One or more sources to synthesize into a specification. Can be:
+  - Discussion documents or research notes (single or multiple)
   - Inline feature descriptions
   - Requirements docs, design documents, or transcripts
   - Any other reference material
@@ -28,6 +28,8 @@ Either way: Transform unvalidated reference material into a specification that's
 
 **If missing:** Will ask user to provide context or point to source files.
 
+**Multiple sources:** When multiple sources are provided, extract exhaustively from ALL of them. Content may be scattered across sources - a decision in one may have constraints or details in another. The specification consolidates everything into a single standalone document.
+
 ## The Process
 
 **Load**: [specification-guide.md](references/specification-guide.md)
@@ -62,7 +64,7 @@ If you are uncertain whether the user approved, **ASK**: "Would you like me to l
 
 ## What You Do
 
-1. **Extract exhaustively**: For each topic, re-scan ALL source material. Search for keywords and related terms. Information is often scattered - collect it all before synthesizing. Include only what we're building (not discarded alternatives).
+1. **Extract exhaustively**: For each topic, re-scan ALL source materials. When working with multiple sources, search each one - information about a single topic may be scattered across documents. Search for keywords and related terms. Collect everything before synthesizing. Include only what we're building (not discarded alternatives).
 
 2. **Filter**: Reference material may contain hallucinations, inaccuracies, or outdated concepts. Validate before including.
 
@@ -88,6 +90,8 @@ The specification is the **golden document** - planning uses only this. If infor
 
 **Trust nothing without validation**: Synthesize and present, but never assume source material is correct.
 
+**Surface conflicts**: When sources contain conflicting decisions, flag the conflict to the user during the discussion. Don't silently pick one - let the user decide what makes it into the specification.
+
 ---
 
 ## Self-Check: Are You Following the Rules?