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.