feature-clarify

I will help you clarify ambiguities in a feature specification through structured question and answer sessions.

Usage:

• /feature-clarify <feature-id> - Start clarification for a spec
• /feature-clarify --auto <feature-id> - Auto-detect ambiguities
• /feature-clarify --show <feature-id> - Display existing clarifications

Instructions for me:

1. Load feature spec:

   • Read .mnemosyne/artifacts/specs/<feature-id>.md
   • If not found: "Error: Feature spec '' not found. Use /feature-specify first."
   • Parse YAML frontmatter to get spec memory_id

2. Check for existing clarifications:

   • Look for .mnemosyne/artifacts/clarifications/<feature-id>-clarifications.md
   • If exists: Load and display summary
   • Count pending vs. resolved questions

3. Auto-detect ambiguities (if --auto flag or no existing clarifications):

   Use DSPy ReviewerModule for semantic detection:

   cd src/orchestration/dspy_modules
   uv run python3 specflow_integration.py ../../.mnemosyne/artifacts/specs/<feature-id>.md --ambiguities-only --json
   

   Parse JSON output for ambiguities array:

   • location: Section where ambiguity was found
   • term: Ambiguous term or phrase
   • question: Suggested clarifying question
   • impact: Why this matters

   Fallback to pattern-based detection if DSPy unavailable:

   • Vague quantifiers: "fast", "slow", "easy", "hard", "secure", "scalable" without metrics
   • Missing acceptance criteria: Scenarios with <3 criteria
   • Underspecified requirements: Performance/security requirements without numbers
   • Unclear dependencies: References to external systems without details
   • Open questions: Explicit "?" or "TBD" markers

   Limit to top 3 most critical ambiguities (prioritize by location: P0/P1 scenarios first).

4. Interactive clarification (max 3 questions per session): For each ambiguity:

   a) Present question:

   Question Q00X: [Clear, specific question]
   
   Context: [Why this needs clarification]
   Found in: [Spec section]
   Impact: [What this blocks or affects]
   

   b) Gather answer:

   • Ask user for decision
   • Ask for rationale (why this choice?)
   • Ask which spec sections need updating
   • Validate answer is concrete and measurable

   c) Record clarification item:

   ## Q00X - Question
   
   [Question text]
   
   ### Context
   
   [Background and why this needs clarification]
   
   ### Decision
   
   [User's decision]
   
   **Rationale**: [Why this decision was made]
   
   **Spec Updates**:
   - [Section to update with new information]
   - [Another section to update]
   

5. Format clarifications document:

   ---
   type: clarification
   id: <feature-id>-clarifications
   name: <feature-name> Clarifications
   feature_id: <feature-id>
   version: 1.0.0
   created_at: <ISO 8601 timestamp>
   updated_at: <ISO 8601 timestamp>
   memory_id: <will be filled>
   references: [<spec-memory-id>]
   ---
   
   # Clarifications: <feature-name>
   
   **Status**: [X resolved, Y pending]
   
   ## Q001 - Question
   
   [Question text]
   
   ### Context
   
   [Context]
   
   ### Decision
   
   [Decision text or *Pending*]
   
   **Rationale**: [Rationale if decided]
   
   **Spec Updates**:
   - [Update 1]
   - [Update 2]
   
   ## Q002 - Question
   
   ...
   

6. Write clarifications file:

   • Create/update .mnemosyne/artifacts/clarifications/<feature-id>-clarifications.md
   • Ensure directory exists
   • If updating: Preserve existing questions, add new ones with incremented IDs

7. Store memory entry:

   • Use Mnemosyne CLI: mnemosyne remember
   • Arguments:
     • Content: "Clarifications for : Q001: , Q002: ..., X resolved, Y pending"
     • Namespace: project:<project-name>
     • Importance: 7 (clarifications are important)
     • Type: clarification
     • Tags: clarification,,ambiguities
     • Context: "Clarification questions and answers for "
   • Capture memory_id