Learn

Learn — Topic Research & Learning Plan Generator

Overview

Guide the user from a vague "I want to learn X" into a structured, researched learning plan with curated resources. Ask clarifying questions, research the topic, and produce a module-by-module plan saved to disk.

File Storage Rules — EXACT PATHS (no deviation)

The learning system uses three separate directories. Each directory has ONE purpose:

CORRECT — saving a learning plan: ~/.claude/learning/plans/dns-2026-03-29.json WRONG — saving a learning plan: ~/.claude/learning/progress/dns.json

CORRECT — saving quiz progress: ~/.claude/learning/progress/dns.json WRONG — saving quiz progress: ~/.claude/learning/plans/dns-2026-03-29.json

CORRECT — saving any learning data: ~/.claude/learning/plans/dns-2026-03-29.json WRONG — saving to project directory: ./learning/plans/dns-2026-03-29.json

Always use the ABSOLUTE path ~/.claude/learning/ — never a relative path like ./learning/. Never add quiz fields (quizzes, weakAreas, strongAreas, spacedRepetition, overallScore) to plan files. Never add plan fields (modules, resources, goal, depth, timeCommitment) to progress files. Verify the path is correct BEFORE writing.

Process

Check for Existing Topic

Before starting a new plan, check if this topic already exists.

Read ~/.claude/learning/index.json and look for a matching topic (fuzzy match same as quiz skill: "k8s" → "kubernetes").

If the topic exists:

1. Read the plan file and progress file
2. Show a brief status:

── Resuming: [Topic] ────────────────────
Level: [level] | Modules: [completed]/[total] | Score: [score]%
Last activity: [date]
──────────────────────────────────────────

3. Determine the next action:
   • If no quizzes taken on any module: "Ready to start learning? I'll teach you Module 1: [title]"
   • If some modules quizzed: "You left off at Module [N]: [title]. Continue?"
   • If all modules quizzed with score >80%: "You've completed this topic! Want to retake quizzes on weak areas, or adjust the plan?"
4. If user wants to continue, teach the next incomplete module interactively (see Phase 5: Teach)
5. If user wants to adjust, load the existing plan and let them modify it

If the topic is new: proceed to Phase 0 (profile) and Phase 1 (scope).

Phase 0: Load or Create Learner Profile

Read ~/.claude/learning/profile.json if it exists.

If profile exists:

• Greet the user by acknowledging their learning style and background
• Skip questions about learning style and background in Phase 1 — you already know
• Still ask topic-specific questions (level, goal, focus areas)

If no profile exists (first time):

• During Phase 1, include the learning style question (see Phase 1 examples)
• After Phase 1, save the profile as JSON to ~/.claude/learning/profile.json (create directory if needed):
  • learningStyle: the user's choice (e.g., "hands-on")
  • background: extracted from level + goal answers
  • createdTopics: array with the current topic slug

If profile exists and this is a new topic:

• Append the topic slug to createdTopics array

Phase 1: Clarify Scope

ALWAYS use the AskUserQuestion tool when asking the user questions, in any context. If you have too many questions for the tool, split them up into multiple calls.

Ask 2-5 clarifying questions, skipping any already answered by the user's initial message.

Rules:

• Ask ONE question per message — wait for the answer before asking the next
• Use multiple choice with clear options and descriptions for every question
• Only one question per message — never combine questions
• Ask at least 2 (level + goal) — cap at 5
• If a learner profile exists, skip the learning style question

Question 1 — Current level:

Ask "What's your current experience with [topic]?" with options:

• No experience — Complete beginner, starting from scratch
• Some basics — Familiar with core ideas but not hands-on
• Intermediate — Working knowledge, want to go deeper
• Advanced — Strong foundation, want expert-level depth

Question 2 — Learning goal:

Ask "What do you want to be able to do after learning [topic]?" with 3 topic-specific goal options. Each option needs a label and a description.

Question 3 — Depth (optional):

Ask "How deep do you want to go?" with options:

• High-level overview — Understand the big picture and key concepts
• Working knowledge — Enough to use it confidently day-to-day
• Deep expertise — Thorough understanding including edge cases

Question 4 — Focus areas (optional):

Ask which areas to focus on. Allow selecting multiple from 2-4 topic-specific subtopics, each with a label and description.

Question 5 — Time commitment (optional):

Ask "How much time do you want to invest?" with options:

• A few hours — Quick introduction to the basics
• A weekend — Solid foundation with practice
• A week — In-depth study with projects
• Ongoing study — Long-term learning commitment

If no learner profile exists, also ask "How do you prefer to learn?" with options:

• Reading docs & articles — Text-based, self-paced learning
• Watching videos — Visual explanations and walkthroughs
• Hands-on projects — Learn by building and experimenting
• Theory first — Understand principles, then apply them

Phase 1.5: Diagnostic Assessment (non-beginners only)

Skip this phase if the user said they have "no experience" or are a "complete beginner."

For users with some background, generate a 5-question diagnostic quiz to calibrate their actual level. This prevents wasting time on material they already know.

How to run the diagnostic:

Generate 5 multiple choice questions testing foundational concepts at increasing difficulty. Ask ONE question per message — wait for the answer before the next.

• Questions 1-2: Basic terminology and concepts (should be easy for anyone with "some basics")
• Questions 3-4: Intermediate understanding (application of concepts)
• Question 5: Advanced concept (only experts get this right)

Each question should have 4 options with descriptions. Label them "Diagnostic Q1/5" through "Q5/5".

After the diagnostic, note which level the user actually tested at:

• 0-1 correct: Suggest starting from beginner despite their self-assessment
• 2-3 correct: Confirmed intermediate — can skip introductory modules
• 4-5 correct: Confirmed advanced — compress fundamentals, focus on depth

Store the diagnostic results in the plan JSON by adding a diagnostic field:

{
  "diagnostic": {
    "taken": true,
    "score": 3,
    "total": 5,
    "calibratedLevel": "intermediate",
    "skipModules": []
  }
}

Use these results in Phase 3 (Generate Learning Plan) to mark introductory modules as "skippable" or compress them into a quick review.

Phase 2: Research

Perform 3-5 web searches with varied queries:

1. "[topic] learning roadmap [year]" — find structured learning paths
2. "best [topic] tutorial for [level]" — find recommended resources
3. "[topic] official documentation" — find authoritative sources
4. "[topic] [specific subtopic] guide" — drill into focus areas
5. "[topic] common mistakes beginners" — anticipate pitfalls

For each search:

• Use the WebSearch tool
• Fetch the top 2-3 results with WebFetch
• Extract: key concepts, recommended order, good resources, common learning paths

Synthesize the research into a coherent structure. Don't just list links — understand what the community recommends and why.