@leeovery/claude-technical-workflows 2.0.27 → 2.0.28

package/commands/workflow:start-discussion.md

@@ -58,82 +58,31 @@ Scan the codebase for research and discussions:
    - Do NOT modify or "simplify" this command - checksum must be deterministic
    - Store this value to compare with the cached checksum
 
-## Step 2: Present Workflow State and Options
+## Step 2: Analyze Research (if exists)
 
-Present the workflow state and available options based on what was discovered.
-
-**Format:**
-```
-📂 Workflow state:
-  📚 Research: {count} files found / None found
-  💬 Discussions: {count} existing / None yet
-```
-
-Then present the appropriate options:
-
-**If research AND discussions exist:**
-```
-How would you like to proceed?
-
-1. **From research** - Analyze research and suggest undiscussed topics
-2. **Continue discussion** - Resume an existing discussion
-3. **Fresh topic** - Start a new discussion
-```
-
-**If ONLY research exists:**
-```
-How would you like to proceed?
-
-1. **From research** - Analyze research and suggest topics to discuss
-2. **Fresh topic** - Start a new discussion
-```
-
-**If ONLY discussions exist:**
-```
-How would you like to proceed?
-
-1. **Continue discussion** - Resume an existing discussion
-2. **Fresh topic** - Start a new discussion
-```
-
-**If NOTHING exists:**
-```
-Starting fresh - no prior research or discussions found.
-
-What topic would you like to discuss?
-```
-Then skip to Step 5 (Fresh topic path).
-
-Wait for the user to choose before proceeding.
-
-## Step 3A: "From research" Path
+Skip this step if no research files were found in Step 1.
 
 This step uses caching to avoid re-analyzing unchanged research documents.
 
-### Step 3A.1: Check Cache Validity
+### Step 2.1: Check Cache Validity
 
 Compare the current research checksum (computed in Step 1.5) with the cached checksum:
 
 **If cache exists AND checksums match:**
 ```
-📋 Using cached analysis
-
-Research documents unchanged since last analysis ({date from cache}).
-Loading {count} previously identified topics...
-
-💡 To force a fresh analysis, enter: refresh
+📋 Using cached research analysis (unchanged since {date from cache})
 ```
 
-Then load the topics from the cache file and skip to Step 3A.3 (Cross-reference).
+Load the topics from the cache file and proceed to Step 2.3.
 
 **If cache missing OR checksums differ:**
 ```
 🔍 Analyzing research documents...
 ```
 
-Proceed to Step 3A.2 (Full Analysis).
+Proceed to Step 2.2 (Full Analysis).
 
-### Step 3A.2: Full Analysis (when cache invalid)
+### Step 2.2: Full Analysis (when cache invalid)
 
 Read each research file and analyze the content to extract key themes and potential discussion topics. For each theme:
 - Note the source file and relevant line numbers
@@ -180,93 +129,136 @@ research_files:
 
 Ensure the `.cache` directory exists: `mkdir -p docs/workflow/.cache`
 
-### Step 3A.3: Cross-reference with Discussions
-
-**Always performed** (whether using cache or fresh analysis):
+### Step 2.3: Cross-reference with Discussions
 
 For each identified topic, check if a corresponding discussion already exists in `docs/workflow/discussion/`.
 
-### Step 3A.4: Present Findings
+## Step 3: Present Workflow State and Options
 
-**If using cached analysis:**
-```
-📋 Cached analysis (research unchanged since {date})
+Present everything discovered to help the user make an informed choice.
 
-💡 Topics identified:
+**If NOTHING exists (no research, no discussions):**
+```
+Starting fresh - no prior research or discussions found.
 
-  ✨ {Theme name}
-     Source: {filename}.md (lines {start}-{end})
-     "{Brief summary}"
+What topic would you like to discuss?
+```
+Then skip to Step 5 (Gather Context) with the fresh topic path.
 
-  ✅ {Already discussed theme} → discussed in {topic}.md
-     Source: {filename}.md (lines {start}-{end})
-     "{Brief summary}"
+**Otherwise, present the full state:**
 
-Which topic would you like to discuss? (Or enter 'refresh' for fresh analysis)
 ```
-
-**If fresh analysis:**
+📂 Workflow state:
 ```
-🔍 Analysis complete (cached for future sessions)
 
-💡 Topics identified:
+**If research exists, show the topics:**
+```
+📚 Research topics:
 
-  ✨ {Theme name}
+  1. ✨ {Theme name}
      Source: {filename}.md (lines {start}-{end})
      "{Brief summary}"
 
-  ✅ {Already discussed theme} → discussed in {topic}.md
+  2. ✅ {Theme name} → discussed in {topic}.md
      Source: {filename}.md (lines {start}-{end})
      "{Brief summary}"
 
-Which topic would you like to discuss? (Or describe something else)
+  [... more topics ...]
 ```
 
 **Key:**
 - ✨ = Undiscussed topic (potential new discussion)
 - ✅ = Already has a corresponding discussion
 
-### Step 3A.5: Handle "refresh" Request
+**If discussions exist, show them:**
+```
+💬 Existing discussions:
 
-If user enters `refresh`:
-- Delete the cache file: `rm docs/workflow/.cache/research-analysis.md`
-- Return to Step 3A.2 (Full Analysis)
-- Inform user: "Refreshing analysis..."
+  • {topic}.md — {Status}
+    "{Brief description from context section}"
 
-**Important:** Keep track of the source file and line numbers for the chosen topic - this will be passed to the skill.
+  • {topic}.md — Concluded
+    "{Brief description}"
+```
 
-Wait for the user to choose before proceeding to Step 4.
+**Key:**
+- Exploring/Deciding = In progress
+- Concluded = Complete (can still be reopened)
 
-## Step 3B: "Continue discussion" Path
+**Then present the options based on what exists:**
 
-List existing discussions with their status:
+**If research AND discussions exist:**
+```
+How would you like to proceed?
 
+  • **From research** - Pick a topic number above (e.g., "research 1" or "1")
+  • **Continue discussion** - Name one above (e.g., "continue {topic}")
+  • **Fresh topic** - Describe what you want to discuss
+  • **refresh** - Force fresh research analysis
 ```
-💬 Existing discussions:
 
-  ⚡ {topic}.md — {Status}
-     "{Brief description from context section}"
+**If ONLY research exists:**
+```
+How would you like to proceed?
 
-  ⚡ {topic}.md — {Status}
-     "{Brief description}"
+  • **From research** - Pick a topic number above (e.g., "research 1" or "1")
+  • **Fresh topic** - Describe what you want to discuss
+  • **refresh** - Force fresh research analysis
+```
 
-  ✅ {topic}.md — Concluded
-     "{Brief description}"
+**If ONLY discussions exist:**
+```
+How would you like to proceed?
 
-Which discussion would you like to continue?
+  • **Continue discussion** - Name one above (e.g., "continue {topic}")
+  • **Fresh topic** - Describe what you want to discuss
 ```
 
-**Key:**
-- ⚡ = In progress (Exploring or Deciding)
-- ✅ = Concluded (can still be continued/reopened)
+Wait for the user to respond before proceeding.
+
+## Step 4A: "From research" Path
 
-Wait for the user to choose, then proceed to Step 4.
+User chose to start from research (e.g., "research 1", "1", "from research", or a topic name).
+
+**If user specified a topic inline** (e.g., "research 2", "2", or topic name):
+- Identify the selected topic from Step 3's numbered list
+- Proceed to Step 5 (Gather Context)
+
+**If user just said "from research" without specifying:**
+```
+Which research topic would you like to discuss? (Enter a number or topic name)
+```
+Wait for response, then proceed to Step 5.
+
+### Handle "refresh" Request
+
+If user enters `refresh`:
+- Delete the cache file: `rm docs/workflow/.cache/research-analysis.md`
+- Return to Step 2.2 (Full Analysis)
+- Inform user: "Refreshing analysis..."
+- After analysis, return to Step 3 to present updated findings
+
+**Important:** Keep track of the source file and line numbers for the chosen topic - this will be passed to the skill.
+
+## Step 4B: "Continue discussion" Path
+
+User chose to continue a discussion (e.g., "continue auth-flow" or "continue discussion").
+
+**If user specified a discussion inline** (e.g., "continue auth-flow"):
+- Identify the selected discussion from Step 3's list
+- Proceed to Step 5 (Gather Context)
+
+**If user just said "continue discussion" without specifying:**
+```
+Which discussion would you like to continue?
+```
+Wait for response, then proceed to Step 5.
 
-## Step 3C: "Fresh topic" Path
+## Step 4C: "Fresh topic" Path
 
-Proceed directly to Step 4.
+User wants to start a fresh discussion. Proceed directly to Step 5.
 
-## Step 4: Gather Context
+## Step 5: Gather Context
 
 Gather context based on the chosen path.
 
@@ -300,7 +292,7 @@ What would you like to focus on in this session?
 
 Wait for response before proceeding.
 
-## Step 5: Invoke the Skill
+## Step 6: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
@@ -313,7 +305,7 @@ Output: docs/workflow/discussion/{topic}.md
 
 Research reference:
 Source: docs/workflow/research/{filename}.md (lines {start}-{end})
-Summary: {the 1-2 sentence summary from Step 3A}
+Summary: {the 1-2 sentence summary from the research analysis}
 
 Invoke the technical-discussion skill.
 ```

package/package.json

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