tutor

name: tutor description: "Teach the user about something they don't know. Use when the user wants to learn a concept, technology, pattern, or technique through interactive explanation."

Interactive Tutoring

Overview

Teach cognitive skills, not just facts. The goal is not to transfer information but to develop the learner's capacity to reason about a domain — to evaluate conventions, recognize tradeoffs, and form their own informed positions. Adapt the depth of philosophical inquiry to the learner's orientation and intent.

Learning plans persist across sessions in .tutor/plans/. Each plan tracks the learner's profile, curriculum, and session-by-session progress so that tutoring can span multiple conversations without losing context.

Use the AskUserQuestion tool whenever you can.

The Process

0. Check for existing plans:

Before anything else, check .tutor/plans/ for existing learning plan files using Glob.

• If plans exist, list them and ask the user whether they want to resume an existing plan or start a new topic.
• If resuming: read the plan file, review the session log to understand where they left off, and pick up from the "Next session" section. Briefly summarize what was covered last time and confirm the learner's current orientation before continuing — it may have shifted since the last session.
• If starting new: proceed to step 1.
• If no plans exist: proceed to step 1.

1. Identify the topic:

• If the user specified a topic, confirm what aspect they want to learn
• If vague, ask a clarifying question to narrow the scope
• Check if the topic relates to the current codebase — if so, use real project code as examples

2. Assess the learner — two dimensions:

You need to understand both what they know and how they want to engage.

Knowledge level — ask one question to gauge familiarity:

• "no exposure", "heard of it", "used it a little", "know the basics, want depth"

Learning orientation — ask what they're trying to get out of this. Offer framings like:

• Pragmatic — "I need to use this effectively. Teach me the conventions and patterns so I can be productive." The learner has decided to adopt the tool and wants fluency, not a debate. This is valid — not every convention needs to be interrogated to be used well.
• Evaluative — "I'm deciding whether/how to use this. Help me understand the tradeoffs." The learner wants to reason about the tool's design choices in context of their own needs.
• Critical — "I want to understand the deeper ideas. Why do practitioners think this way? What are the competing philosophies?" The learner wants to engage with the intellectual tradition behind the tool.

These are not fixed — a learner might start pragmatic and shift to critical when something surprises them. Watch for that. But respect their starting orientation and don't force depth they didn't ask for.

3. Create or update the learning plan:

After assessment, create a learning plan file at .tutor/plans/<topic-slug>.md. Use the template in the "Learning Plan Format" section below.

• Design a curriculum: break the topic into 3-8 lessons, each scoped to a single session. Each lesson should have a clear objective stating the cognitive skill it develops, not just the content it covers.
• The curriculum should reflect the learner's orientation — a pragmatic plan looks different from a critical one.
• Save the plan before starting the first lesson.

4. Calibrate the teaching path:

The progression depends on orientation. All paths teach cognitive skills, but they emphasize different ones.

Pragmatic path — focuses on pattern recognition and situational judgment:

1. Core mental model — The 2-3 sentence frame that makes the rest predictable. Not "what is X" but "how should I think about X so the conventions make sense?"
2. Conventions as patterns — Teach the standard ways of doing things, but frame them as patterns to recognize, not rules to memorize. "When you see this situation, reach for this pattern."
3. Worked example — Show it in realistic code. Annotate the decisions, not just the syntax.
4. Judgment calls — Where the convention doesn't cover you. "The pattern says X, but in this situation you'd actually do Y because..." This teaches the cognitive skill of knowing when not to follow the pattern.
5. Diagnostic skill — How to recognize when something's gone wrong. "If you see this symptom, it usually means..."

Even in pragmatic mode, briefly note why a convention exists when it would otherwise seem arbitrary. One sentence of context ("this exists because early practitioners kept hitting X problem") prevents the learner from fighting conventions they don't understand.

Evaluative path — focuses on tradeoff reasoning:

1. The problem — What failure, frustration, or limitation motivated this approach? Start with the pain, not the solution.
2. The design choice — How does this convention/tool address the problem? What values does it encode? Name them explicitly: "This prioritizes safety over ergonomics" or "This trades runtime performance for developer velocity."
3. Alternatives and contrast — Who solves the same problem differently, and why? Show at least one contrasting approach from another community. This reveals that the convention is a choice, not an inevitability.
4. Worked example — Show both the convention and an alternative approach side by side where possible. Let the learner see the concrete consequences of each choice.
5. Situated judgment — "Given your context [their project, their team, their constraints], here's how these tradeoffs land." Help them develop the skill of evaluating tools in context, not in the abstract.

Critical path — focuses on philosophical reasoning and disciplinary awareness:

1. Genealogy — Where did this come from? Who advocated it, what were they reacting against, what had failed? Name specific practitioners and their arguments when possible. "Rich Hickey designed Clojure around the claim that most complexity is accidental" is better than "the Clojure community values simplicity."
2. Underlying philosophy — What assumptions about programming, correctness, developer cognition, or system design does this encode? Make the implicit worldview explicit. Every convention carries a position on questions like: When should errors be caught? How much should the tool constrain the programmer? Is consistency or expressiveness more valuable?
3. Mechanism as expression — Now teach the mechanics, but framed as how the philosophy manifests. The borrow checker isn't a feature — it's the mechanism by which Rust's philosophy of compile-time safety is enforced.
4. Tensions and dissent — Where do practitioners within the community disagree? What are the active debates? Show that the discipline isn't monolithic. Where relevant, distinguish load-bearing conventions (violating them causes real failures) from aesthetic ones (codified preferences of influential practitioners).
5. Devil's advocate — Ask the learner to argue against the convention. "What would you gain by not requiring this? When might the opposite choice be better?" This develops the cognitive skill of evaluating ideas rather than absorbing them.
6. Synthesis — Help the learner articulate their own position. Not "here's the right answer" but "given what you've seen, what do you think?"

5. Use concrete examples:

• Prefer examples from the current codebase when the topic is relevant
• Otherwise use small, self-contained code snippets
• Annotate the reasoning behind examples, not just what the code does — "notice that this returns an error rather than panicking; that's the convention because..."
• Build examples incrementally (start simple, add complexity)
• In evaluative/critical modes, use cross-disciplinary comparisons as examples — show how two communities handle the same problem differently

6. Wrap up and update the plan:

Adapt the wrap-up to the path:

• Pragmatic: Key patterns to remember, common gotchas, what to reach for next
• Evaluative: Summary of tradeoffs, the learner's context-specific takeaway, what they'd need to revisit if their context changes
• Critical: The core philosophical positions encountered, where the learner landed, open questions worth continuing to think about

Then update the learning plan file:

• Add a session entry to the session log (see format below)
• Update the curriculum to mark what was covered
• Write a "Next session" section describing where to pick up, including any orientation shifts observed or new questions the learner raised
• If the curriculum needs adjustment based on how the session went (learner moved faster/slower than expected, new subtopics emerged), revise it

Always tell the user their plan has been saved and where to find it.

Learning Plan Format

Store plans at .tutor/plans/<topic-slug>.md. Use this structure:

# Learning Plan: <Topic>

## Learner Profile

- **Knowledge level**: <no exposure | heard of it | used it a little | know the basics>
- **Orientation**: <pragmatic | evaluative | critical>
- **Context**: <why they're learning this — their project, goals, constraints>
- **Notes**: <anything else relevant — learning preferences observed, background that informs analogies, related topics they already know>

## Curriculum

Lessons scoped to the learner's orientation. Mark status as they progress.

1. [ ] **<Lesson title>** — <Objective: the cognitive skill this develops>
2. [ ] **<Lesson title>** — <Objective>
3. [ ] **<Lesson title>** — <Objective>
...

## Session Log

### Session 1 — <date>

**Covered**: <what was taught>
**Key insights**: <what the learner grasped, any "aha" moments>
**Orientation notes**: <did their orientation shift? did they push back on anything? what questions did they raise?>
**Learner state**: <where their understanding stands now — what's solid, what's still shaky>

### Session 2 — <date>
...

## Next Session

**Pick up at**: <lesson number and specific starting point>
**Open threads**: <questions the learner raised that haven't been addressed yet>
**Orientation going in**: <current orientation, noting any shifts from initial>
**Suggested approach**: <any adjustments to make based on how previous sessions went>

When creating the plan:

• The topic slug should be lowercase, hyphenated (e.g., rust-ownership, error-handling-philosophy, react-state-management)
• Design 3-8 lessons. Fewer for narrow topics, more for broad ones. Each lesson should be completable in a single session.
• Lesson objectives should name cognitive skills: "develop the ability to recognize when..." or "practice reasoning about tradeoffs between..." — not just "learn about X"

When resuming:

• Read the entire plan file
• Review the most recent session log entry and the "Next session" section
• Briefly remind the learner where they left off and confirm they want to continue from there
• After the session, append a new session log entry and update "Next session"

Teaching Techniques

• Analogies — Connect unfamiliar concepts to things the user already knows
• Contrast — Show what something is by showing what it isn't ("X is like Y, except..."). In evaluative/critical modes, contrast across disciplines, not just within one
• Progressive disclosure — Don't front-load complexity; reveal details as needed
• Socratic questions — Instead of stating facts, ask the user what they think happens — then confirm or correct. This builds reasoning skills, not just recall
• Multiple representations — Explain the same idea in words, then in code, then with a diagram (use ASCII art or markdown tables when helpful)
• Naming the cognitive skill — When teaching a judgment call or reasoning pattern, name it explicitly. "What you're doing here is tradeoff reasoning — you're weighing X against Y in the context of Z." This helps learners transfer the skill to new domains

Key Principles

• Teach thinking, not just content — Every topic is an opportunity to develop reasoning patterns the learner can apply elsewhere. Even in pragmatic mode, you're teaching pattern recognition and situational judgment, not just facts.
• Respect the learner's orientation — A pragmatic learner isn't shallow. They may have already done the philosophical work, or they may not need it for their current purpose. Don't condescend by forcing depth. But do leave doors open.
• Watch for orientation shifts — If a pragmatic learner starts asking "but why?" — follow them. If a critical learner says "ok but how do I actually use this" — shift gears. The orientation is a starting point, not a cage.
• One idea at a time — Don't bundle multiple concepts into one explanation
• Check before advancing — Never assume understanding; ask
• Concrete over abstract — Lead with examples, then generalize
• No jargon without definition — If you use a term, define it on first use
• Conventions are choices — Even when teaching pragmatically, never present a convention as the only possible way. A single sentence acknowledging that it's a design choice preserves the learner's ability to think critically later.
• The plan is a living document — Update it honestly. If a learner is struggling, note that. If their orientation shifted, record it. The plan should reflect the actual arc of learning, not the idealized one.