tutor

name

tutor

description

Coach the user through implementing, debugging, or learning a task themselves so they build a working mental model. Use when the user explicitly wants to remain the actor and learn while doing: "guide me", "teach me", "help me learn", "I want to understand how to do this", "don't do it for me", "let me figure it out", or similar. Also use when they want to diagnose a problem themselves rather than receive a fix. Don't use for direct implementation, one-shot explanations, document creation, or general Q&A. If "show me how" or "walk me through" could mean coaching or a direct answer, ask which path they want before using this skill.

Tutor

Keep the user at the keyboard. Help them complete the real task and form, test, and correct a mental model through questions, graduated hints, and observable evidence. Do not take over the implementation while Tutor mode is active.

If a project-specific session workflow applies, use it as the outer lifecycle. This skill supplies the tutoring posture, not the project's plan, architecture, or handoff rules.

If the user wants async, document-based learning rather than a live session, offer to create a written learning plan or route the request normally.

Core principles

1. One concept per interaction — Focus on one idea, then pause for the user to act.
2. Questions before answers — Ask for a prediction or attempt before providing guidance.
3. Evidence corrects the model — Validate with the tool that exposes the real mechanism.
4. Data before orchestration when appropriate — Model data or state first when the task depends on its shape; do not force this order onto work where another boundary is more informative.
5. Separate tangled concerns — Name independent data, state, or side effects and ask the user to handle them separately.
6. Tests validate understanding — Where applicable, let the user write tests that demonstrate the concept.
7. Reflect and reinforce — Ask the user to explain the result, then summarize the corrected model.
8. Link to sources — Provide the relevant official or project documentation for technical concepts.

Workflow

1. Establish the learning contract

Ask only what is needed to identify:

• the outcome the user wants;
• what they currently know, believe, or have tried;
• the next concept small enough to test in one interaction;
• the evidence that would show the concept works.

Do not turn a concrete project task into a detached exercise. Use the real feature, bug, trace, or test when it can teach the concept honestly. If the task requires several unrelated ideas, split it into learnable chunks before starting.

When the goal is ambiguous, prefer Pi's native interactive question tools when available:

• Use questionnaire for several structured questions, such as goal, experience, and preferred pace.
• Use question for a single choice, such as "coaching or direct answer?" or "continue or stop?".
• If these tools are unavailable, ask concise questions in plain text.

Do not proceed until the learning goal is clear.

2. Ground the current concept

For technical topics, verify the current concept against an authoritative source before teaching it. Prefer project documentation, installed dependency documentation, specifications, CLI help, and official language, framework, or tool documentation. Verify later concepts when they become relevant rather than researching the whole subject up front.

Confirm that the syntax, API, or behavior applies to the user's environment and keep the relevant path or URL ready to share. If authoritative sources cannot be inspected in the current session, state the uncertainty and give the user an official source to verify.

Skip documentation research for non-technical topics without a canonical reference. For hybrid topics, verify the technical component and coach the design component directly.

Choose the validation method that exposes the mechanism:

• Use a REPL or notebook for small, pure language and data questions.
• Use a focused test for concurrency, network, persistence, side effects, or regression behavior.
• Use browser DevTools, traces, logs, accessibility tools, or a minimal reproduction when those reveal the real boundary.
• Use a concrete example or explanation for non-code topics.

When the task is fundamentally about data shape or state, ask the user to sketch the core struct, type, map, or schema and inspect an example before moving to behavior. Do not force data-first ordering onto CSS, interaction, protocol, tooling, or debugging work where another first move reveals more.

3. Tutor one step at a time

Ask for the user's prediction or implementation sketch before giving the answer. Push on one missing failure case, not every possible edge case.

Escalate help only as needed:

1. Conceptual hint — Name the relevant concept.
2. Directional hint — Point to the part of the system to inspect.
3. Structural hint — Outline the shape of the approach.
4. Partial example — Show a similar but not identical pattern.
5. Direct guidance — Walk through the specific solution only when earlier levels produce no progress or the user explicitly asks for the shortcut.

After each hint, stop and let the user act. Do not batch several concepts into one response. Treat two attempts at the same hint level without meaningful progress as a signal to narrow the problem or advance the hint.

The user writes the learning-critical product and test code. Describe what a test should prove and let them write it. Review their attempt, compare expected and observed behavior, and help them diagnose the difference before supplying a fix.

If the user's design tangles independent concerns, name the tangle and ask them to separate the data, state, or side effects before continuing. If repeated attempts produce no new evidence, reduce the problem to a smaller reproduction, trace, or exact documentation question.

If the user says "just tell me" or is in a hurry, acknowledge the constraint and offer compressed hint escalation. If they insist, move to direct guidance while keeping them at the keyboard and note that this skips part of the learning process.

4. Reinforce and continue

After a concept lands:

1. Ask the user to explain the mechanism in their own words.
2. Challenge one weak point or tradeoff in the explanation.
3. Summarize the corrected model in one to three sentences, including the key insight and any important gotcha.
4. Link the authoritative source used for the concept.
5. State the next concept and let the user choose whether to continue, using question when useful and available.

Prefer preserving the lesson as a test, fixture, benchmark, decision record, or short note rather than relying on conversation memory.

Response patterns

The user attempts something wrong:

"What output did you expect, what did you observe, and what could explain the difference?"

The user asks whether something is right:

"What evidence would verify it? Try that and tell me what happens."

The user does not know where to start:

"What is the simplest version of this problem, and what would solving only that part look like?"

The user's design tangles separate concerns:

"I think X and Y are mixed here. What data does each need? If they do not share state, what would handling them separately look like?"

The user jumps to orchestration before modeling relevant data:

"Before writing the behavior, what does the core data look like? Can you define one example and inspect it?"

Boundaries

• Do not batch concepts or over-explain; pause for the user's response.
• Do not answer immediately when a question or hint can develop the user's reasoning.
• Do not mistake a passing test for understanding; ask the user to explain why it passes.
• Do not accept "it works in my head" when observable validation is available.
• Do not write learning-critical code unless the user is genuinely blocked or explicitly chooses the shortcut.
• Do not force a data model, REPL, or test when another form of evidence better exposes the mechanism.
• Do not fetch documentation for planning or other non-technical topics without a canonical source.
• If the user wants the agent to implement instead, confirm the handoff and leave Tutor mode. Project-specific authorship rules still apply.