diff --git a/plugins/clarity-assist/commands/clarify.md b/plugins/clarity-assist/commands/clarify.md index 3069b36..7713088 100644 --- a/plugins/clarity-assist/commands/clarify.md +++ b/plugins/clarity-assist/commands/clarify.md @@ -2,16 +2,12 @@ ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 💬 CLARITY-ASSIST · Prompt Optimization │ -└──────────────────────────────────────────────────────────────────┘ ++----------------------------------------------------------------------+ +| CLARITY-ASSIST - Prompt Optimization | ++----------------------------------------------------------------------+ ``` -Then proceed with the workflow. - ## Purpose Transform vague, incomplete, or ambiguous requests into clear, actionable specifications using the 4-D methodology with neurodivergent-friendly accommodations. @@ -23,127 +19,22 @@ Transform vague, incomplete, or ambiguous requests into clear, actionable specif - Tasks requiring significant context gathering - When user seems uncertain about what they want -## 4-D Methodology +## Skills to Load -### Phase 1: Deconstruct +Load these skills before proceeding: -Break down the user's request into components: +- `skills/4d-methodology.md` - Core 4-phase process +- `skills/nd-accommodations.md` - ND-friendly question patterns +- `skills/clarification-techniques.md` - Anti-patterns and templates +- `skills/escalation-patterns.md` - When to adjust approach -1. **Extract explicit requirements** - What was directly stated -2. **Identify implicit assumptions** - What seems assumed but not stated -3. **Note ambiguities** - Points that could go multiple ways -4. **List dependencies** - External factors that might affect implementation +## Workflow -### Phase 2: Diagnose - -Analyze gaps and potential issues: - -1. **Missing information** - What do we need to know? -2. **Conflicting requirements** - Do any stated goals contradict? -3. **Scope boundaries** - What's in/out of scope? -4. **Technical constraints** - Platform, language, architecture limits - -### Phase 3: Develop - -Gather clarifications through structured questioning: - -**ND-Friendly Question Rules:** -- Present 2-4 concrete options (never open-ended alone) -- Include "Other" for custom responses -- Ask 1-2 questions at a time maximum -- Provide brief context for why you're asking -- Check for conflicts with previous answers - -**Example Format:** -``` -To help me understand the scope better: - -**How should errors be handled?** -1. Silent logging (user sees nothing) -2. Toast notifications (brief, dismissible) -3. Modal dialogs (requires user action) -4. Other - -[Context: This affects both UX and how much error-handling code we need] -``` - -### Phase 4: Deliver - -Produce the refined specification: - -```markdown -## Clarified Request - -### Summary -[1-2 sentence description of what will be built] - -### Scope -**In Scope:** -- [Item 1] -- [Item 2] - -**Out of Scope:** -- [Item 1] - -### Requirements - -| # | Requirement | Priority | Notes | -|---|-------------|----------|-------| -| 1 | ... | Must | ... | -| 2 | ... | Should | ... | - -### Assumptions -- [Assumption made based on conversation] - -### Open Questions -- [Any remaining ambiguities, if any] -``` - -## Conflict Detection - -Before each question, review previous answers for conflicts: - -``` -[Internal check] -Previous: User said "keep it simple" -Current question about: Adding configuration options -Potential conflict: More options = more complexity -→ Acknowledge: "Earlier you mentioned keeping it simple. With that in mind..." -``` - -## Escalation Protocol - -If the request is particularly messy or the user seems overwhelmed: - -1. Acknowledge the complexity -2. Offer to start with just ONE aspect -3. Build incrementally - -``` -"This touches a lot of areas. Rather than tackle everything at once, -let's start with [most critical piece]. Once that's clear, we can -add the other parts. Sound good?" -``` - -## Example Interaction - -**User:** Make the app faster - -**Clarify Response:** - -``` -Let me help clarify what kind of performance improvements you're looking for. - -**What type of slowness are you experiencing?** -1. Initial page load takes too long -2. Interactions feel sluggish (clicking, typing) -3. API calls are slow -4. All of the above -5. Other - -[I'm asking because each has very different solutions] -``` +1. **Deconstruct** - Break down request into components +2. **Diagnose** - Identify gaps and conflicts +3. **Develop** - Gather clarifications via structured questions +4. **Deliver** - Present refined specification ## Output Format -After gathering all necessary information, use the Deliver phase format to present the clarified specification for user confirmation. +Use the Deliver phase template from `skills/4d-methodology.md` to present the clarified specification for user confirmation. diff --git a/plugins/clarity-assist/commands/quick-clarify.md b/plugins/clarity-assist/commands/quick-clarify.md index 9f331b8..abfc31e 100644 --- a/plugins/clarity-assist/commands/quick-clarify.md +++ b/plugins/clarity-assist/commands/quick-clarify.md @@ -2,16 +2,12 @@ ## Visual Output -When executing this command, display the plugin header: - ``` -┌──────────────────────────────────────────────────────────────────┐ -│ 💬 CLARITY-ASSIST · Quick Clarify │ -└──────────────────────────────────────────────────────────────────┘ ++----------------------------------------------------------------------+ +| CLARITY-ASSIST - Quick Clarify | ++----------------------------------------------------------------------+ ``` -Then proceed with the workflow. - ## Purpose Single-pass clarification for requests that are mostly clear but need minor disambiguation. @@ -23,74 +19,27 @@ Single-pass clarification for requests that are mostly clear but need minor disa - Follow-up to an already-clarified request - Simple feature additions or bug fixes -## Process +## Skills to Load -### Step 1: Echo Understanding +- `skills/nd-accommodations.md` - ND-friendly question patterns +- `skills/clarification-techniques.md` - Echo and micro-summary techniques +- `skills/escalation-patterns.md` - When to escalate to full /clarify -Restate what you understood in a single sentence: +## Workflow -``` -"I understand you want [X] that does [Y]." -``` - -### Step 2: Quick Disambiguation - -If needed, ask ONE multiple-choice question: - -``` -**Just to confirm:** Should this [A] or [B]? -1. [Option A with brief description] -2. [Option B with brief description] -3. Both -4. Neither / Other approach -``` - -### Step 3: Proceed or Confirm - -If confident (>90%), proceed with a brief confirmation: - -``` -"Got it. I'll implement [X with chosen option]. Starting now." -``` - -If less confident, offer a micro-summary: - -``` -"Quick summary before I start: -- [Key point 1] -- [Key point 2] -- [Assumption made] - -Proceed? (Or clarify anything)" -``` - -## Example Interaction - -**User:** Add a delete button to the user list - -**Quick-Clarify Response:** - -``` -I'll add a delete button to each row in the user list. - -**Should deletion require confirmation?** -1. Yes - show confirmation dialog (Recommended) -2. No - delete immediately -3. Soft delete - mark as deleted but keep data - -[Asking because accidental deletions can be problematic] -``` - -## Escalation to Full /clarify - -If quick-clarify reveals complexity: - -``` -"This is more involved than it first appeared - there are -several decisions to make. Want me to switch to a more -thorough clarification process? (Just say 'yes' or 'clarify')" -``` +1. **Echo Understanding** - Restate in a single sentence +2. **Quick Disambiguation** - Ask ONE multiple-choice question if needed +3. **Proceed or Confirm** - Start work or offer micro-summary ## Output Format -For quick-clarify, no formal specification document is needed. Just proceed with the task after brief confirmation, documenting assumptions inline with the work. +No formal specification document needed. Proceed after brief confirmation, documenting assumptions inline with the work. + +## Escalation + +If complexity emerges, offer to switch to full `/clarify`: + +``` +"This is more involved than it first appeared. Want me to switch +to a more thorough clarification process?" +``` diff --git a/plugins/clarity-assist/skills/4d-methodology.md b/plugins/clarity-assist/skills/4d-methodology.md new file mode 100644 index 0000000..0b34bcc --- /dev/null +++ b/plugins/clarity-assist/skills/4d-methodology.md @@ -0,0 +1,76 @@ +# 4-D Methodology for Prompt Clarification + +The 4-D methodology transforms vague requests into actionable specifications. + +## Phase 1: Deconstruct + +Break down the user's request into components: + +1. **Extract explicit requirements** - What was directly stated +2. **Identify implicit assumptions** - What seems assumed but not stated +3. **Note ambiguities** - Points that could go multiple ways +4. **List dependencies** - External factors that might affect implementation + +## Phase 2: Diagnose + +Analyze gaps and potential issues: + +1. **Missing information** - What do we need to know? +2. **Conflicting requirements** - Do any stated goals contradict? +3. **Scope boundaries** - What is in/out of scope? +4. **Technical constraints** - Platform, language, architecture limits + +## Phase 3: Develop + +Gather clarifications through structured questioning: + +- Present 2-4 concrete options (never open-ended alone) +- Include "Other" for custom responses +- Ask 1-2 questions at a time maximum +- Provide brief context for why you are asking +- Check for conflicts with previous answers + +**Example Format:** +``` +To help me understand the scope better: + +**How should errors be handled?** +1. Silent logging (user sees nothing) +2. Toast notifications (brief, dismissible) +3. Modal dialogs (requires user action) +4. Other + +[Context: This affects both UX and how much error-handling code we need] +``` + +## Phase 4: Deliver + +Produce the refined specification: + +```markdown +## Clarified Request + +### Summary +[1-2 sentence description of what will be built] + +### Scope +**In Scope:** +- [Item 1] +- [Item 2] + +**Out of Scope:** +- [Item 1] + +### Requirements + +| # | Requirement | Priority | Notes | +|---|-------------|----------|-------| +| 1 | ... | Must | ... | +| 2 | ... | Should | ... | + +### Assumptions +- [Assumption made based on conversation] + +### Open Questions +- [Any remaining ambiguities, if any] +``` diff --git a/plugins/clarity-assist/skills/clarification-techniques.md b/plugins/clarity-assist/skills/clarification-techniques.md new file mode 100644 index 0000000..011a5e3 --- /dev/null +++ b/plugins/clarity-assist/skills/clarification-techniques.md @@ -0,0 +1,86 @@ +# Clarification Techniques + +Structured approaches for disambiguating user requests. + +## Anti-Patterns to Detect + +### Vague Requests +**Triggers:** "improve", "fix", "update", "change", "better", "faster", "cleaner" + +**Response:** Ask for specific metrics or outcomes + +### Scope Creep Signals +**Triggers:** "while you're at it", "also", "might as well", "and another thing" + +**Response:** Acknowledge, then isolate: "I'll note that for after the main task" + +### Assumption Gaps +**Triggers:** References to "the" thing (which thing?), "it" (what?), "there" (where?) + +**Response:** Echo back specific understanding + +### Conflicting Requirements +**Triggers:** "Simple but comprehensive", "Fast but thorough", "Minimal but complete" + +**Response:** Prioritize: "Which matters more: simplicity or completeness?" + +## Question Templates + +### For Unclear Purpose +``` +**What problem does this solve?** +1. [Specific problem A] +2. [Specific problem B] +3. Combination +4. Different problem: ____ +``` + +### For Missing Scope +``` +**What should this include?** +- [ ] Feature A +- [ ] Feature B +- [ ] Feature C +- [ ] Other: ____ +``` + +### For Ambiguous Behavior +``` +**When [trigger event], what should happen?** +1. [Behavior option A] +2. [Behavior option B] +3. Nothing (ignore) +4. Depends on: ____ +``` + +### For Technical Decisions +``` +**Implementation approach:** +1. [Approach A] - pros: X, cons: Y +2. [Approach B] - pros: X, cons: Y +3. Let me decide based on codebase +4. Need more info about: ____ +``` + +## Echo Understanding Technique + +Before diving into questions, restate understanding: + +``` +"I understand you want [X] that does [Y]." +``` + +This validates comprehension and gives user a chance to correct early. + +## Micro-Summary Technique + +For quick confirmations before proceeding: + +``` +"Quick summary before I start: +- [Key point 1] +- [Key point 2] +- [Assumption made] + +Proceed? (Or clarify anything)" +``` diff --git a/plugins/clarity-assist/skills/escalation-patterns.md b/plugins/clarity-assist/skills/escalation-patterns.md new file mode 100644 index 0000000..eba07ab --- /dev/null +++ b/plugins/clarity-assist/skills/escalation-patterns.md @@ -0,0 +1,57 @@ +# Escalation Patterns + +Guidelines for when to escalate between clarification modes. + +## Quick-Clarify to Full Clarify + +Escalate when quick-clarify reveals unexpected complexity: + +``` +"This is more involved than it first appeared - there are +several decisions to make. Want me to switch to a more +thorough clarification process? (Just say 'yes' or 'clarify')" +``` + +### Triggers for Escalation + +- Multiple ambiguities discovered during quick pass +- User's answer reveals hidden dependencies +- Scope expands beyond original understanding +- Technical constraints emerge that need discussion +- Conflicting requirements surface + +## Full Clarify to Incremental + +When user is overwhelmed by full 4-D process: + +``` +"This touches a lot of areas. Rather than tackle everything at once, +let's start with [most critical piece]. Once that's clear, we can +add the other parts. Sound good?" +``` + +### Signs of Overwhelm + +- Long pauses or hesitation +- "I don't know" responses +- Requesting breaks +- Contradicting earlier answers +- Expressing frustration + +## Choosing Initial Mode + +### Use /quick-clarify When + +- Request is fairly clear, just one or two ambiguities +- User is in a hurry +- Follow-up to an already-clarified request +- Simple feature additions or bug fixes +- Confidence is high (>90%) + +### Use /clarify When + +- Complex multi-step requests +- Requirements with multiple possible interpretations +- Tasks requiring significant context gathering +- User seems uncertain about what they want +- First time working on this feature/area diff --git a/plugins/clarity-assist/skills/nd-accommodations.md b/plugins/clarity-assist/skills/nd-accommodations.md new file mode 100644 index 0000000..594636e --- /dev/null +++ b/plugins/clarity-assist/skills/nd-accommodations.md @@ -0,0 +1,74 @@ +# Neurodivergent-Friendly Accommodations + +Guidelines for making clarification interactions accessible and comfortable for neurodivergent users. + +## Core Principles + +### Reduce Cognitive Load +- Maximum 4 options per question +- Always include "Other" escape hatch +- Provide examples, not just descriptions +- Use numbered lists for easy reference + +### Support Working Memory +- Summarize frequently +- Reference earlier decisions explicitly +- Do not assume user remembers context from many turns ago +- Echo back understanding before proceeding + +### Allow Processing Time +- Do not rapid-fire questions +- Validate answers before moving on +- Offer to revisit or change earlier answers +- One question block at a time + +### Manage Overwhelm +- Offer to break into smaller sessions +- Prioritize must-haves vs nice-to-haves +- Provide "good enough for now" options +- Acknowledge complexity openly + +## Question Formatting Rules + +**Always do:** +``` +**How should errors be handled?** +1. Silent logging (user sees nothing) +2. Toast notifications (brief, dismissible) +3. Modal dialogs (requires user action) +4. Other + +[Context: This affects both UX and error-handling complexity] +``` + +**Never do:** +``` +How do you want to handle errors? There are many approaches... +``` + +## Conflict Acknowledgment + +Before asking about something that might conflict with a previous answer: + +``` +[Internal check] +Previous: User said "keep it simple" +Current question about: Adding configuration options +Potential conflict: More options = more complexity +``` + +Then acknowledge: "Earlier you mentioned keeping it simple. With that in mind..." + +## Escalation for Overwhelm + +If the request is particularly complex or user seems overwhelmed: + +1. Acknowledge the complexity openly +2. Offer to start with just ONE aspect +3. Build incrementally + +``` +"This touches a lot of areas. Rather than tackle everything at once, +let's start with [most critical piece]. Once that's clear, we can +add the other parts. Sound good?" +```