study

/tutor:study

Lead the user through the onboarding docs as a code walk, one layer at a time, in one of three study modes (see Choosing a mode): guided drives them into specific file lines with questions they can only answer by reading the code; lecture and reference present a whole layer at once with code quoted inline. Coverage is tracked per topic so a session can be resumed later.

Preconditions

Check for docs/onboarding/index.md in the current repo root. If it does not exist, tell the user to run /tutor:build-study-guide first and stop.

If the file exists, run the Freshness procedure defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. Surface its advisory line verbatim if triggered; otherwise proceed silently.

Read .tutor/review.md if it exists and build the coverage set — the (layer, topic) pairs already walked, per the review.md format in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. Keep this in scope for the session to drive Resume and the coverage summary below. If the file does not exist, there is no prior coverage.

Choosing a route

Parse the argument(s) passed to the skill:

• layer-id given — start the walk on that layer. Read its NN-<layer>.md doc.

• --route data-flow — order the layers to trace the end-to-end data path described in docs/onboarding/00-overview.md. Reorder the index.md layer list to follow that path.

• --route top-down — walk layers in the order they appear in index.md.

• --route bottom-up — walk layers in reverse index.md order.

• No argument — ask the user where they want to start. If prior coverage exists, lead with a one-line summary (e.g. "You've walked 3 of 7 layers; next un-walked is model-builder · cache-roles."). Offer:

  1. Resume — continue at the first un-walked topic in route order (the next un-walked layer, starting at its first un-walked topic). Only offer this when prior coverage exists.
  2. Saved topics — study from your bookmarks. Only offer this option when .tutor/saved-topics.jsonl exists and has ≥ 1 active entry (see Saved topics below).
  3. Pick a layer by name or number from the index.md table (this is how you start a different review).
  4. Describe a named entry point ("start at the database", "follow a request from the API") and you will map it to the corresponding starting layer or topic within a layer.

  Wait for their choice before proceeding.

When the route resolves, compute Resume as the first topic — in the active route order — whose (layer, topic) pair has no row in the coverage set. Already-walked topics are not re-walked on Resume unless the user asks; mention them briefly and move to the first un-walked one.

Saved topics

When the user picks Saved topics:

1. Build the active list. Read .tutor/saved-topics.jsonl and apply the active-entry rules defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md:

   • Exclude entries tombstoned by a "studied" event.
   • Exclude linked entries (layer+topic both non-empty) whose (layer, topic) pair already has a row in .tutor/review.md.

2. If the active list is empty: Tell the user all saved topics have already been walked, then fall back to the normal route/layer picker (options 3 and 4 above).

3. Display the list. Number the active entries, most-recent first, showing title, timestamp, and (if present) the linked layer + topic.

4. Wait for the user to pick one by number or title.

5. If the chosen entry has layer + topic: Navigate directly — load that layer's doc, start at that specific topic. Before the first question, show the saved description as a one-line context note so the user remembers why they bookmarked it. From here, proceed as in normal guided/lecture/reference mode; the topic is marked walked in review.md as usual, which retires this bookmark automatically.

6. If layer/topic are empty: Show the description and ask the user which layer they'd like to start on (standard layer-pick UI, same as option 3 above). The description is context, not a route — use it to orient the session but do not constrain which layer is chosen. When the session ends or the user stops, append a "studied" tombstone to .tutor/saved-topics.jsonl for this entry (format in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md).

Choosing a mode

Parse --mode guided|lecture|reference from the arguments.

• --mode given — use that mode for the session.

• --mode omitted — ask the user which mode they want, together with the route/layer question above. Present the three choices:

  • guided (default) — one topic at a time. I point you to file:line and ask a question you can only answer by reading the code; I don't narrate until you've looked.
  • lecture — I present a whole layer at once, narrating each topic and quoting the relevant code inline (with citations). After the layer I offer an optional comprehension check.
  • reference — same dense, inline-quoted narration of the whole layer, with no questions. Read straight through.

  If the user gives a route/layer but no mode, default to guided rather than blocking.

The mode is switchable mid-session. If the user asks to "switch to lecture/reference/ guided", apply the new mode starting with the next layer.

Walking a layer

How you work through each layer's ## Topics depends on the active mode. In every mode, read citations using the format defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md.

guided (default)

Work through the ## Topics one at a time. For each topic:

1. Point to the code. Read the topic's first citation. Tell the user the file:line reference and ask them to open it — do not quote the code for them.
2. Ask a grounded question. Pose a question that can only be answered by reading those specific lines (e.g. "What field does the constructor set here?"). Phrase it so a correct answer proves the user looked.
3. Wait. Do not continue until the user responds.
4. Confirm or correct. Acknowledge what they got right. If their answer is wrong or vague, send them back to the same lines with a more precise pointer — never supply the answer yourself (see Drive-to-code rule).
5. Expand. Once the user has demonstrated they read the code, explain the concept, data-flow context, or gotcha from the doc. Narrate after, not before.

If a topic has multiple citations, use the first to anchor the question; bring in additional citations during the expansion step or to deepen follow-up questions.

lecture

Present the whole layer as continuous reading. Work through all ## Topics in order; for each, narrate the concept and quote the relevant code snippet inline, keeping its file:line citation so the user can click through. Do not gate progress on questions.

After the layer, offer one comprehension check with three choices:

1. Ask a few grounded questions (guided-style) on this layer's topics.
2. Skip to the next layer.
3. Launch the full quiz by invoking the /tutor:quiz <layer-id> skill directly.

reference

Same dense, inline-quoted narration of the whole layer as lecture, but ask no questions. After the layer, go straight to the next-layer/stop prompt below.

Recording coverage (all modes)

The moment a topic is walked, append one row for its (layer, topic, mode) to .tutor/review.md, using the format in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md (create the file with its header if it does not yet exist). Write each row immediately — do not batch — so an interrupted session is preserved. A topic is walked:

• guided — after the Expand step (the user read the code and you explained it).
• lecture / reference — after you have narrated and quoted that topic.

Do not record a topic the user explicitly skipped without it being walked.

Diagram rules

When to show

Diagrams are orientation aids, not answers. Showing a diagram never violates the Drive-to-code rule — that rule prohibits narrating code before the user reads it; structural flowcharts do not contain code answers. A diagram may be shown in any mode at any time if the user requests it.

Automatic display rules by mode:

Trigger	guided	lecture	reference
Layer start (layer doc has ## Diagram)	Show once, before first topic	Show once, before narration begins	Show once, before narration begins
Topic name contains "flow", "boundary", "path", "security", or "pipeline"	Skip	Re-show diagram once per layer (not once per matching topic)	Re-show diagram once per layer (not once per matching topic)
User explicitly requests a diagram	Show immediately	Show immediately	Show immediately

"Show" means: output the ## Diagram section's code block verbatim inline. ASCII diagrams render correctly in the TUI and all other environments with no special handling.

System overview diagram

Before walking the first layer (any mode, any route), check whether 00-overview.md contains a fenced code block. If it does, show it as a brief system-orientation step — a single message with the diagram and one sentence of context — before proceeding to the first layer. Show it only once per session.

No diagram exists and the user asks

If the current layer doc has no ## Diagram section and the user asks for a diagram, generate a minimal ASCII diagram from the layer's overview prose (≤ 12 components), using the drawing conventions in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. Do not write it back to the doc. In guided mode, after showing the ad-hoc diagram, re-issue the pending file:line pointer and question so the user knows where they left off — the diagram interruption does not count as walking a topic.

After each layer (all modes)

Offer the quiz: "Ready to test yourself on this layer?" If the user agrees, launch it by invoking the /tutor:quiz <layer-id> skill directly (do not just print the command).

Then ask whether to continue to the next layer in the route or stop. (In lecture, this follows the comprehension check above.)

Drive-to-code rule (guided mode)

In guided mode you are a guide, not a narrator. The user must open the files. Answering on their behalf defeats the purpose of the session.

• Never front-load the answer before the user has looked at the cited lines.
• If the user's answer is vague ("it does something with the cache"), send them back to the specific file:line with a tighter prompt: "Look at line N specifically — what is the return type?"
• If the user asks you to just explain it, decline politely and redirect: "Open <file>:<line> and tell me what you see — then I can give you the full picture."
• A guided session in which the user never opens a file has failed.

This rule is scoped to guided. lecture and reference are textbook-style reading: quote relevant code inline (always with file:line citations) so the user can absorb a layer without opening files, while keeping citations clickable so they still can.

See also

• ${CLAUDE_PLUGIN_ROOT}/references/conventions.md — authoritative formats for index.md front-matter, layer docs, citation syntax, the Freshness procedure, .tutor/progress.md, and .tutor/review.md (review coverage).