@leeovery/claude-technical-workflows 2.0.10 → 2.0.12

package/commands/start-discussion.md

@@ -1,36 +1,321 @@
 ---
-description: Start a technical discussion using the technical-discussion skill. Gathers information about the topic and creates discussion documentation in docs/workflow/discussion/
+description: Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill.
 ---
 
 Invoke the **technical-discussion** skill for this conversation.
 
-Before beginning, ask the user these questions to properly set up the discussion:
+## Instructions
 
-## Essential Information
+Follow these steps EXACTLY as written. Do not skip steps or combine them. Present output using the EXACT format shown in examples - do not simplify or alter the formatting.
 
-1. **Discussion Topic**: What are we discussing? (This will be used as the filename in `docs/workflow/discussion/{topic}.md`)
+Before beginning, discover existing work and determine the best entry path.
 
-2. **Context & Background**:
-   - What sparked this discussion?
-   - What problem are we trying to solve?
-   - Why are we discussing this now?
+## Important
 
-3. **Foundational Knowledge**:
-   - Is there any background information I need to understand before we begin?
-   - Are there specific concepts, technologies, or architectures I should know about?
-   - Any constraints, requirements, or limitations I should be aware of?
+Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
 
-4. **Codebase Review**:
-   - Are there specific files in this repository I should read first?
-   - Should I explore any particular directories or components?
-   - Is there existing code related to this discussion?
+## Step 1: Discover Existing Work
 
-## After Gathering Information
+Scan the codebase for research and discussions:
 
-Once I have this information:
+1. **Find research**: Look in `docs/workflow/research/`
+   - Run `ls docs/workflow/research/` to list research files
+   - Note which files exist (may include `exploration.md` and semantic files like `market-landscape.md`)
+
+2. **Find discussions**: Look in `docs/workflow/discussion/`
+   - Run `ls docs/workflow/discussion/` to list discussion files
+   - Each file is named `{topic}.md`
+
+3. **Check discussion status**: For each discussion file
+   - Run `head -10 docs/workflow/discussion/{topic}.md` to extract the `Status:` field
+   - Status values: `Exploring`, `Deciding`, or `Concluded`
+   - Do NOT use bash loops - run separate commands for each file
+
+4. **Check for cached analysis** (if research files exist):
+   - Check if `docs/workflow/.cache/research-analysis.md` exists
+   - If it exists, read it to get the stored checksum from the frontmatter
+
+5. **Compute current research checksum** (if research files exist):
+   - Run: `cat $(ls docs/workflow/research/*.md | sort) 2>/dev/null | md5sum | cut -d' ' -f1`
+   - This creates a combined checksum of all research files (sorted alphabetically)
+   - Store this value to compare with the cached checksum
+
+## Step 2: Present Workflow State and Options
+
+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
+
+This step uses caching to avoid re-analyzing unchanged research documents.
+
+### Step 3A.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
+```
+
+Then load the topics from the cache file and skip to Step 3A.3 (Cross-reference).
+
+**If cache missing OR checksums differ:**
+```
+🔍 Analyzing research documents...
+```
+
+Proceed to Step 3A.2 (Full Analysis).
+
+### Step 3A.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
+- Summarize what the theme is about in 1-2 sentences
+- Identify key questions or decisions that need discussion
+
+**Be thorough**: This analysis will be cached, so take time to identify ALL potential topics including:
+- Major architectural decisions
+- Technical trade-offs mentioned
+- Open questions or concerns raised
+- Implementation approaches discussed
+- Integration points with external systems
+- Security or performance considerations
+- Edge cases or error handling mentioned
+
+**Save to cache:**
+After analysis, create/update `docs/workflow/.cache/research-analysis.md`:
+
+```markdown
+---
+checksum: {computed_checksum}
+generated: {ISO date}
+research_files:
+  - {filename1}.md
+  - {filename2}.md
+---
+
+# Research Analysis Cache
+
+## Topics
+
+### {Theme name}
+- **Source**: {filename}.md (lines {start}-{end})
+- **Summary**: {1-2 sentence summary}
+- **Key questions**: {what needs deciding}
+
+### {Another theme}
+- **Source**: {filename}.md (lines {start}-{end})
+- **Summary**: {1-2 sentence summary}
+- **Key questions**: {what needs deciding}
+
+[... more topics ...]
+```
+
+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):
+
+For each identified topic, check if a corresponding discussion already exists in `docs/workflow/discussion/`.
+
+### Step 3A.4: Present Findings
+
+**If using cached analysis:**
+```
+📋 Cached analysis (research unchanged since {date})
+
+💡 Topics identified:
+
+  ✨ {Theme name}
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+  ✅ {Already discussed theme} → discussed in {topic}.md
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+Which topic would you like to discuss? (Or enter 'refresh' for fresh analysis)
+```
+
+**If fresh analysis:**
+```
+🔍 Analysis complete (cached for future sessions)
+
+💡 Topics identified:
+
+  ✨ {Theme name}
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+  ✅ {Already discussed theme} → discussed in {topic}.md
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+Which topic would you like to discuss? (Or describe something else)
+```
+
+**Key:**
+- ✨ = Undiscussed topic (potential new discussion)
+- ✅ = Already has a corresponding discussion
+
+### Step 3A.5: Handle "refresh" Request
+
+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..."
+
+**Important:** Keep track of the source file and line numbers for the chosen topic - this will be passed to the skill.
+
+Wait for the user to choose before proceeding to Step 4.
+
+## Step 3B: "Continue discussion" Path
+
+List existing discussions with their status:
+
+```
+💬 Existing discussions:
+
+  ⚡ {topic}.md — {Status}
+     "{Brief description from context section}"
+
+  ⚡ {topic}.md — {Status}
+     "{Brief description}"
+
+  ✅ {topic}.md — Concluded
+     "{Brief description}"
+
+Which discussion would you like to continue?
+```
+
+**Key:**
+- ⚡ = In progress (Exploring or Deciding)
+- ✅ = Concluded (can still be continued/reopened)
+
+Wait for the user to choose, then proceed to Step 4.
+
+## Step 3C: "Fresh topic" Path
+
+Proceed directly to Step 4.
+
+## Step 4: Gather Context
+
+Gather context based on the chosen path.
+
+**If starting new discussion (from research or fresh):**
+
+```
+## New discussion: {topic}
+
+Before we begin:
+
+1. What's the core problem or decision we need to work through?
+
+2. Any constraints or context I should know about?
+
+3. Are there specific files in the codebase I should review first?
+```
+
+Wait for responses before proceeding.
+
+**If continuing existing discussion:**
+
+Read the existing discussion document first, then ask:
+
+```
+## Continuing: {topic}
+
+I've read the existing discussion.
+
+What would you like to focus on in this session?
+```
+
+Wait for response before proceeding.
+
+## Step 5: Invoke Discussion Skill
+
+Begin the discussion session with appropriate context based on the path taken.
+
+**If from research:**
+```
+Discussion session for: {topic}
+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}
+
+Begin discussion using the technical-discussion skill.
+```
+
+**If continuing or fresh:**
+```
+Discussion session for: {topic}
+Source: {existing discussion | fresh}
+Output: docs/workflow/discussion/{topic}.md
+
+Begin discussion using the technical-discussion skill.
+```
+
+**Setup:**
 - Ensure discussion directory exists: `docs/workflow/discussion/`
-- Start documenting the discussion following the technical-discussion skill structure
-- Create file: `docs/workflow/discussion/{topic}.md`
+- If new: Create file using the template structure
+- If continuing: Work with existing file
 - Commit frequently at natural discussion breaks
 
-Ask these questions clearly and wait for responses before proceeding with the discussion.
+## Notes
+
+- Ask questions clearly and wait for responses before proceeding
+- Discussion captures WHAT and WHY - don't jump to specifications or implementation
+- The goal is to work through edge cases, debates, and decisions before planning
+- Commit the discussion document frequently during the session

package/package.json

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