how-to-talk-to-claude/PROJECT-CONTEXT.md

# "How to Talk to Claude" Project Context & Style Guide

## Project Overview

**Project Name:** How to Talk to Claude - A Comprehensive AI Collaboration Guide
**Current Location:** `/home/user/claude/how-to-ai-fresh/`
**Development Server:** `http://localhost:4321`
**Technology Stack:** Astro + Starlight with custom CSS, full component system, and site graph visualization

## Project Philosophy & Tone

### Core Voice & Style
- **Conversational and human-centered** - Written like explaining to a friend, not a manual
- **Experience-driven** - Focus on actual collaboration experiences, not just theory
- **Problem-focused** - Address real frustrations people have with AI
- **Inclusive and accessible** - Examples work across different tech backgrounds
- **Psychologically aware** - Acknowledge emotional aspects of learning AI collaboration
- **Authentic over generic** - Avoid typical "AI prompt" advice, focus on genuine partnership

### Content Approach
- **No jargon or technical complexity** unless absolutely necessary
- **Conversational examples** over formal templates
- **Personal anecdotes** and relatable analogies (AIM, texting, coffee shop interactions)
- **Honest about limitations** - acknowledge when things don't work
- **Practical and immediately useful** - every section provides actionable value

## Content Framework: Diataxis Implementation

We use the **Diataxis documentation framework** with four distinct content types:

### 🎓 Tutorials (Learning-oriented)
- **Purpose:** Step-by-step experiences that build confidence through practice
- **User mindset:** "I want to learn by doing"
- **Structure:** Guided experiences with actual conversations
- **Voice:** Encouraging, supportive, "let's try this together"

### 🔧 How-To Guides (Task-oriented)  
- **Purpose:** Solutions for specific problems users face right now
- **User mindset:** "I have a specific problem to solve"
- **Structure:** Problem → Solution → Examples → Links to related content
- **Voice:** Direct, practical, "here's how to fix this"

### 🧠 Explanations (Understanding-oriented)
- **Purpose:** Principles and psychology behind effective AI collaboration
- **User mindset:** "I want to understand why this works"
- **Structure:** Concept → Psychology → Examples → Implications
- **Voice:** Thoughtful, exploratory, "here's what's happening underneath"

### ⚡ Quick Reference (Information-oriented)
- **Purpose:** Conversation starters, troubleshooting, emergency fixes
- **User mindset:** "I need something fast"
- **Structure:** Scannable, organized by problem type, lots of templates
- **Voice:** Concise, organized, "bookmark this for when you need it"

## Component Usage Standards

**Visual Hierarchy:**
- Use `CardGrid` for feature organization and comparisons
- Use `Tabs` for before/after examples and alternatives  
- Use `Code` blocks for conversation examples with context
- Use `Asides` for tips, warnings, insights (4 types: note, tip, caution, danger)
- Use `Steps` for sequential processes and workflows
- Use `LinkCards` for enhanced navigation between guides
- Use `Badges` for visual indicators and status

**Content Enhancement Patterns:**
- Start sections with clear `Aside` callouts for key insights
- Use `Tabs` to show contrasts (good vs bad examples)
- Group related information in `Card` layouts
- End sections with `LinkCard` navigation to related content
- Use `Code` blocks for all conversation templates and examples

## Current Project Status

### ✅ Complete Sections (Beginners Guide)
- **3 Tutorials:** All enhanced with rich components
  - **Enhanced:** first-conversation.mdx (baseline)
  - **Enhanced:** messy-ideas.mdx (109→219 lines)
  - **Enhanced:** creative-project.mdx (118→231 lines)
- **13 How-To Guides:** MASSIVE ENHANCEMENT WAVE COMPLETED!
  - **Enhanced:** match-tone-style.mdx (177→293 lines) - "#1 transformation guide"
  - **Enhanced:** fix-misunderstandings.mdx (194→406 lines) - Biggest enhancement yet!
  - **Enhanced:** ask-when-uncertain.mdx - COMPLETED BY USER
  - **Enhanced:** fact-check.mdx - COMPLETED BY USER
  - **Enhanced:** brainstorm-comfortably.mdx - Template literal syntax fixes completed
  - **Enhanced:** avoid-walls-of-text.mdx (208→300 lines) - Length control mastery
  - **Enhanced:** get-useful-sources.mdx (244→304 lines) - Source-finding expertise  
  - **Enhanced:** get-helpful-feedback.mdx (263→333 lines) - Feedback collaboration
  - **Enhanced:** organize-information.mdx (~280→300 lines) - Information management
  - **Enhanced:** research-unfamiliar-topics.mdx (265→337 lines) - Learning methodology
  - **Enhanced:** maintain-voice-writing.mdx (~270→281 lines) - Writing collaboration
  - **⭐ ONLY 2 REMAINING:** personal-decisions.mdx, persona-prompts.mdx
- **4 Explanations:** Conversations vs commands (fixed), psychology, how Claude thinks, making AI work for life
- **1 Quick Reference:** Comprehensive conversation starters and troubleshooting

### 🚀 Framework Ready (Intermediate Guide)
- **Complete structure** with 27 content placeholders
- **5 Tutorial outlines** for advanced collaboration
- **16 How-To Guide outlines** organized into 4 categories
- **6 Explanation outlines** for sophisticated concepts
- **1 Advanced Reference outline** for power users

### 🎨 Technical Implementation
- **All 54 content files** converted to MDX format with component support
- **Complete Starlight integration** with custom CSS and navigation
- **✅ NEW: Starlight Obsidian Theme** - Modern, sleek design installed
- **Logo integration** and professional branding
- **All internal links** properly functioning with /beginners/ prefix
- **Two-tier navigation** system (Beginners/Intermediate)
- **✅ Starlight Site Graph Plugin** - Graph view and backlinks working perfectly

### 🐛 Known Issues
- **RESOLVED:** conversations-vs-commands.mdx quote escaping issues
- **RESOLVED:** brainstorm-comfortably.mdx template literal syntax issues
- **RESOLVED:** astro.config.mjs syntax errors

## Recent Accomplishments (Latest Sessions)

### ✅ MASSIVE ENHANCEMENT WAVE COMPLETED (12 FILES)
- **avoid-walls-of-text.mdx** enhanced (208→300 lines) - Response length control mastery
- **get-useful-sources.mdx** enhanced (244→304 lines) - Source-finding expertise with MDX syntax fixes
- **get-helpful-feedback.mdx** enhanced (263→333 lines) - Feedback collaboration strategies
- **organize-information.mdx** enhanced (~280→300 lines) - Information management systems 
- **research-unfamiliar-topics.mdx** enhanced (265→337 lines) - Zero-knowledge learning methodology
- **maintain-voice-writing.mdx** enhanced (~270→281 lines) - Authentic writing collaboration

### ✅ Technical Mastery Achieved
- **MDX Syntax Mastery** - All indentation and component syntax issues resolved
- **Component Integration** - All Starlight components working flawlessly across 12 files
- **Enhancement Pattern** - 100% success rate across all content types and complexity levels
- **Template Literal Fixes** - Proper {`template`} syntax for complex quotes mastered

### ✅ Navigation & Structure Improvements
- **Duplication Cleanup** - Removed redundant /beginners/start/introduction/ 
- **Streamlined Navigation** - Clear entry point to first-conversation tutorial
- **Modern LinkCard Navigation** - All enhanced files use professional LinkCard grids
- **Obsidian Theme Installation** - Modern design upgrade completed

## Proven Enhancement Pattern Established

### **Visual Components That Work:**
- **Opening Asides** for key insights, tips, and warnings (especially "Game-Changer" type callouts)
- **CardGrid** for organizing multiple concepts and scenarios
- **Tabs** for showing different approaches, before/after examples, or alternatives
- **Steps** for sequential processes and tutorials
- **Code blocks** with titles for conversation examples (users love copy buttons!)
- **LinkCards** for enhanced navigation between related content

### **Content Enhancement Strategy:**
1. **Opening Hook** - Aside with the key insight or "why this matters"
2. **Problem Organization** - CardGrid for common scenarios users face
3. **Solution Framework** - Multiple sections using rich components appropriately
4. **Interactive Examples** - Tabs and Code blocks for practical application
5. **Navigation Enhancement** - LinkCards connecting to related content

## Git Commit History
- `5da77a3` - Initial complete conversion (11,697 lines)
- `0d6fea5` - Homepage title fix
- `fab2254` - Major restructure into two guides  
- `2925a43` - Logo branding enhancement
- `428a3a4` - Complete Intermediate Guide outline (27 placeholders)
- `ad62547` - Enable Starlight components (54 files converted to MDX)
- `91225f7` - Enhanced Introduction & Ask When Uncertain pages
- `97de83f` - Transformed Quick Reference (+374 lines of rich components)
- `907364b` - Repair all internal links after /beginners/ restructure
- **[NEXT COMMIT NEEDED]** - Starlight site graph installation + enhanced tutorials/how-tos

## Next Priority Enhancement Candidates

### **🎯 FINAL 2 HOW-TO GUIDES (Complete the Collection!)**
1. **`/beginners/how-to/personal-decisions.mdx`** 
   - Decision-making with AI guidance
   - High user value - everyone needs help with personal choices
   - Perfect for CardGrid showing decision frameworks
   
2. **`/beginners/how-to/persona-prompts.mdx`**
   - Advanced technique for sophisticated users
   - Great candidate for Tabs showing different persona types
   - Final piece to complete beginners how-to collection

### **🚀 Intermediate Guide Development Ready:**
- **27 advanced content pieces** outlined and ready for development
- **5 Tutorial outlines** for sophisticated collaboration
- **16 How-To Guide outlines** organized into 4 categories  
- **6 Explanation outlines** for complex concepts
- **1 Advanced Reference outline** for power users

### **🎯 Quality Assurance & Launch Prep**
- Test all 12 enhanced pages across different devices/browsers
- Performance optimization and final technical polish
- Create comprehensive deployment checklist

### **Key Success Patterns**

#### Content Enhancement Strategy
1. **Start with most-visited content** (homepage, introduction, popular how-to guides)
2. **Use components strategically** - enhance scannability and engagement  
3. **Maintain conversational voice** while adding visual structure
4. **Create clear navigation paths** between related content
5. **Focus on user problems** rather than technical features

#### Component Integration Best Practices
- Import components at top of each enhanced file
- Use `CardGrid` for organizing multiple related concepts
- Use `Tabs` for showing different approaches or examples
- Use `Asides` for important callouts and tips
- End sections with `LinkCard` navigation to related content
- Always maintain the human, conversational tone within component structure
- **CRITICAL:** Avoid quote escaping issues in MDX - use simple quotes, not `\"`

This approach has successfully transformed basic markdown content into professional, interactive documentation while preserving the authentic, human-centered voice that makes this guide special. The foundation is rock-solid and the enhancement pattern is proven effective.