coding_mentorship_sessions v1.0.0

name: coding_mentorship_sessions description: "Run a coding mentorship session while you build together: slow down at decision points, explain why before what, use predict-before-reveal checks that keep the learner active, fade help on purpose, and capture a short lesson note at the end. Triggers when mentoring, pair programming with a learner, tutoring someone through real code, onboarding a junior, or when help keeps turning into doing the work for them."

Coding Mentorship Sessions

Purpose

A standalone session method for mentoring a learner while you code together, in any setup: in person, remote screen share, an agent pairing with a person, or two people in a chat with a shared editor.

The job is two outputs at once: working code, and a learner who can do the next similar task with less help. If only the code ships, the session failed as mentorship, even if the code is good.

The method rests on four researched moves, detailed in references/evidence.md: make thinking visible (cognitive apprenticeship, Collins, Brown and Holum), prompt self-explanation (Chi and colleagues), predict before you reveal or run (PRIMM, Sentance), and fade support in steps instead of dropping it at once (Renkl, Atkinson and Maier). Use the moves, do not lecture the citations unless the learner asks.

Workflow

1. Set the contract in the first two minutes. Name one goal small enough to finish this session, name who drives first, and say out loud that the mentor will slow down at decisions and ask for predictions. A goal like "fix the login bug and learn how you trace a bad state" beats "work on the app".

1. Take a starting snapshot. Ask the learner to state, in plain words, what they can already do here and what feels shaky. Write both down. This is the baseline the end note compares against, and it stops the mentor pitching help at the wrong level.

1. Pick roles and swap on purpose. Driver types and thinks aloud. Navigator holds the goal, watches for drift, asks questions, and looks things up. Swap at a natural break, a finished test, a new file, or roughly every 20 to 30 minutes. That interval is a practical default, not a research finding. Adjust it to the task. A learner who never drives only practices watching.

1. Slow down at decision points, and only there. A decision point is any place with two or more real options: which layer owns a check, how to shape data, which error to handle, whether to refactor now or later. At each one, stop typing and run this order:

• Why before what: state the problem and the constraint first, then the options, then the pick.
• Prompt first: ask the learner "How would you do this, and why?" before giving your own pick.
• Name rejected options and the reason each lost. Silent picks teach nothing.
• Say whether this was a learner call or a mentor call, and record it in the note.

1. Use predict-before-reveal checks at every reveal. Before running code, opening a file, reading an error, or showing a solution step, get a committed prediction:

• "Before we run this, what do you expect to happen, exactly?"
• "What do you think this function returns when the list is empty?"
• "Read this error top line only. What is it claiming broke?" Then reveal or run, compare out loud, and spend the time on the gap. A correct prediction needs one sentence. A wrong one is the lesson, so trace it, annotate it, or test a smaller case until the learner can explain why the real result happened. Never run first and ask after, that turns prediction into guessing at a known answer.

1. Prompt self-explanation while code is in front of you. Ask the learner to explain a step in their own words: "Why does this check come before the loop, not inside it?" If they reach for a label ("it validates the input"), ask what that means concretely for one example value. Restating the code line by line does not count, explaining what would break if the step moved or vanished does.

1. Ask before telling, with a limit. Use this hint ladder, one rung at a time, and wait for a real attempt between rungs:

• Rung 1, focus: "What does this line do?"
• Rung 2, narrow: point at the smaller piece that is wrong and ask about that piece only.
• Rung 3, contrast: show a tiny working case and ask what differs.
• Rung 4, tell: explain it directly, then immediately give a near twin case for the learner to do alone. Two genuine attempts with no progress is the signal to move down a rung. Stuck and silent is not an attempt. Ask what they tried and what they expected.

1. Run offloading checks every 10 to 15 minutes. Mentors drift into doing the work. Check for it plainly:

• Who typed the last three changes, and who decided them?
• Could the learner redo the last change alone, right now? If not, undo the drift: hand the keyboard back, or have the learner retype and explain the last block while the mentor only navigates.
• Is the mentor answering their own questions? If a prompt gets no pause before the mentor answers it, the prompts are decoration. Slow down and wait.
• Is the learner only running commands the mentor dictated? Dictation is offloading with extra steps.

1. Fade help inside the session. Start with more support and remove it in steps, following the fading pattern in references/evidence.md:

• First task together: mentor models one full small example while thinking aloud.
• Next: same shape of task, mentor leaves one step blank for the learner to fill.
• Next: learner writes the plan, mentor reviews the plan only, learner codes.
• Last stretch: learner codes alone for a set block while the mentor watches silently except for safety issues, then they review together. If a faded step fails, add back exactly one level of support, not all of it.

1. Close with a solo rep and the lesson note. Before ending, give one small task the learner does alone, live, using what the session covered. Watch, do not help unless they are blocked after a real attempt. Then write the session note together using bin/mentor_note.py, see the Output Contract. Read the next step out loud and confirm the learner agrees it is the right next step.

Worked mini session, validation bug, about 25 minutes:

text
Mentor: Goal is find why empty emails pass, and you learn the trace.
        Before I open the handler, predict: where is the check, browser or server?
Learner: Browser only, I think. The form has a required flag.
Mentor: Good, committed. Let us run it with the browser check removed.
        [Run. Empty email is accepted.]
Learner: So the server never checks. That is the gap.
Mentor: Decision point. Options: add a browser check, a server check, or both.
        Which and why?
Learner: Server, because browser checks can be bypassed.
Mentor: Right. That is your call, recorded. Now you drive. Write the check,
        I will navigate only. Before you run the test, predict the status code.
Learner: 400 with a message.
        [Test run. 400 returned.]
Mentor: Solo rep: add the same pattern for an empty name field, alone.
        I will watch and say nothing unless you are blocked.

Worked mini session, reading unfamiliar code, about 15 minutes:

text
Mentor: Here is a 20 line function neither of us has run. Do not run it yet.
        Predict the output for an empty list, in writing.
Learner: It returns zero.
Mentor: Run it. [It throws.] Where does your model differ from the code?
Learner: I assumed it handled empty. Line 3 indexes the first item directly.
Mentor: Explain line 3 back to me as if I wrote it and forgot why.
Learner: It grabs the first item to seed the total, so empty breaks it.
Mentor: That is a real explanation. Now modify: fix the empty case in the
        smallest change you can, then predict again before running.

Output Contract

• Working code for the session goal, with every decision point either made by the learner or explained why before what at the time it was made.
• A completed session note at the path the pair chooses, created and checked with the bundled tool:

sh
python3 bin/mentor_note.py new --goal "Add input validation to a signup form" --learner "Sam" --role navigator --out session-note.md
python3 bin/mentor_note.py append --file session-note.md --decision "Validate on the server, not only in the browser" --why "Browser checks can be bypassed, the server is the last gate" --prediction "Empty email will return 400 after the change" --result "Confirmed, 400 and a clear message"
python3 bin/mentor_note.py check --file session-note.md

• The note must contain: the goal, the starting point, at least one decision point with its why, at least one prediction and its actual result, the offloading checks, what the learner did alone, and one concrete next step. check fails the note if a required heading or any decision point is missing.
• A stated fading position: what support was removed this session, and what support comes off next session.

Operating Rules

• Explain why before what at decision points. Code typed in silence, explained after, teaches the learner to wait for you.
• Get the prediction before the reveal, every time. No prediction, no run. Write it down when the stakes are more than trivial, memory rewrites predictions after the fact.
• The learner types the learning. If the point of a block is that the learner learns it, their hands write it, even if it is slower. Mentor typing is for modelling one example, not for the whole session.
• Wait after a question. Count to ten silently before rephrasing or answering your own prompt. Fast mentors train learners to wait them out.
• Tell directly when telling is right: a safety or data loss risk, a plain tool fact with no reasoning behind it, or after two real attempts on the hint ladder. Telling without a follow up solo case wastes the tell, so always pair it with a near twin.
• Talk about the code, not the person. "That variable name is vague" lands. "You named that badly" shuts a learner down.
• Keep one goal per session. Park new topics in the note as future goals instead of chasing them live.
• Do not grade the person in the note. Record what was done, what was predicted, what was handed back, and what comes next. No character judgments, no scores the learner did not agree to track.
• If the learner wants speed over learning for a deadline, say the trade plainly, switch to direct help, and mark the note as a delivery session, not a mentorship session. Do not pretend both happened.
• Never invent research numbers in a session. If you cite a study, use the figures and limits in references/evidence.md, or say it is your own practice and why you use it.