@riotprompt/riotplan 1.0.5 → 1.0.6

package/MCP-EXPLORE-IDEA-FIX.md

@@ -0,0 +1,122 @@
+# Fix: explore_idea Command UX Issue
+
+## Problem
+
+The `explore_idea` MCP prompt had a workflow mismatch that created a confusing user experience:
+
+1. User invokes the prompt (via MCP or Cursor command)
+2. AI would immediately stop and ask for structured input:
+   - "Please provide a code/identifier"
+   - "Please provide an initial description"
+3. User had to provide these in a second interaction
+4. Only then would the AI create the idea and begin exploration
+
+This created a jarring, form-filling experience instead of a natural conversational flow.
+
+## Root Cause
+
+The MCP prompt file (`src/mcp/prompts/explore_idea.md`) had outdated instructions that told the AI to:
+1. Ask the user for code and description
+2. Wait for response
+3. Then create the idea
+
+Meanwhile, the Cursor command version (`.cursor/commands/explore_idea.md`) had already been updated with smart extraction logic.
+
+## Solution
+
+Updated the MCP prompt to match the improved Cursor command version with smart extraction:
+
+### Key Changes
+
+1. **Smart Extraction First**: AI now checks if the user already provided code/description in their message
+2. **Derive Missing Info**: If description is provided but code is missing, AI derives a kebab-case code from the description
+3. **Natural Fallback**: Only asks for missing information if truly needed
+4. **Immediate Creation**: Creates the idea as soon as it has the required info
+5. **Start Exploration**: Begins the exploration conversation immediately after creation
+
+### Updated Workflow
+
+```
+1. Extract or Gather Idea Details
+   - Check user's message for code and description
+   - Extract if present
+   - Derive code from description if only description provided
+   - Only ask if both are missing
+
+2. Create the Idea
+   - Call riotplan_idea_create immediately with extracted/derived values
+
+3. Begin Exploration
+   - Start asking open-ended questions immediately
+   - Don't wait for further prompting
+```
+
+### Example Flows
+
+**Before Fix:**
+```
+User: /riotplan/explore_idea
+AI: "Please provide: 1. A short code/identifier 2. Initial description"
+User: "Ugh, okay... code is 'my-feature', description is 'Add feature X'"
+AI: *calls riotplan_idea_create*
+AI: "What's driving this?"
+```
+
+**After Fix - Full Info:**
+```
+User: /riotplan/explore_idea real-time-notifications Add push notifications
+AI: *extracts code="real-time-notifications", description="Add push notifications"*
+AI: *calls riotplan_idea_create immediately*
+AI: "Let's explore this idea. What's driving the need for push notifications?"
+```
+
+**After Fix - Partial Info:**
+```
+User: /riotplan/explore_idea I want to add notifications
+AI: *derives code="add-notifications", description="I want to add notifications"*
+AI: *calls riotplan_idea_create immediately*
+AI: "Let's explore this notification idea. What's driving this?"
+```
+
+**After Fix - No Info:**
+```
+User: /riotplan/explore_idea
+AI: "What idea would you like to explore? Give me a short name and brief description."
+User: "I'm thinking about real-time notifications"
+AI: *extracts and creates immediately*
+AI: "Great! Let's explore this. What's driving the need?"
+```
+
+## Files Changed
+
+- `/Users/tobrien/gitw/kjerneverk/riotplan/src/mcp/prompts/explore_idea.md`
+  - Updated workflow section with smart extraction logic
+  - Added detailed examples showing extraction patterns
+  - Added anti-pattern: "Don't ask for information the user already provided"
+  - Added principle: "Smart Extraction: Use information the user already provided"
+
+## Testing
+
+- All existing tests pass (623 tests, 92.84% coverage)
+- No breaking changes to MCP tool schemas
+- Backward compatible with all existing workflows
+
+## Benefits
+
+1. **Better UX**: Natural conversational flow instead of form-filling
+2. **Fewer Steps**: Reduces interaction from 2-3 messages to 1
+3. **Smarter AI**: AI extracts and derives information intelligently
+4. **Consistent**: MCP prompt now matches Cursor command behavior
+5. **Flexible**: Still supports all three scenarios (full info, partial info, no info)
+
+## Related Work
+
+The Cursor command version (`.cursor/commands/explore_idea.md`) already had this smart extraction logic. This fix brings the MCP prompt in sync with that improved version.
+
+## Future Considerations
+
+This pattern could be applied to other interactive prompts/commands that currently ask for structured input upfront. Candidates to review:
+- `checkpoint_create` (asks for name and message)
+- Any other prompts that immediately request structured data
+
+The key insight: **Extract first, ask later**. If the user has already provided information in their message, use it instead of asking them to repeat it.

package/dist/mcp/prompts/explore_idea.md

@@ -13,21 +13,49 @@ Guide collaborative exploration of a new idea without premature commitment. This
 
 ## Workflow
 
-### 1. Create the Idea
+### 1. Extract or Gather Idea Details
 
-Ask the user for:
-- A short code/identifier (kebab-case)
-- Initial description of the concept
+**FIRST: Check if the user already provided details in their message.**
+
+Look for:
+- A code/identifier (kebab-case name like "my-feature")
+- A description of the concept
+
+**If both are present in the user's message:**
+- Extract them immediately
+- Proceed directly to creating the idea
+- Do NOT ask the user to repeat information they already provided
+
+**If either is missing:**
+- Have a natural conversation: "What idea would you like to explore? Give me a short name and brief description."
+- When they respond, extract the code (convert to kebab-case if needed) and description
+- Then create the idea
+
+**Example extractions:**
+
+User says: "explore_idea user-notifications I want to add real-time notifications"
+→ code: "user-notifications", description: "I want to add real-time notifications"
+
+User says: "explore_idea real-time notifications for users"
+→ code: "real-time-notifications" (derived), description: "real-time notifications for users"
+
+User says: "explore_idea"
+→ Ask: "What idea would you like to explore? Give me a short name and brief description."
+
+### 2. Create the Idea
+
+Once you have both code and description, create the idea immediately:
 
-Create the idea:
 ```
 riotplan_idea_create({
-  code: "feature-name",
-  description: "Initial concept description"
+  code: "extracted-or-provided-code",
+  description: "extracted or provided description"
 })
 ```
 
-### 2. Explore Together
+### 3. Begin Exploration
+
+After creating the idea, immediately begin the exploration conversation. Don't wait for further prompting.
 
 Ask open-ended questions:
 - "What's driving this idea?"
@@ -35,6 +63,8 @@ Ask open-ended questions:
 - "What questions need answering?"
 - "Do you have any evidence (docs, diagrams, examples)?"
 
+### 4. Capture Responses in TWO Ways
+
 As the user responds, capture their thinking in TWO ways:
 
 **FIRST: Capture the full narrative (preserve the raw conversation)**
@@ -87,7 +117,7 @@ riotplan_idea_add_evidence({
 - Structured data makes information actionable
 - Timeline shows both the conversation and the decisions
 
-### 3. Decide Next Steps
+### 5. Decide Next Steps
 
 After exploration, ask:
 - "Does this feel worth pursuing?"
@@ -115,20 +145,46 @@ Just leave it in idea stage. Can return later.
 2. **Cheap Thinking**: Capture thoughts without formality
 3. **Evidence Gathering**: Collect supporting materials
 4. **Question-Driven**: Surface unknowns early
+5. **Smart Extraction**: Use information the user already provided; don't make them repeat themselves
+
+## Example Conversations
+
+### Example 1: User Provides Everything Upfront
+
+**User**: `/riotplan/explore_idea real-time-notifications Add push notifications for important updates`
+
+**AI**: *Extracts code="real-time-notifications", description="Add push notifications for important updates"*
+*Calls riotplan_idea_create immediately*
+
+**AI**: "Let's explore this idea. What's driving the need for push notifications? What constraints should we consider?"
 
-## Example Conversation
+### Example 2: User Provides Partial Info
 
-**User**: "I'm thinking about adding real-time notifications"
+**User**: `/riotplan/explore_idea I want to add notifications`
 
-**AI**: "Let's explore that idea. I'll create a lightweight idea to capture your thinking."
+**AI**: *Extracts description="I want to add notifications", derives code="add-notifications"*
+*Calls riotplan_idea_create immediately*
 
-*Creates idea*
+**AI**: "Let's explore this notification idea. What's driving this? What problem does it solve?"
 
-**AI**: "What's driving this? What problem does it solve?"
+### Example 3: User Provides No Info
+
+**User**: `/riotplan/explore_idea`
+
+**AI**: "What idea would you like to explore? Give me a short name and brief description."
+
+**User**: "I'm thinking about real-time notifications for users"
+
+**AI**: *Extracts code="real-time-notifications", description="real-time notifications for users"*
+*Calls riotplan_idea_create*
+
+**AI**: "Great! Let's explore this. What's driving the need for real-time notifications?"
+
+### Example 4: Rich Exploration with Narrative
 
 **User**: "Users miss important updates. They have to refresh constantly. It's frustrating for them and we're getting complaints. I think we need some kind of push notification system but I'm not sure if it should be in-app only or also email."
 
-*Captures narrative first:*
+**AI**: *Captures full narrative first:*
 ```
 riotplan_idea_add_narrative({
   content: "Users miss important updates. They have to refresh constantly. It's frustrating for them and we're getting complaints. I think we need some kind of push notification system but I'm not sure if it should be in-app only or also email.",
@@ -144,41 +200,27 @@ riotplan_idea_add_note({
 })
 ```
 
-**AI**: "What constraints should we consider?"
+**AI**: "Good context. What constraints should we consider?"
 
 **User**: "Must work on mobile. Can't require WebSockets everywhere. Also need to keep costs reasonable."
 
-*Captures narrative and extracts constraints*
-
-**AI**: "Good constraints. Any questions we need to answer?"
-
-**User**: "How do we handle offline users? What's the latency requirement?"
-
-*Adds questions*
-
-**AI**: "Do you have any examples or diagrams of how this might work?"
-
-**User**: "Here's a diagram from a similar system" [attaches image]
-
-*Adds evidence*
-
-**AI**: "This is taking shape. Ready to explore different approaches for implementation?"
-
-**User**: "Yes, let's look at options"
-
-*Transitions to shaping*
+**AI**: *Captures narrative and extracts constraints*
 
 ## Anti-Patterns
 
+❌ Don't ask for information the user already provided
 ❌ Don't immediately jump to solutions
 ❌ Don't create detailed plans yet
 ❌ Don't pressure for commitment
 ❌ Don't skip evidence gathering
+❌ Don't stop after creating the idea—begin exploration immediately
 
+✅ Do extract information from the user's message
 ✅ Do ask open questions
 ✅ Do capture all thinking
 ✅ Do surface constraints early
 ✅ Do gather supporting materials
+✅ Do start the conversation immediately after creating the idea
 
 ## Transition Criteria
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riotprompt/riotplan",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Framework for long-lived, stateful AI workflows (plans)",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,19 +51,19 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
-    "@theunwalked/cardigantime": "^0.0.23",
+    "@utilarium/cardigantime": "^0.0.24",
     "@types/inquirer": "^9.0.9",
     "chalk": "^5.4.1",
     "commander": "^14.0.2",
     "inquirer": "^13.2.1",
     "js-yaml": "^4.1.1",
     "marked": "^17.0.1",
-    "zod": "^4.1.12"
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@riotprompt/agentic": "^1.0.2",
+    "@riotprompt/agentic": "^1.0.4",
     "@riotprompt/execution": "^1.0.1",
-    "@riotprompt/riotprompt": "^1.0.4"
+    "@riotprompt/riotprompt": "^1.0.5"
   },
   "peerDependenciesMeta": {
     "@riotprompt/agentic": {