8.6 KiB
Mental Model Shift
Guide to positioning skills as canonical approaches rather than optional features.
The Principle
When a skill provides a better way to do something, the documentation should reflect confidence in that approach. The feature isn't "new" or "recommended"—it IS the way things are done.
Mental model shift means:
- Feature becomes "the way" (not "a new way")
- Documentation reflects this confidence
- Alternative approaches are downgraded to "manual" or "advanced"
Language Patterns
✅ Canonical Language (Good)
Presents as THE way:
# Session Registry
Use the session registry for automatic session tracking.
## Quick Start
1. Create session: `create-session.sh -n my-session`
2. Send commands: `safe-send.sh -s my-session -c "command"`
Key phrases:
- "Use [tool] for [task]"
- "Standard workflow"
- "[Tool] handles [task]"
- Direct imperatives ("Create a session", "Send commands")
❌ Optional Language (Bad)
Presents as A way among many:
# Session Registry (NEW!)
The session registry is a new recommended feature you can use instead of manual socket management.
## Two Approaches
### Traditional: Manual Socket Management
[old way]
### New (Recommended): Session Registry
[new way]
You might want to consider using the session registry...
Red flag phrases:
- "New feature" or "NEW!"
- "Recommended" or "optional"
- "You can use" or "you might want to"
- "Instead of" or "alternative to"
- Side-by-side old vs new comparisons
- "Traditional" vs "modern"
Documentation Structure
Primary Workflow First
Place the canonical approach at the top as the default.
Good structure:
# Tool Name
## Quick Start
[Canonical approach]
## Common Tasks
[Using canonical approach]
---
## Alternative: Manual Approach
For advanced users or special cases...
Bad structure:
# Tool Name
## Choose Your Approach
### Option 1: Traditional Method (Still Supported)
[Old way]
### Option 2: New Registry Method (Recommended!)
[New way]
Downgrade Alternatives
When mentioning alternative approaches, position them as secondary.
Good (alternative is clearly secondary):
# Session Management
Create and manage sessions using the session registry.
## Creating Sessions
```bash
create-session.sh -n my-session --python
Manual Socket Management
For advanced use cases requiring explicit socket control, you can manage sockets manually. See manual-socket-management.md.
**Bad** (alternatives treated equally):
```markdown
# Session Management
## Approach 1: Registry (Recommended)
Use create-session.sh...
## Approach 2: Manual Sockets (Traditional)
Create sockets manually...
Both approaches are fully supported. Choose based on your preferences.
Evolution Example: tmux Skill
Phase 1: Feature Addition (❌ Wrong)
# tmux Skill
## New Feature: Session Registry!
We're excited to announce session registry support! This new recommended feature eliminates the need for manual socket management.
### Traditional Workflow (Still Supported)
1. Create socket: `tmux -S /tmp/my.sock new -d`
2. Send commands: `tmux -S /tmp/my.sock send-keys...`
### New Registry Workflow (Recommended!)
1. Create session: `create-session.sh -n my-session`
2. Send commands: `safe-send.sh -s my-session -c "command"`
Consider migrating to the registry for a better experience!
Problems:
- "New feature" announcement
- "Recommended" implies optionality
- Side-by-side comparison treats both as equal
- "Consider migrating" is hesitant
Phase 2: Mental Model Shift (✅ Right)
# tmux Skill
Use the session registry for automatic session tracking.
## Quick Start
Create a session:
```bash
create-session.sh -n my-session --python
Send commands:
safe-send.sh -s my-session -c "print('hello')"
Wait for output:
wait-for-text.sh -s my-session -p ">>>"
Session Management
List sessions:
list-sessions.sh
Clean up dead sessions:
cleanup-sessions.sh --dead
Alternative: Manual Socket Management
For advanced scenarios requiring explicit socket control, see manual-sockets.md.
**Improvements**:
- No "new" or "recommended" language
- Registry is THE approach
- Direct, confident instructions
- Manual approach relegated to "Alternative" section
- Documentation reflects "this is the way"
---
## Key Transformations
### From Feature to Standard
**Before**: "Session registry is a new feature"
**After**: "Use the session registry"
**Before**: "You can optionally use create-session.sh"
**After**: "Create sessions with create-session.sh"
**Before**: "The recommended approach is..."
**After**: [Just describe the approach as the default]
### From Optional to Canonical
**Before**: "Consider using -s flag for convenience"
**After**: "Use -s flag to specify the session"
**Before**: "The -s flag is a shorthand that may be helpful"
**After**: "The -s flag identifies the session by name"
### From Hedging to Direct
**Before**: "You might want to try the session registry"
**After**: "The session registry tracks sessions automatically"
**Before**: "It's recommended to clean up dead sessions regularly"
**After**: "Clean up dead sessions with cleanup-sessions.sh"
---
## Section Positioning
### Primary Content (80-90% of docs)
Focus on the canonical approach:
- Quick start
- Common workflows
- Standard examples
- Main documentation
### Alternative Content (10-20% of docs)
Relegated to end or separate files:
- "Alternative:" sections
- "Advanced:" sections
- "Manual:" approaches
- Legacy compatibility
---
## Migration Guidance
When transitioning from old to new approach:
### During Migration
Acknowledge the transition but frame it positively:
```markdown
# Tool Name
Use [new approach] for [task].
## Migrating from Manual Approach
If you're currently using manual [old approach]:
1. Replace [old command] with [new command]
2. Remove [old pattern]
3. Adopt [new pattern]
Migration is straightforward and improves [benefit].
After Migration Period
Remove migration notices, treat new approach as standard:
# Tool Name
Use [new approach] for [task].
## Alternative: Manual Approach
For advanced cases, see [manual.md](references/manual.md).
Verification Checklist
Mental model shift audit:
Language:
- No "new feature" or "NEW!" markers
- No "recommended" or "optional" hedging
- No side-by-side old vs new comparisons
- Direct, imperative instructions
- Confident tone throughout
Structure:
- Canonical approach presented first
- Primary content focuses on canonical approach
- Alternatives relegated to end or separate files
- Section titles don't imply choice ("Quick Start" not "Option 1")
Content:
- Examples use canonical approach
- Workflow descriptions assume canonical approach
- Troubleshooting assumes canonical approach
- Getting started uses canonical approach
Common Mistakes
Mistake 1: Hedging with "Recommended"
❌ "The recommended way is to use the registry" ✅ "Use the registry for session management"
Why: "Recommended" implies other approaches are equally valid.
Mistake 2: Feature Announcement Language
❌ "We're introducing session registry support" ✅ "Session registry provides automatic session tracking"
Why: "Introducing" or "new" frames it as optional addition.
Mistake 3: Choice Architecture
❌ "Choose between registry or manual approach based on your needs" ✅ "Use registry for session management. For advanced cases requiring manual control, see..."
Why: Presenting choice implies both are equal. Default should be clear.
Mistake 4: Qualification
❌ "Session registry can help you manage sessions more easily" ✅ "Session registry manages sessions automatically"
Why: "Can help" and "more easily" undermine confidence.
Mistake 5: Comparison to Old Way
❌ "Unlike manual socket management, session registry is automatic" ✅ "Session registry tracks sessions automatically"
Why: Mentioning the old way keeps it in the mental model.
Summary
Mental model shift means:
- Documentation reflects the feature as canonical
- Language is direct and confident
- Alternatives are clearly secondary
- No hedging or option-presenting
Key transformation:
- From: "New recommended feature you can optionally use"
- To: "This is how you do it"
Test: Read your documentation. If someone unfamiliar with the history would see multiple equally-presented approaches, the mental model shift is incomplete.