Research

---
name: research
description: "Use when the student has a task, project, or goal and needs a structured learning plan — researches prerequisites, finds authoritative resources (docs, articles, RFCs, tutorials), and saves a checklist-style study plan to a file. The student follows the plan at their own pace."
argument-hint: "[task or project]"
---

Requested topic/task: $ARGUMENTS

Before accessing education data, read `${CLAUDE_PLUGIN_ROOT}/references/education-data.md`. Resolve every `<education-db>` below using that contract. Current session ID: `${CLAUDE_SESSION_ID}`.

# Research — Study Plan Generator

Researches what the student needs to learn to successfully complete a task or project, then saves a structured checklist with resources to a markdown file.

## Invocation

`/claude-teacher:research <task or project description>`

Examples:
- `/claude-teacher:research build an FTP server in C`
- `/claude-teacher:research prepare for AWS Solutions Architect exam`
- `/claude-teacher:research create a REST API with authentication`
- `/claude-teacher:research understand how Docker networking works`

## Process

### 1. Understand the Goal

Read `<education-db>/student.json` and `dashboard.json` to understand:
- What the student already knows (skip those topics)
- Their level and background (calibrate depth)
- Their goals and deadlines (prioritize accordingly)
- Their learning style (choose resource types that fit)

Ask clarifying questions if the task is vague:
- What's the end result? (working app, exam pass, understanding)
- Any deadline?
- Any constraints? (language, framework, platform)

### 2. Scan the Project (if applicable)

If the student is working inside a project directory, **read the codebase** before planning:

- **Glob** for source files to understand the tech stack (languages, frameworks, libraries)
- **Read** key files: `README.md`, `package.json`/`Cargo.toml`/`Makefile`/etc., config files, main entry points
- **Grep** for patterns that reveal what's already implemented vs what's missing
- **Check git log** — recent commits show what the student has been working on

This tells you:
- What the student has **already built** (don't plan topics for finished work)
- What they're **currently stuck on** (prioritize those topics)
- What **specific technologies** they're using (find resources for those exact versions/frameworks)
- What **gaps exist** between current code and the goal

If there's no project yet (pure learning goal), skip this step.

### 3. Decompose the Task

Break the task into skills/knowledge areas needed. For each area, determine:
- Is it a **prerequisite** (must know before starting)?
- Is it a **core skill** (directly needed for the task)?
- Is it **nice-to-have** (improves quality but not required)?

Cross-reference with `dashboard.json` — if the student has demonstrated `status: solid`, mark it known. `depth: working` alone still needs review.

Cross-reference with the **project scan** — if the codebase already has a working implementation of something (e.g., TCP socket setup is done), note "already implemented in your project" and include a self-check. Implementation alone does not establish the student's understanding.

### 4. Research Resources

Use **WebSearch** to find real, authoritative resources for each topic. For every topic, find **2-4 resources** from different categories:

| Category | Examples | When to use |
|----------|---------|-------------|
| Official docs | MDN, RFC, language docs, framework docs | Always — primary source |
| Tutorial/guide | DigitalOcean, freeCodeCamp, Real Python | For hands-on learners |
| Article/deep-dive | Blog posts, conference talks, papers | For deeper understanding |
| Video | YouTube tutorials, course lectures | If student prefers video |
| Interactive | Exercism, LeetCode, official interactive tutorials | For practice-oriented students |

**Rules:**
- Every link MUST be real and verified — never hallucinate URLs
- **WebFetch** the top resource for each topic to verify:
  - The page loads and isn't a 404
  - The content is actually relevant to what you're recommending
  - It's reasonably current (not a 2015 tutorial for a 2026 framework)
  - Note the actual title and a one-line summary of what it covers
- If a resource is dead or irrelevant after fetching, replace it — don't include it
- Prefer free resources over paid
- Prefer official docs over third-party when quality is equal
- Include estimated reading/watching time when possible
- Note difficulty level (beginner/intermediate/advanced) for each resource

### 5. Build the Study Plan

Structure the plan as a markdown checklist with clear phases:

```markdown
# Study Plan: [Task/Project Name]

> Generated: [date]
> Goal: [one-line goal description]
> Estimated time: [total estimate]
> Student level: [from student.json]

---

## Phase 1: Prerequisites
*Must understand before starting the main task*

### Topic Name
> Why: [one sentence — why this is needed for the task]
> Status: [new | already known (solid) | needs review (learned/weak)]
> Estimated time: ~Xh

- [ ] Read: [Resource title](url) — [type, difficulty, ~time]
- [ ] Read: [Resource title](url) — [type, difficulty, ~time]
- [ ] Practice: [specific exercise or mini-task to verify understanding]
- [ ] Self-check: [question they should be able to answer after studying]

### Another Topic
...

---

## Phase 2: Core Skills
*Directly needed to complete the task*

### Topic Name
> Why: [why this matters for the task]
> Status: [new | already known | needs review]
> Estimated time: ~Xh

- [ ] Read: [Resource](url) — [details]
- [ ] Build: [hands-on mini-task related to the project]
- [ ] Self-check: [verification question]

---

## Phase 3: Nice-to-Have
*Will improve quality but not strictly required*

### Topic Name
> Why: [how this improves the result]
> Estimated time: ~Xh

- [ ] Read: [Resource](url)
- [ ] Optional: [deeper exploration idea]

---

## Suggested Order

1. [Topic A] → [Topic B] → [Topic C] (prerequisites build on each other)
2. Then [Core Topic D] + [Core Topic E] (can be parallel)
3. Finally [Nice-to-have F] if time permits

## Next Steps

After completing this plan, you should be ready to:
- [Concrete outcome 1]
- [Concrete outcome 2]
- Start building: [first concrete step of the actual task]
```

### 6. Save the Plan

Save to **two locations**:
- Project-local: `docs/study-plan-<slug>.md`
- Global: `<education-db>/docs/study-plan-<slug>.md`

Tell the student the file path so they can open it and start checking off items.

### 7. Update the Education DB

For each NEW topic in the plan that isn't already in the DB:
- Create `<education-db>/topics/<slug>.json` with:
  - `status: "new"` (not yet studied)
  - `depth: "surface"`
  - `first_seen`, `last_reviewed`, `next_review`: `null` (planned, untaught)
  - `review_interval_days: 1`
  - `prerequisites` filled in based on the plan structure
  - `related_topics` filled in
- Update `dashboard.json` to include the new topics

Append to session log:
```jsonl
{"time": "[now]", "event": "research", "task": "[task description]", "plan_file": "docs/study-plan-<slug>.md", "topics_added": ["topic1", "topic2"], "topics_already_known": ["topic3"]}
```

## Adaptation Rules

**Based on student level (from student.json):**
- **Beginner**: More prerequisites, simpler resources, more self-check questions, smaller steps
- **Intermediate**: Skip basics, focus on core + nice-to-have, include deeper resources
- **Advanced**: Minimal prerequisites, focus on specifics and edge cases, include RFCs/papers

**Based on learning style:**
- **Visual learner**: Prioritize video resources, suggest `/claude-teacher:excalidraw` or `/claude-teacher:demo` for complex topics
- **Hands-on learner**: More "Build:" and "Practice:" items, fewer "Read:" items
- **Reader**: More articles and docs, fewer videos

**Based on time commitment:**
- If tight deadline: mark nice-to-haves clearly, suggest minimum viable path
- If open-ended: include deeper exploration paths and bonus topics

## Quality Rules

- Every resource link must be real (verified via WebSearch)
- Every topic must have a "Why:" explaining relevance to the task
- Every topic must have at least one self-check question or mini-task
- The plan must have a clear suggested order (not just a flat list)
- Already-known topics should be acknowledged (not re-assigned)
- Total time estimate should be realistic based on student level

## Integration with Other Skills

- After the student studies a topic from the plan → suggest `/claude-teacher:quiz-me [topic]` to verify
- After a phase is complete → suggest `/claude-teacher:progress` to see updated dashboard
- For visual topics in the plan → suggest `/claude-teacher:ascii`, `/claude-teacher:excalidraw`, or `/claude-teacher:demo`
- For hands-on topics → suggest `/claude-teacher:challenge`
- At session end → `/claude-teacher:summary` captures what was studied from the plan
- The plan file itself becomes a persistent reference the student returns to across sessions