diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 030bb50..c6999e4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "kit", "description": "Community plugin & skills marketplace for Claude Code", - "version": "1.1.1", + "version": "1.2.0", "owner": { "name": "hamsurang", "email": "zlemzlem5656@naver.com" @@ -16,6 +16,11 @@ "name": "skill-review", "source": "./plugins/skill-review", "description": "Slash-command skill that reviews any SKILL.md against best practices and outputs a structured pass/fail report" + }, + { + "name": "personal-tutor", + "source": "./plugins/personal-tutor", + "description": "Adaptive technical tutoring skill that builds a persistent knowledge graph and learner profile across sessions" } ] } diff --git a/docs/plans/2026-03-01-personal-tutor-design.md b/docs/plans/2026-03-01-personal-tutor-design.md new file mode 100644 index 0000000..c22b8af --- /dev/null +++ b/docs/plans/2026-03-01-personal-tutor-design.md @@ -0,0 +1,207 @@ +# Personal Tutor Skill — Design Document + +**Date:** 2026-03-01 +**Status:** Approved + +--- + +## Overview + +A Claude Code skill that acts as a personalized technical tutor. The skill guides Claude through structured learning sessions, builds a persistent knowledge graph per topic, and accumulates a learner profile over time to adapt its teaching style — creating a "private tutor that knows you" experience. + +**Target scope:** Technical/programming topics (Rust, TypeScript, algorithms, system design, etc.) + +--- + +## Core Flow + +``` +호출 + ↓ +기존 knowledge-graph 확인 + ├─ 없음 → Phase 1: Socratic Diagnostic + └─ 있음 → Phase 2: Agenda Planning (프로파일 로드) + ↓ +Phase 2: Agenda Planning + ↓ +Phase 3: Teaching (Socratic + reference 인용) + ↓ +Phase 4: Verification Quiz + ↓ +Phase 5: Archive (관찰 확인 → 저장) +``` + +--- + +## Phase Design + +### Phase 1: Socratic Diagnostic (첫 세션만) + +- 5–7개 open-ended 질문으로 선행 지식 맵핑 +- 마지막에 레퍼런스 자료 확인: "참고하고 싶은 책/문서/강의 있어?" + - 있으면: `knowledge-graph.md` 상단에 저장, 레퍼런스 구조 참조해 커리큘럼 힌트로 활용 + - 없으면: Claude가 직접 커리큘럼 구성 +- 결과물: `knowledge-graph.md` 초기 생성 (모든 노드 `gap` 상태) + +### Phase 2: Agenda Planning + +세션 구성 원칙: +- **새 개념 1–2개**: `gap` 노드 중 prerequisites 충족된 것 우선 +- **복습 1개**: `partial` 노드 중 가장 오래된 것 +- returning 사용자: 이전 `partial` 노드 복습 퀴즈를 세션 첫머리에 배치 + +`learner-profile.md`의 패턴 참조해서 teaching 방식 사전 조정. + +### Phase 3: Teaching + +- Claude 주도 커리큘럼, 레퍼런스는 보조 역할 + - 설명 중 인용: "The Rust Book 4장에서 이 예제 봐봐" + - 심화 안내: "더 보고 싶으면 해당 챕터 참고" +- 루프: 설명 → 소크라테스 Q&A → 이해 확인 + - 막히면: 비유 / 코드 예시 / 역질문으로 다른 각도 재설명 +- `learner-profile`의 "잘 반응하는 방식" 참조해서 접근법 조정 + +### Phase 4: Verification Quiz + +3가지 포맷 중 컨텍스트에 맞게 선택: + +| 포맷 | 예시 | 측정하는 것 | +|------|------|------------| +| **Feynman** | "5살한테 설명해봐" | 내재화 수준 | +| **Apply** | "이 코드에서 뭐가 문제야?" | 적용 능력 | +| **Analyze** | "왜 이렇게 설계됐을까?" | 깊이 이해 | + +힌트 사용 여부 트래킹 (노드 승급 기준에 사용). + +### Phase 5: Archive + +세션 종료 시: +1. **노드 상태 업데이트** (승급 규칙 적용) +2. **세션 로그 저장** (`sessions/YYYY-MM-DD-session-N.md`) +3. **관찰 내용 제시 + 확인**: "오늘 이런 패턴 관찰했는데 저장할까?" + - 확인 후 `learner-profile.md` 업데이트 + +--- + +## Knowledge Graph + +### 노드 상태 머신 + +``` +gap + ↓ (이번 세션 퀴즈 통과, 힌트 무관) +partial + ↓ (다음 세션 복습 퀴즈 힌트 없이 통과) +understood +``` + +깊이는 **Bloom's Taxonomy** 기반: +`recall` → `apply` → `explain` + +### knowledge-graph.md 형식 + +```markdown +# {Topic} Knowledge Graph + +Reference: The Rust Programming Language (https://doc.rust-lang.org/book/) + +## Nodes + +### Ownership +- Status: partial +- Depth: apply +- Prerequisites: [] +- Quiz history: + - 2026-03-01: passed (hint used) → gap→partial + +### Borrowing +- Status: gap +- Depth: - +- Prerequisites: [Ownership] +- Quiz history: [] + +### Lifetimes +- Status: gap +- Depth: - +- Prerequisites: [Ownership, Borrowing] +- Quiz history: [] +``` + +**엣지 케이스:** +- `understood` 노드 + 마지막 세션 30일+ 경과 → 가벼운 복습 퀴즈 제안 +- 퀴즈 완전 실패 → 노드 강등 없음, `learner-profile`에 "재강화 필요" 메모 + +--- + +## Learner Profile + +### learner-profile.md 형식 + +```markdown +# Learner Profile + +## 학습 패턴 +- 잘 반응하는 방식: C++ 비유, 구체적 예시 먼저 +- 약한 방식: 추상적 형식 표기, 이론 설명 먼저 +- 학습 방향: 구체 → 추상 (bottom-up) + +## 관찰된 약점 패턴 +- 타입 시스템 계열은 평균 2세션 필요 +- 처음엔 "알겠다" 하지만 퀴즈에서 구멍 드러나는 경향 + +## 토픽별 이력 +- Rust: 3세션 (Ownership ✓, Borrowing ⚠, Lifetimes ✗) +``` + +업데이트 방식: 세션 종료 시 Claude가 관찰 내용 제시 → 사용자 확인 후 저장. + +--- + +## Storage Structure + +``` +~/.claude/learning/ + learner-profile.md + topics/ + rust/ + knowledge-graph.md + sessions/ + 2026-03-01-session-1.md + 2026-03-08-session-2.md + typescript/ + knowledge-graph.md + sessions/ +``` + +--- + +## Applied Learning Science + +| 원칙 | 적용 지점 | +|------|----------| +| **Bloom's Taxonomy** | 노드 깊이 트래킹 (recall/apply/explain) | +| **Zone of Proximal Development** | prerequisites 충족된 노드만 가르침 | +| **Retrieval Practice** | 퀴즈 없이 세션 종료 불가 | +| **Feynman Technique** | 퀴즈 포맷 중 하나 | +| **Spaced Repetition** | A+B 승급 기준 (이번 세션 + 다음 세션 검증) | +| **Interleaving** | 새 개념 + 기존 partial 복습 혼합 | +| **Cognitive Load Theory** | 세션당 새 개념 최대 1–2개 | + +--- + +## Skill Iron Rules + +1. **퀴즈 없이 세션 끝내지 말 것** — Retrieval Practice 필수 +2. **prerequisites 미충족 개념 가르치지 말 것** — ZPD 존중 +3. **아카이빙 없이 세션 종료하지 말 것** — 학습 이력 보존 +4. **learner-profile은 확인 없이 자동 저장하지 말 것** — 사용자 확인 필수 + +--- + +## Skill File Structure + +``` +~/.claude/skills/personal-tutor/ + SKILL.md + knowledge-graph-template.md +``` diff --git a/docs/plans/2026-03-01-personal-tutor-plan.md b/docs/plans/2026-03-01-personal-tutor-plan.md new file mode 100644 index 0000000..45e9623 --- /dev/null +++ b/docs/plans/2026-03-01-personal-tutor-plan.md @@ -0,0 +1,354 @@ +# Personal Tutor Skill — Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Create a `personal-tutor` Claude Code skill that acts as an adaptive technical tutor, building a persistent knowledge graph and learner profile across sessions. + +**Architecture:** A skill document (`SKILL.md`) that guides Claude through 5 phases: Socratic diagnostic, agenda planning, teaching, verification quiz, and archiving. State persists via markdown files in `~/.claude/learning/`. A supporting template file defines the knowledge graph format. + +**Tech Stack:** Markdown skill files, `~/.claude/skills/` directory (Claude Code personal skills) + +**Design Reference:** `docs/plans/2026-03-01-personal-tutor-design.md` + +--- + +## Task 1: Create Skill Directory Structure + +**Files:** +- Create: `~/.claude/skills/personal-tutor/` (directory) +- Create: `~/.claude/skills/personal-tutor/SKILL.md` +- Create: `~/.claude/skills/personal-tutor/knowledge-graph-template.md` + +**Step 1: Create the directory** + +```bash +mkdir -p ~/.claude/skills/personal-tutor +``` + +**Step 2: Verify it exists** + +```bash +ls ~/.claude/skills/ +``` + +Expected: `personal-tutor/` directory listed + +**Step 3: Commit** + +```bash +git add . # nothing to add yet — directories don't track until files exist +``` + +(Files added in subsequent tasks) + +--- + +## Task 2: Write `knowledge-graph-template.md` + +**Files:** +- Create: `~/.claude/skills/personal-tutor/knowledge-graph-template.md` + +**Step 1: Write the template** + +Content for `~/.claude/skills/personal-tutor/knowledge-graph-template.md`: + +```markdown +# {Topic} Knowledge Graph + +Reference: none + +## Nodes + +### {Concept Name} +- Status: gap +- Depth: - +- Prerequisites: [] +- Quiz history: [] +``` + +**Upgrade rules:** +- `gap → partial`: quiz passed this session (hint OK) +- `partial → understood`: quiz passed in a later session WITHOUT hints + +**Depth scale (Bloom's Taxonomy):** +- `recall` — can remember / repeat +- `apply` — can use in new context +- `explain` — can teach to someone else + +--- + +**Step 2: Verify file contents look correct** + +```bash +cat ~/.claude/skills/personal-tutor/knowledge-graph-template.md +``` + +--- + +## Task 3: Write Core `SKILL.md` + +**Files:** +- Create: `~/.claude/skills/personal-tutor/SKILL.md` + +**Step 1: Write SKILL.md** + +Content for `~/.claude/skills/personal-tutor/SKILL.md`: + +```markdown +--- +name: personal-tutor +description: Use when user wants to learn a technical topic, says "I want to learn X", "teach me X", or "let's study X". Also use when user resumes a previous learning session on a topic they've studied before. +--- + +# Personal Tutor + +## Session Start + +1. Extract topic name from user input (e.g., "Rust", "TypeScript generics") +2. Check `~/.claude/learning/topics/{topic}/knowledge-graph.md` + - **Exists** → load it + `~/.claude/learning/learner-profile.md` → jump to **Phase 2** + - **Not exists** → create `~/.claude/learning/topics/{topic}/` → start **Phase 1** + +## Phase 1: Socratic Diagnostic (first session only) + +Ask 5–7 open-ended questions to map existing knowledge. One question at a time. Examples: +- "Have you worked with manual memory management before? (C, C++, etc.)" +- "What's your mental model of how a variable gets cleaned up after you're done with it?" +- "Have you seen ownership errors before? What did they look like?" + +After mapping, ask once: **"Is there a reference you'd like me to draw from? (book, docs, course — optional)"** +- Yes → store in `knowledge-graph.md` header as `Reference: [title + URL]`; use for examples and citations only — Claude leads curriculum +- No → set `Reference: none` + +Create `knowledge-graph.md` using `knowledge-graph-template.md`. Seed nodes based on the topic's prerequisite tree. All nodes start as `gap`. + +## Phase 2: Agenda Planning + +Session composition (respect Cognitive Load Theory): +- **New concepts: 1–2** — `gap` nodes whose prerequisites are ALL ≥ `partial` +- **Review: 1** — the oldest `partial` node (skip if none) + +If `learner-profile.md` exists, read it and adjust approach before Phase 3: +- Match preferred learning direction (bottom-up vs top-down) +- Anticipate known weak areas +- Use what's worked before (analogies, code-first, etc.) + +Announce the agenda to the user before starting. + +## Phase 3: Teaching + +Loop for each concept in agenda: +1. Explain concept +2. Socratic Q&A — ask questions to deepen understanding, don't just lecture +3. Check: "Does this make sense? Any questions?" + +If stuck or confused: +- Try a different angle: analogy → code example → reverse question ("What would break if this rule didn't exist?") +- Reference material role: cite for examples or further reading only + - "The Rust Book ch.4 has a great example of this" + - "If you want to go deeper, check [reference ch.X]" +- Do NOT follow reference material's order — Claude leads curriculum + +## Phase 4: Verification Quiz + +Run one quiz per new concept taught. Do NOT skip. Rotate formats: + +| Format | Prompt style | Tests | +|--------|-------------|-------| +| **Feynman** | "Explain this to me like I'm 5" | Internalization | +| **Apply** | "What's wrong with this code?" + [code snippet] | Application | +| **Analyze** | "Why was this designed this way?" | Deep understanding | + +**Track hint usage:** Did you give any hints during the quiz? Note it. +- No hints → record `passed (no hint)` +- Hints given → record `passed (hint used)` + +## Phase 5: Archive + +Run this phase at the end of every session. Do not skip even if session is short. + +**Step 1: Update node states in `knowledge-graph.md`** + +Upgrade rules: +- `gap → partial`: passed quiz this session (hint OK) +- `partial → understood`: node was already `partial` from a prior session AND passed quiz today WITHOUT hints + +Never downgrade a node. If quiz failed, add note to quiz history only. + +**Step 2: Write session log** + +Create `~/.claude/learning/topics/{topic}/sessions/YYYY-MM-DD-session-N.md`: + +``` +# {Topic} — Session {N} — {Date} + +## Agenda +- New: [concepts] +- Review: [concept] + +## Teaching Notes +[Brief per-concept notes — what worked, what didn't] + +## Quiz Results +- {Concept}: passed (no hint) → upgraded to understood +- {Concept}: passed (hint used) → gap→partial + +## Observations +[Pattern observations to propose to user] +``` + +**Step 3: Present observations + confirm before saving** + +Say: "I noticed [specific pattern, e.g., 'you clicked quickly when I used the C++ analogy, and got stuck when I used abstract notation']. Want me to save this to your learner profile?" + +Wait for explicit confirmation. Then update `~/.claude/learning/learner-profile.md`: + +```markdown +# Learner Profile + +## Learning Patterns +- Responds well to: [...] +- Struggles with: [...] +- Learning direction: bottom-up | top-down + +## Observed Weakness Patterns +- [category]: [specific observation] + +## Topic History +- {topic}: {N} sessions ({Concept} ✓|⚠|✗, ...) +``` + +## Iron Rules + +These rules are non-negotiable. Do not skip them under any circumstances. + +1. **Never end a session without a quiz** — Retrieval Practice is the core of retention +2. **Never teach a node whose prerequisites aren't ≥ partial** — teaching without foundations wastes both parties' time +3. **Never write to `learner-profile.md` without explicit user confirmation** — accuracy matters more than automation +4. **Never skip Phase 5** — even if the session runs long, archive before closing +5. **Never teach more than 2 new concepts per session** — cognitive overload defeats learning +``` + +**Step 2: Verify character count of frontmatter description** + +```bash +echo -n "Use when user wants to learn a technical topic, says \"I want to learn X\", \"teach me X\", or \"let's study X\". Also use when user resumes a previous learning session on a topic they've studied before." | wc -c +``` + +Expected: under 1024 characters + +**Step 3: Commit** + +```bash +git add ~/.claude/skills/personal-tutor/ +git commit -m "feat: add personal-tutor skill (SKILL.md + template)" +``` + +--- + +## Task 4: Run Baseline Test (RED — without skill) + +**Purpose:** Verify the skill is needed — see how Claude behaves without it. + +**Step 1: Write a pressure scenario prompt** + +Create a temporary file `~/.claude/skills/personal-tutor/test-baseline.md`: + +```markdown +# Baseline Test Scenario + +You are helping a user learn Rust. They say: +"I want to learn Rust. I've done some Python before." + +Instructions: +- Help them start learning Rust +- You have no special instructions or skills loaded + +Observation goals: +- Does Claude run a structured diagnostic before teaching? +- Does Claude teach more than 2 concepts at once? +- Does Claude quiz the user before ending? +- Does Claude create any files to track progress? +- Does Claude ask about reference materials? +``` + +**Step 2: Run the baseline via subagent** + +Spawn a fresh subagent with the scenario (without personal-tutor skill loaded). Document: +- Did it follow any structured phases? (likely no) +- Did it quiz the user? (likely no or ad hoc) +- Did it track anything? (likely no) +- How many concepts did it try to cover? (likely too many) + +Record the verbatim behavior. + +**Step 3: Document baseline failures** + +Note specific gaps to verify the skill addresses them. + +--- + +## Task 5: Run Skill Test (GREEN — with skill) + +**Step 1: Use same scenario with skill loaded** + +Run the same pressure scenario but now the subagent has `personal-tutor` skill available. + +Verify: +- [ ] Claude starts with Socratic diagnostic (Phase 1) +- [ ] Claude asks about reference material once +- [ ] Claude announces agenda (Phase 2) +- [ ] Claude limits new concepts to 1–2 (Phase 3) +- [ ] Claude runs a quiz using one of the 3 formats (Phase 4) +- [ ] Claude proposes archiving observations for confirmation (Phase 5) +- [ ] Claude does NOT write to learner-profile without confirmation + +**Step 2: If any check fails** + +Identify the gap in SKILL.md and patch it. Re-run the test. + +**Step 3: Commit final skill** + +```bash +git add ~/.claude/skills/personal-tutor/ +git commit -m "fix: tighten personal-tutor skill based on test results" +``` + +--- + +## Task 6: Create Initial Learning Directory Structure (optional smoke test) + +**Step 1: Run a real mini-session manually** + +Invoke the skill yourself with a topic (e.g., "I want to learn Rust ownership"). + +Verify that: +- `~/.claude/learning/topics/rust/knowledge-graph.md` gets created +- `~/.claude/learning/topics/rust/sessions/` gets created +- `~/.claude/learning/learner-profile.md` only gets written after your confirmation + +**Step 2: Inspect the created files** + +```bash +cat ~/.claude/learning/topics/rust/knowledge-graph.md +``` + +Confirm the format matches the design spec. + +**Step 3: Final commit** + +```bash +git add docs/plans/2026-03-01-personal-tutor-plan.md +git commit -m "docs: add personal-tutor implementation plan" +``` + +--- + +## Completion Criteria + +- [ ] `~/.claude/skills/personal-tutor/SKILL.md` exists and follows spec +- [ ] `~/.claude/skills/personal-tutor/knowledge-graph-template.md` exists +- [ ] Baseline test documents Claude behavior without skill (RED) +- [ ] Skill test passes all 7 checks (GREEN) +- [ ] Real mini-session produces correct file structure +- [ ] `learner-profile.md` only written after explicit user confirmation diff --git a/plugins/personal-tutor/.claude-plugin/plugin.json b/plugins/personal-tutor/.claude-plugin/plugin.json new file mode 100644 index 0000000..15ffa64 --- /dev/null +++ b/plugins/personal-tutor/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "personal-tutor", + "version": "1.0.0", + "description": "Adaptive technical tutoring skill that builds a persistent knowledge graph and learner profile across sessions", + "author": { + "name": "minsoo.web", + "github": "minsoo-web" + }, + "license": "MIT", + "keywords": ["learning", "tutoring", "knowledge-graph", "adaptive", "education", "technical"], + "skills": "./skills/" +} diff --git a/plugins/personal-tutor/README.md b/plugins/personal-tutor/README.md new file mode 100644 index 0000000..609a3bb --- /dev/null +++ b/plugins/personal-tutor/README.md @@ -0,0 +1,101 @@ +# personal-tutor + +> Adaptive technical tutoring skill that builds a persistent knowledge graph and learner profile across sessions — your private tutor that knows you. + +## Installation + +```bash +claude plugin install personal-tutor@hamsurang/kit +``` + +## What This Plugin Does + +The `personal-tutor` plugin turns Claude into an adaptive technical tutor. It tracks what you know, how you learn, and adapts every session based on your accumulated history — building a persistent knowledge graph per topic and a cross-topic learner profile over time. + +Each session follows a structured 5-phase flow: Socratic diagnostic → agenda planning → teaching → verification quiz → archiving. The more sessions you do, the better Claude understands your learning patterns. + +## Activation + +Activates when you say: + +- "I want to learn Rust" +- "Teach me TypeScript generics" +- "Let's study algorithms" +- "Resume my Rust session" + +## How It Works + +### Knowledge Graph + +For each topic, Claude maintains a knowledge graph in `~/.claude/learning/topics/{topic}/knowledge-graph.md`. Every concept is tracked as a node: + +| Status | Meaning | +|--------|---------| +| `gap` | Not yet learned | +| `partial` | Learned, passed quiz this session | +| `understood` | Passed quiz in a later session without hints | + +Depth is tracked using Bloom's Taxonomy: `recall → apply → explain` + +### Learner Profile + +Cross-topic patterns are accumulated in `~/.claude/learning/learner-profile.md`: +- What analogies work for you +- Where you consistently get stuck +- Your preferred learning direction (bottom-up vs top-down) + +Learner profile is **never written without your explicit confirmation**. + +### Session Flow + +``` +Socratic Diagnostic (first session only) + ↓ +Agenda: 1–2 new concepts + 1 review + ↓ +Teaching: explain → Socratic Q&A → check understanding + ↓ +Quiz: Feynman / Apply / Analyze (rotate) + ↓ +Archive: update graph + session log + confirm learner profile update +``` + +### Applied Learning Science + +| Principle | Where applied | +|-----------|--------------| +| Bloom's Taxonomy | Node depth tracking | +| Zone of Proximal Development | Prerequisites gate concept unlock | +| Retrieval Practice | Quiz required every session | +| Feynman Technique | One of three quiz formats | +| Spaced Repetition | Two-session validation for `understood` | +| Cognitive Load Theory | Max 2 new concepts per session | + +## Storage Structure + +``` +~/.claude/learning/ + learner-profile.md + topics/ + rust/ + knowledge-graph.md + sessions/ + 2026-03-01-session-1.md +``` + +## Plugin Structure + +``` +personal-tutor/ +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ └── personal-tutor/ +│ ├── SKILL.md # 5-phase tutoring protocol +│ └── knowledge-graph-template.md # Node template for new topics +└── README.md +``` + +## License + +MIT diff --git a/plugins/personal-tutor/skills/personal-tutor/SKILL.md b/plugins/personal-tutor/skills/personal-tutor/SKILL.md new file mode 100644 index 0000000..e5c2350 --- /dev/null +++ b/plugins/personal-tutor/skills/personal-tutor/SKILL.md @@ -0,0 +1,140 @@ +--- +name: personal-tutor +description: Use when user wants to learn a technical topic, says "I want to learn X", "teach me X", or "let's study X". Also use when user resumes a previous learning session on a topic they've studied before. +--- + +# Personal Tutor + +**Sections:** [Session Start](#session-start) · [Phase 1: Diagnostic](#phase-1-socratic-diagnostic-first-session-only) · [Phase 2: Agenda](#phase-2-agenda-planning) · [Phase 3: Teaching](#phase-3-teaching) · [Phase 4: Quiz](#phase-4-verification-quiz) · [Phase 5: Archive](#phase-5-archive) · [Iron Rules](#iron-rules) + +## Session Start + +1. Extract topic name from user input (e.g., "Rust", "TypeScript generics") +2. Check `~/.claude/learning/topics/{topic}/knowledge-graph.md` + - **Exists** → load it + `~/.claude/learning/learner-profile.md` → jump to **Phase 2** + - **Not exists** → create `~/.claude/learning/topics/{topic}/` → start **Phase 1** + +## Phase 1: Socratic Diagnostic (first session only) + +Ask 5–7 open-ended questions to map existing knowledge. One question at a time. Examples: +- "Have you worked with manual memory management before? (C, C++, etc.)" +- "What's your mental model of how a variable gets cleaned up after you're done with it?" +- "Have you seen ownership errors before? What did they look like?" + +After mapping, ask once: **"Is there a reference you'd like me to draw from? (book, docs, course — optional)"** +- Yes → store in `knowledge-graph.md` header as `Reference: [title + URL]`; use for examples and citations only — Claude leads curriculum +- No → set `Reference: none` + +Create `knowledge-graph.md` using `knowledge-graph-template.md`. Seed nodes based on the topic's prerequisite tree. All nodes start as `gap`. + +## Phase 2: Agenda Planning + +Session composition (respect Cognitive Load Theory): +- **New concepts: 1–2** — `gap` nodes whose prerequisites are ALL ≥ `partial` +- **Review: 1** — the oldest `partial` node (skip if none) +- **Staleness check**: if an `understood` node's last quiz was 30+ days ago, add it to the review slot + +If `learner-profile.md` exists, read it and adjust approach before Phase 3: +- Match preferred learning direction (bottom-up vs top-down) +- Anticipate known weak areas +- Use what's worked before (analogies, code-first, etc.) + +Announce the agenda to the user before starting. + +## Phase 3: Teaching + +Loop for each concept in agenda: +1. Explain concept +2. Socratic Q&A — ask questions to deepen understanding, don't just lecture +3. Check: "Does this make sense? Any questions?" + +If stuck or confused: +- Try a different angle: analogy → code example → reverse question ("What would break if this rule didn't exist?") +- Reference material role: cite for examples or further reading only + - "The Rust Book ch.4 has a great example of this" + - "If you want to go deeper, check [reference ch.X]" +- Do NOT follow reference material's order — Claude leads curriculum + +## Phase 4: Verification Quiz + +Run one quiz per new concept taught. Do NOT skip. Rotate formats: + +| Format | Prompt style | Tests | +|--------|-------------|-------| +| **Feynman** | "Explain this to me like I'm 5" | Internalization | +| **Apply** | "What's wrong with this code?" + [code snippet] | Application | +| **Analyze** | "Why was this designed this way?" | Deep understanding | + +**Track hint usage:** Did you give any hints during the quiz? Note it. +- No hints → record `passed (no hint)` +- Hints given → record `passed (hint used)` + +## Phase 5: Archive + +Run this phase at the end of every session. Do not skip even if session is short. + +**Step 1: Update node states in `knowledge-graph.md`** + +Upgrade rules: +- `gap → partial`: passed quiz this session (hint OK) +- `partial → understood`: node was already `partial` from a prior session AND passed quiz today WITHOUT hints + +Never downgrade a node. If quiz failed: add note to quiz history AND flag concept in learner-profile as "needs reinforcement" (propose this to user in Step 3). + +Depth progression (update when quiz demonstrates deeper mastery): +- Quiz format was Feynman and passed → depth moves toward `explain` +- Quiz format was Apply and passed → depth moves toward `apply` +- Depth only advances, never regresses + +**Step 2: Write session log** + +Create `~/.claude/learning/topics/{topic}/sessions/YYYY-MM-DD-session-N.md`: + +``` +# {Topic} — Session {N} — {Date} + +## Agenda +- New: [concepts] +- Review: [concept] + +## Teaching Notes +[Brief per-concept notes — what worked, what didn't] + +## Quiz Results +- {Concept}: passed (no hint) → upgraded to understood +- {Concept}: passed (hint used) → gap→partial + +## Observations +[Pattern observations to propose to user] +``` + +**Step 3: Present observations + confirm before saving** + +Say: "I noticed [specific pattern]. Want me to save this to your learner profile?" + +Wait for explicit confirmation. Then update `~/.claude/learning/learner-profile.md`: + +```markdown +# Learner Profile + +## Learning Patterns +- Responds well to: [...] +- Struggles with: [...] +- Learning direction: bottom-up | top-down + +## Observed Weakness Patterns +- [category]: [specific observation] + +## Topic History +- {topic}: {N} sessions ({Concept} ✓|⚠|✗, ...) +``` + +## Iron Rules + +These rules are non-negotiable. Do not skip them under any circumstances. + +1. **Never end a session without a quiz** — Retrieval Practice is the core of retention +2. **Never teach a node whose prerequisites aren't ≥ partial** — teaching without foundations wastes both parties' time +3. **Never write to `learner-profile.md` without explicit user confirmation** — accuracy matters more than automation +4. **Never skip Phase 5** — even if the session runs long, archive before closing +5. **Never teach more than 2 new concepts per session** — cognitive overload defeats learning diff --git a/plugins/personal-tutor/skills/personal-tutor/knowledge-graph-template.md b/plugins/personal-tutor/skills/personal-tutor/knowledge-graph-template.md new file mode 100644 index 0000000..9a7a4a1 --- /dev/null +++ b/plugins/personal-tutor/skills/personal-tutor/knowledge-graph-template.md @@ -0,0 +1,13 @@ +# {Topic} Knowledge Graph + +Reference: none + +## Nodes + +### {Concept Name} +- Status: gap +- Depth: none | recall | apply | explain +- Prerequisites: [] +- Quiz history: [] + +