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:

| Directory | Stores | Allowed fields |
|---|---|---|
| `~/.claude/learning/plans/` | Learning plans ONLY | topic, slug, created, level, goal, depth, timeCommitment, modules, totalEstimatedTime, diagnostic |
| `~/.claude/learning/progress/` | Quiz progress ONLY | topic, quizzes, weakAreas, strongAreas, overallScore, spacedRepetition |
| `~/.claude/learning/` (root) | index.json + profile.json ONLY | topics (index), learningStyle/background/createdTopics (profile) |

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-que