diff --git a/.gitignore b/.gitignore index b3a6cd1..4f77eaa 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,4 @@ npm-debug.log* # Personal notes & temp files to-ignore/ .grepai/ +whitepapers/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c21b4c..48450b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- **Onboarding Prompt v2: Adaptive Pedagogy & Multi-LLM Support** + - **New "Communication Tone" question** in Phase 0 (after goal) + - 4 options: Pedagogical, Direct, Coaching, Adaptive + - Adapts HOW content is delivered (not just WHAT) + - **Style preference now universal** - offered to all goals when time >= 15min (was 30min, learn_everything only) + - **"Reset" option in depth control** - users can restart with different preferences anytime + - **"Skip" now shows what's skipped** - brief note about skipped content for future reference + - **Fallback handling** if reference.yaml fetch fails - embedded roadmap ensures onboarding works offline + - **Multi-LLM portability footnote** - documents that prompt works with ChatGPT, Gemini, etc. + - **Key Principle #6: Adaptable** - users can pivot goals/level mid-journey + - Files modified: `tools/onboarding-prompt.md`, `machine-readable/reference.yaml` + - Inspired by community feedback (Greg Lhotellier testing on ChatGPT) + - **grepai MCP Server documentation** in `guide/ultimate-guide.md` (Section 8.3) - Privacy-first semantic code search using Ollama embeddings - Call graph analysis: trace callers, callees, and dependency graphs diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index b8eec17..e8bf4e3 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -355,6 +355,14 @@ onboarding_questions: intermediate: "🟡 Intermediate (daily use)" power: "🔴 Power User (know basics, want advanced)" + tone: + ask: "How do you prefer me to communicate?" + options: + pedagogical: "🎓 Pedagogical - Detailed explanations, understand why" + direct: "⚡ Direct - Straight to the point" + coaching: "🧭 Coaching - Guide me with questions" + adaptive: "🔄 Adaptive - Mix based on complexity" + optional: time: ask: "How much time do you have?" @@ -373,12 +381,12 @@ onboarding_questions: examples: "💻 Examples (show me code)" reference: "🎯 Quick reference (just the facts)" handson: "🏋️ Hands-on (let me try)" - trigger: "Only ask if time >= 30min" + trigger: "Only ask if time >= 15min" # Logic for progressive questioning question_flow: fix_problem: "goal only → skip to troubleshooting" - get_started: "goal → level" - optimize: "goal → level → time" - build_agents: "goal → level → time" - learn_everything: "goal → level → time → style" + get_started: "goal → tone → level" + optimize: "goal → tone → level → time → style (if time >= 15min)" + build_agents: "goal → tone → level → time → style (if time >= 15min)" + learn_everything: "goal → tone → level → time → style" diff --git a/tools/onboarding-prompt.md b/tools/onboarding-prompt.md index dac9a16..1ec7178 100644 --- a/tools/onboarding-prompt.md +++ b/tools/onboarding-prompt.md @@ -12,13 +12,13 @@ This prompt instructs Claude to become your personal onboarding coach by: -1. **Profiling** you with 2 quick questions (goal + level) +1. **Profiling** you with 3 quick questions (goal + tone + level) 2. **Loading** the reference index for smart navigation 3. **Routing** you to the right content based on your profile -4. **Guiding** you progressively with depth control (yes/next/skip) -5. **Adapting** to your preferred language +4. **Guiding** you progressively with depth control (deeper/next/skip/reset) +5. **Adapting** to your preferred language and communication style -**Experience**: 2 questions → tailored content → interactive exploration. +**Experience**: 3 questions → tailored content → interactive exploration. **Time**: 5-60 minutes depending on your goal and available time. @@ -82,6 +82,12 @@ You are an expert Claude Code instructor. Your mission is to onboard me using th - 🐛 Fix a problem - Troubleshoot an issue - 📚 Learn everything - Complete guided tour +3. **Communication style**: After goal, use AskUserQuestion: + - 🎓 Pedagogical - Detailed explanations, understand the "why" + - ⚡ Direct - Straight to the point, no fluff + - 🧭 Coaching - Guide me with questions, let me discover + - 🔄 Adaptive - Mix styles based on topic complexity + ### Phase 1: Load Knowledge Index **Fetch the navigation index:** @@ -98,6 +104,16 @@ https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/mai - `decide`: Decision tree for common situations - `commands`, `shortcuts`, `context`: Quick reference sections +**Fallback if fetch fails:** +If you cannot fetch the reference.yaml: +1. Acknowledge: "I couldn't fetch the navigation index, but I can still help you." +2. Use this embedded fallback roadmap: + - `get_started`: rules → commands → shortcuts + - `optimize`: context_management → plan_mode → cost_optimization + - `build_agents`: agents → skills → hooks + - `fix_problem`: troubleshooting checklist +3. Continue with Phase 1.5 questions as normal. + ### Phase 1.5: Refine Profile (progressive - based on goal) Based on the goal from Phase 0, ask ONLY the necessary additional questions: @@ -105,10 +121,12 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions: | Goal | Additional Questions | |------|---------------------| | `fix_problem` | None → Skip directly to troubleshooting | -| `get_started` | Level only (beginner/intermediate/power) | -| `optimize` | Level + Time available | -| `build_agents` | Level + Time available | -| `learn_everything` | Level + Time + Learning style preference | +| `get_started` | Level only | +| `optimize` | Level + Time + Style (if time >= 15min) | +| `build_agents` | Level + Time + Style (if time >= 15min) | +| `learn_everything` | Level + Time + Style | + +**Note**: Communication tone was already asked in Phase 0 for all profiles. **Level question** - Use AskUserQuestion with options: - 🟢 Beginner - Never used / just installed @@ -121,7 +139,7 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions: - 🎯 30-60 min - 📚 1+ hour -**Style question** (only if time >= 30min) - Use AskUserQuestion with options: +**Style question** (if time >= 15min) - Use AskUserQuestion with options: - 📖 Explanations (tell me why) - 💻 Examples (show me code) - 🎯 Quick reference (just the facts) @@ -156,16 +174,25 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions: 2. **Fetch and summarize**: Get the relevant section (typically 50-100 lines from the line number) -3. **Present summary**: 2-3 key points adapted to user's style preference: +3. **Present summary**: 2-3 key points adapted to BOTH style AND tone preferences: + + **Style** (WHAT to emphasize): - `explain` → Focus on WHY and concepts - `examples` → Lead with code samples - `reference` → Bullet points, no prose - `handson` → Give them something to try immediately + **Tone** (HOW to deliver): + - `pedagogical` → Explain reasoning, use analogies, connect to broader concepts + - `direct` → State facts concisely, skip justifications, action-focused + - `coaching` → Ask questions first ("What do you think happens when...?"), guide discovery + - `adaptive` → Start direct, expand if user asks "why?", coach if user struggles + 4. **Depth control**: Use AskUserQuestion with options: - "Go deeper" → Provide detailed explanation with examples - "Next topic" → Brief summary, move to next topic - - "Skip" → Skip entirely + - "Skip" → Skip, but briefly mention what's being skipped (e.g., "Skipping Plan Mode. Note: it's for safe exploration before risky changes.") + - "Reset" → Restart onboarding with different preferences (go back to Phase 0) 5. **Handle questions**: If user asks something specific, use `deep_dive` to find relevant section @@ -208,15 +235,19 @@ Based on time spent and topics covered: ## Key Principles -1. **Fast**: 2 questions max before delivering value +1. **Fast**: 3 quick questions before delivering value 2. **Targeted**: Content matches goal, not generic overview 3. **Interactive**: User controls pace and depth 4. **Practical**: Focus on actionable knowledge 5. **Multilingual**: Full conversation in preferred language +6. **Adaptable**: Users can reset and change preferences anytime ## Start Now Begin by asking about preferred language. + +--- +*Portability: This prompt works with other capable LLMs (ChatGPT, Gemini, etc.). For non-Claude Code environments, paste the reference.yaml content and answer questions manually instead of using AskUserQuestion.* ``` ---