Tutor Agent

The tutor agent helps you understand code, concepts, and patterns. It teaches using the Socratic method and grounds explanations in real code from the repo.

Persona

• Patient and clear — meets the learner where they are.
• Uses the Socratic method: asks questions to guide understanding.
• Explains "why" before "how".
• Uses concrete examples from the repo when possible.

Constraints

• Never modifies project files. The tutor teaches, it doesn't build.
• If you ask it to implement something, it redirects you to /dev.
• May read any file in the repo for explanation purposes.
• Keeps explanations focused — no tangents.

Skills

Skill	Description	Tools	Read-only
/tutor	Explain concepts, teach patterns	Read, Bash, Glob, Grep, WebFetch, WebSearch	Yes
/tutor-explain	Walk through code section by section	Read, Glob, Grep, WebSearch	Yes
/tutor-save	Save/checkpoint tutor session	Read, Write, Edit, Bash, Glob	Sessions only

/tutor

The main tutor skill. Starts by checking for existing sessions to resume, then follows a structured teaching flow:

1. Resume check — looks for active or paused sessions and offers to continue.
2. Clarify — confirms what you want to learn.
3. Save on start — creates a session file immediately so the session is tracked from the beginning.
4. Contextualize — finds relevant examples in the repo.
5. Explain — starts with the big picture, then zooms into details.
6. Check — asks a follow-up question to verify understanding.
7. Extend — suggests related topics or next steps.
8. Auto-save — when the session winds down, saves state and commits to git.

Arguments:

• /tutor — normal flow (resume check, then teach)
• /tutor sessions — list all saved sessions with topic, date, and status
• /tutor resume [topic] — skip the resume prompt and go straight to resuming
• /tutor restart [topic] — reset a session and start over from the beginning

/tutor-explain

Walks through a file or code section with a structured breakdown:

1. Purpose — what the section does and why it exists.
2. Walk-through — line-by-line or block-by-block explanation.
3. Patterns — design patterns or idioms in use.
4. Connections — how it relates to other parts of the repo.

Ends with comprehension-check questions and suggestions for what to look at next.

/tutor-save

Manual checkpoint for tutor sessions. Use this when you want explicit control over when a session is saved.

• /tutor-save — save with status paused (default)
• /tutor-save completed — mark the session as finished

Session Persistence

Tutor sessions are persisted as JSON files in agent/tutor/sessions/. This lets the tutor resume where it left off across conversations.

Lifecycle

• Active — session is in progress. Created when /tutor starts a new topic or resumes a paused session.
• Paused — session is saved but not finished. Created by /tutor-save or auto-save when a conversation winds down.
• Completed — session is finished. Set by /tutor-save completed when a topic is fully covered.

Session Data

Each session file tracks:

• Topics — planned subtopics with status (covered, in-progress, planned) and comprehension level (strong, moderate, weak, untested).
• Learnings — concepts taught, with summaries, code examples, and related topics.
• Open questions — unresolved questions with context and suggested approaches.
• Log — timestamped interaction history (questions, explanations, examples, comprehension checks).

JSON Schema

Session files follow this structure:

{
  "version": 1,
  "sessionId": "<topic-slug>--<YYYY-MM-DDTHH-MM-SS>",
  "topic": "Human-readable topic name",
  "startedAt": "ISO 8601",
  "updatedAt": "ISO 8601",
  "status": "active | paused | completed",
  "topics": [
    {
      "name": "Subtopic name",
      "status": "covered | in-progress | planned",
      "comprehension": "strong | moderate | weak | untested",
      "notes": "Optional notes"
    }
  ],
  "learnings": [
    {
      "concept": "Concept name",
      "summary": "What was learned",
      "examples": ["file:line"],
      "relatedTopics": ["..."]
    }
  ],
  "openQuestions": [
    {
      "question": "...",
      "context": "...",
      "suggestedApproach": "..."
    }
  ],
  "log": [
    {
      "timestamp": "ISO 8601",
      "type": "question | explanation | example | comprehension-check | checkpoint | note",
      "content": "...",
      "filesReferenced": ["..."]
    }
  ]
}

Branch-Specific Data

Session data is branch-specific — it lives on the workspace branch where the learning happened. Sessions are never merged across branches (e.g., personal sessions stay on personal).