leo-claude-mktplace/plugins/clarity-assist/docs/ND-SUPPORT.md

Neurodivergent Support in clarity-assist

This document describes how clarity-assist is designed to support users with neurodivergent traits, including ADHD, autism, anxiety, and other conditions that affect executive function, sensory processing, or cognitive style.

Overview

Purpose

clarity-assist exists to help all users transform vague or incomplete requests into clear, actionable specifications. For neurodivergent users specifically, it addresses common challenges:

• Executive function difficulties - Breaking down complex tasks, getting started, managing scope
• Working memory limitations - Keeping track of context across long conversations
• Decision fatigue - Facing too many open-ended choices
• Processing style differences - Preferring structured, predictable interactions
• Anxiety around uncertainty - Needing clear expectations and explicit confirmation

Philosophy

Our design philosophy centers on three principles:

1. Reduce cognitive load - Never force the user to hold too much in their head at once
2. Provide structure - Use consistent, predictable patterns for all interactions
3. Respect different communication styles - Accommodate rather than assume one "right" way to think

Features for ND Users

1. Reduced Cognitive Load

Prompt Simplification

• The 4-D methodology (Deconstruct, Diagnose, Develop, Deliver) breaks down complex requests into manageable phases
• Users never need to specify everything upfront - clarification happens incrementally

Task Breakdown

• Large requests are decomposed into explicit components
• Dependencies and relationships are surfaced rather than left implicit
• Scope boundaries are clearly defined (in-scope vs. out-of-scope)

2. Structured Output

Consistent Formatting

• Every clarification session produces the same structured specification:
  • Summary (1-2 sentences)
  • Scope (In/Out)
  • Requirements table (numbered, prioritized)
  • Assumptions list
• This predictability reduces the mental effort of parsing responses

Predictable Patterns

• Questions always follow the same format
• Progress summaries appear at regular intervals
• Escalation (simple to complex) is always offered, never forced

Bulleted Lists Over Prose

• Requirements are presented as scannable lists, not paragraphs
• Options are numbered for easy reference
• Key information is highlighted with bold labels

3. Customizable Verbosity

Detail Levels

• /clarify - Full methodology for complex requests (more thorough, more questions)
• /quick-clarify - Rapid mode for simple disambiguation (fewer questions, faster)

User Control

• Users can always say "that's enough detail" to end questioning early
• The plugin offers to break sessions into smaller parts
• "Good enough for now" is explicitly validated as an acceptable outcome

4. Vagueness Detection

The UserPromptSubmit hook automatically detects prompts that might benefit from clarification and gently suggests using /clarify.

Detection Signals

• Short prompts (< 10 words) without specific technical terms
• Vague action phrases: "help me", "fix this", "make it better"
• Ambiguous scope words: "somehow", "something", "stuff", "etc."
• Open questions without context

Non-Blocking Approach

• The hook never prevents you from proceeding
• It provides a suggestion with a vagueness score (percentage)
• You can disable auto-suggestions entirely via environment variable

5. Focus Aids

Task Prioritization

• Requirements are tagged as Must/Should/Could/Won't (MoSCoW)
• Critical items are separated from nice-to-haves
• Scope creep is explicitly called out and deferred

Context Switching Warnings

• When questions touch multiple areas, the plugin acknowledges the complexity
• Offers to focus on one aspect at a time
• Summarizes frequently to rebuild context after interruptions

How It Works

The UserPromptSubmit Hook

When you submit a prompt, the vagueness detection hook (hooks/vagueness-check.sh) runs automatically:

User submits prompt
       |
       v
Hook reads prompt from stdin
       |
       v
Skip if: empty, starts with /, or contains file paths
       |
       v
Calculate vagueness score (0.0 - 1.0)
  - Short prompts: +0.3
  - Vague action phrases: +0.2
  - Ambiguous scope words: +0.15
  - Missing technical specifics: +0.2
  - Short questions without context: +0.15
       |
       v
If score >= threshold (default 0.6):
  - Output gentle suggestion with [clarity-assist] prefix
  - Show vagueness percentage
       |
       v
Exit 0 (always non-blocking)

Example Hook Output

[clarity-assist] Your prompt could benefit from more clarity.
[clarity-assist] Consider running /clarity-assist to refine your request.
[clarity-assist] (Vagueness score: 65% - this is a suggestion, not a block)

The 4-D Methodology

Phase	What Happens	ND Benefit
Deconstruct	Break request into components	Shows the full picture without overwhelming
Diagnose	Identify gaps and conflicts	Surfaces hidden assumptions
Develop	Ask structured questions	Option-based, chunked, contextual
Deliver	Produce specification	Consistent, scannable format

Usage Examples

Before: Vague Request

User: Make the app faster

This triggers vagueness detection because:

• Short (4 words)
• Vague action ("make")
• No specific technical context
• No measurable outcome

After: Clarified with /clarify

User: /clarify Make the app faster

Claude: 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]

User: 1

Claude: Initial page load - got it.

**What's an acceptable load time for you?**
1. Under 1 second (aggressive)
2. Under 2 seconds (standard)
3. Under 3 seconds (relaxed)
4. I don't have a specific target

[This helps me know whether to suggest quick wins or a major optimization effort]

After 2-3 more questions, the user receives:

## Clarified Request

### Summary
Optimize initial page load time to under 2 seconds by addressing bundle size and initial render blocking resources.

### Scope
**In Scope:**
- Bundle analysis and splitting
- Lazy loading non-critical components
- Image optimization
- CSS/JS minification check

**Out of Scope:**
- Backend API optimization
- Database query performance
- CDN setup

### Requirements
| # | Requirement | Priority | Notes |
|---|-------------|----------|-------|
| 1 | Page loads in < 2s on 4G | Must | Measured via Lighthouse |
| 2 | Largest contentful paint < 1.5s | Should | Core Web Vital |
| 3 | No layout shift after load | Should | CLS < 0.1 |

### Assumptions
- Current load time is > 3 seconds (based on "too long" description)
- Target browsers: modern evergreen (Chrome, Firefox, Safari)
- Build tooling already configured (webpack/vite)

Common Patterns Detected

Pattern	Example	What It Triggers
Missing context	"Fix the bug"	"Which bug? In which file or feature?"
Ambiguous scope	"Update the user stuff"	"What specifically needs updating?"
Unclear goals	"Make it better"	"Better in what way? Faster? Cleaner? More features?"
Implicit knowledge	"Do it like last time"	"I don't have context from previous sessions"
Conflicting requests	"Keep it simple but add everything"	"Which matters more: simplicity or completeness?"

Quick-Clarify Example

For simpler requests that just need minor disambiguation:

User: /quick-clarify Add a delete button to the user list

Claude: 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]

User: 1

Claude: Got it. I'll implement a delete button with confirmation dialog. Starting now.

Configuration Options

Environment Variables

Variable	Default	Description
CLARITY_ASSIST_AUTO_SUGGEST	true	Enable/disable automatic vagueness detection
CLARITY_ASSIST_VAGUENESS_THRESHOLD	0.6	Score threshold to trigger suggestion (0.0-1.0)

Disabling Auto-Suggestions

If you find the vagueness detection unhelpful, disable it in your shell profile or .env:

export CLARITY_ASSIST_AUTO_SUGGEST=false

Adjusting Sensitivity

To make detection more or less sensitive:

# More sensitive (suggests more often)
export CLARITY_ASSIST_VAGUENESS_THRESHOLD=0.4

# Less sensitive (only very vague prompts)
export CLARITY_ASSIST_VAGUENESS_THRESHOLD=0.8

Tips for ND Users

If You're Feeling Overwhelmed

• Use /quick-clarify instead of /clarify for faster interactions
• Say "let's focus on just one thing" to narrow scope
• Ask to "pause and summarize" at any point
• It's OK to say "I don't know" - the plugin will offer concrete alternatives

If You Have Executive Function Challenges

• Start with /clarify even for tasks you think are simple - it helps with planning
• The structured specification can serve as a checklist
• Use the scope boundaries to prevent scope creep

If You Prefer Detailed Structure

• The 4-D methodology provides a predictable framework
• All output follows consistent formatting
• Questions always offer numbered options

If You Have Anxiety About Getting It Right

• The plugin validates "good enough for now" as acceptable
• You can always revisit and change earlier answers
• Assumptions are explicitly listed - nothing is hidden

Accessibility Notes

• All output uses standard markdown that works with screen readers
• No time pressure - take as long as you need between responses
• Questions are designed to be answerable without deep context retrieval
• Visual patterns (bold, bullets, tables) create scannable structure

Feedback

If you have suggestions for improving neurodivergent support in clarity-assist, please open an issue at:

https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/issues

Include the label clarity-assist and describe:

• What challenge you faced
• What would have helped
• Any specific accommodations you'd like to see