Initial commit

2025-11-29 18:17:56 +08:00
commit 7290dfdcfb
10 changed files with 2646 additions and 0 deletions
--- a/references/mental-model-shift.md
+++ b/references/mental-model-shift.md
@@ -0,0 +1,389 @@
+# 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**:
+```markdown
+# 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**:
+```markdown
+# 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**:
+```markdown
+# Tool Name
+
+## Quick Start
+[Canonical approach]
+
+## Common Tasks
+[Using canonical approach]
+
+---
+
+## Alternative: Manual Approach
+
+For advanced users or special cases...
+```
+
+**Bad structure**:
+```markdown
+# 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):
+```markdown
+# 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](references/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)
+
+```markdown
+# 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)
+
+```markdown
+# 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:
+```bash
+safe-send.sh -s my-session -c "print('hello')"
+```
+
+Wait for output:
+```bash
+wait-for-text.sh -s my-session -p ">>>"
+```
+
+## Session Management
+
+List sessions:
+```bash
+list-sessions.sh
+```
+
+Clean up dead sessions:
+```bash
+cleanup-sessions.sh --dead
+```
+
+---
+
+## Alternative: Manual Socket Management
+
+For advanced scenarios requiring explicit socket control, see [manual-sockets.md](references/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:
+
+```markdown
+# 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.