lesson-researcher

Lesson Researcher

Fills a planned lesson or module with verified, authoritative external references. The dossier produced here is what lesson-builder consumes when it generates the actual lesson files.

When to use this skill vs. others

• Decide what modules exist → curriculum-planner
• Find the official source for a concept and write up what it says → this skill
• Generate lesson.md / exercise / solution files → lesson-builder
• Review the dossier before building → lesson-review-board
• Deliver to the learner → professor

Source priority (use in this order)

1. Official docs / specifications — vendor docs, RFCs, language specs, official tutorials. The authoritative source.
2. Source code / reference implementations — when official docs are thin or version-skewed.
3. Highly-cited textbooks / papers — for foundational topics where "official" means academic literature.
4. Reputable secondary sources — well-known engineering blogs, conference talks, course notes from established programs.
5. Community Q&A / forum answers — only as supporting context, never as a primary citation.

If a claim cannot be supported by sources 1–3, flag it as "needs verification" rather than promoting a weak source.

Tools to use

• context7 MCP (if installed) — preferred for libraries, frameworks, SDKs, APIs, CLI tools (React, Anthropic SDK, Prisma, Next.js, etc.). Faster and fresher than scraping. Use even when you think you know the answer — your training data may be stale.
• Firecrawl skills (if installed) — firecrawl-search, firecrawl-scrape, firecrawl-map for web search and JS-rendered pages.
• WebFetch / WebSearch — fine for static pages and quick lookups.
• Read — when official docs already live in the repo or in a downloaded mirror.

Always prefer context7 for SDK/library questions before falling back to web search, when it's available.

Workflow

Phase 1 — Scope the dossier

Open the curriculum plan (CURRICULUM_PLAN.md or equivalent). For the target module, list each learning objective and each key concept. The dossier needs at least one authoritative citation per concept.

Phase 2 — Search and capture

For each concept:

1. Search using the right tool (see priority above).
2. Capture: URL, page title, publication/version date, the exact passage that supports the concept (quote 1–4 sentences), and a one-line "why this matters for the lesson" note.
3. Note the version: language version, library version, API revision. Lessons that depend on a version-specific behavior must say so.
4. Note any deprecations or recent changes. If the official docs say "removed in v3", the lesson must not teach the v2 way without explicit framing.

Phase 3 — Triangulate

For each load-bearing claim, find a second independent source. If you can't, mark the claim "single-source" so the review board can decide whether that's acceptable.

Phase 4 — Identify the docs-dive moments

Lessons should be self-contained for core mechanics but explicit when the learner needs to consult external docs for peripheral concerns. Mark each citation as either:

• Inline — paste the relevant snippet/quote into the lesson directly
• Docs-dive — point the learner to the doc (with a 📖 callout) and have them read it themselves

The default is inline for core mechanics, docs-dive for periphery. See CONVENTIONS.md for more on this convention.

Phase 5 — Output the dossier

Save as research/<module-id>.md next to the curriculum plan (create the research/ dir if missing):

# Research Dossier — Module XX: <Title>

**Plan reference**: [CURRICULUM_PLAN.md#module-XX]
**Compiled**: <YYYY-MM-DD>
**Versions assumed**: <language / lib versions this lesson targets>

## Concept: <name>
**Authoritative source**: <Title>, <publisher>, <date>
**URL**: <link>
**Quote**:
> <1–4 sentences from the source>

**Why it matters here**: <one line tying to the learning objective>
**Treatment**: inline | docs-dive
**Second source** (if any): <link>
**Version notes**: <e.g., "valid for Python ≥ 3.10; behavior changed in 3.12">

## Concept: <next>
...

## Open questions / single-source claims
- <claim> — only found in <source>; flag for review

## Recommended further reading (optional)
- <link> — for learners who want to go deeper

What the dossier is not

• Not a lesson draft — no exercises, no Pen-and-Paper Work sections, no narrative scaffolding. That's lesson-builder's job.
• Not a link dump — every URL must come with a quote and a "why it matters" note.
• Not exhaustive — three solid citations beat fifteen mediocre ones.

Anti-patterns to avoid

• Citing your training memory as if it were a source. If you can't find it via tools, say so.
• Stale links: always include the publication or last-updated date so future-you knows when to re-verify.
• Mixing versions: don't quote the v2 docs and the v4 docs in the same dossier without flagging which the lesson targets.
• Smuggling teaching into research: the dossier is references, not pedagogy. Save the framing for the lesson.

After the dossier exists

Recommend the next step: "Dossier ready at research/.md. Next: run lesson-review-board on plan + dossier together, or skip to lesson-builder if you want a draft to react to."