@leeovery/claude-technical-workflows 2.0.10 → 2.0.11

package/commands/start-discussion.md

@@ -1,36 +1,218 @@
 ---
-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
+
+## 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
+
+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
+
+Cross-reference with existing discussions to identify what has and hasn't been discussed.
+
+**Present findings:**
+```
+🔍 Analyzing research documents...
+
+💡 Topics identified:
+
+  ✨ {Theme name}
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief 1-2 sentence summary of the theme and what needs deciding}"
+
+  ✨ {Another theme}
+     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
+
+**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.11",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",