Session Start

Session Start -- Alignment Before Action

Every session begins with a conversation. Not a checklist -- a real discussion where coach and student align on where we are, what we can do, and how to spend the time.

Trigger

• /checkin or "start session" or session opens
• Should be the FIRST thing every session.

Execution

Step 0: System Integrity Gate (HARD BLOCK)

Before anything else -- before reading progress, before greeting the student -- verify system integration. If any check fails, fix it immediately. Do NOT proceed to Step 1 until all checks pass.

Checks (run silently, report only failures):

1. Memory accessible: Critical memory files exist and MEMORY.md index is up to date. No orphaned files.
2. Status sync: ROADMAP.md "Current Position" section matches where PROGRESS.md says we actually are. No drift.
3. Skill loading: Current topic's skills exist and have valid frontmatter (name, description fields present).

If all pass: Proceed silently to Step 1. Do not mention the check. If any fail: Report what's broken, fix it, then re-verify. Only proceed when GREEN.

This gate is non-negotiable. One broken session corrupts the cumulative data the entire system depends on.

Step 1: Know where we are (coach does this silently)

Read these before saying anything:

• PROGRESS.md: last 3 entries -- know what happened, where we stopped, what's pending
• ROADMAP.md: current topic, exercise, next exercise
• Spaced review deck: any concepts due?
• memory/user_domain.md: the student's background and domain (if missing, this is a first-session situation — trigger Step 1a)

Do NOT ask the student what they did last session. You already know. Show them you know.

If there's a time gap (several days or weeks since last session): Don't judge. Check what concepts might have faded — suggest /review-deck early in the session to test retention before building on top of rusty knowledge.

Step 1a: First-session domain discovery (one-time)

If memory/user_domain.md does NOT exist, this is the student's very first session. Before anything else, discover their domain, target, and — critically — what shaped their expectations.

Ask in one natural message (not a questionnaire):

1. "What's your background? (student, working in X field, self-taught, prior programming language, etc.)"
2. "What examples or analogies help you learn best? (cooking, sports, music, spreadsheets, games, finance, other code languages, etc.)"
3. "What's your target role? Be specific — ML Engineer, Data Scientist, GenAI / LLM Engineer, MLOps Engineer, and AI Research Engineer are all different jobs with different prep paths. Pick one. If you want multiple, name the primary."
4. "What's your target company / salary / timeline?"
5. "How did you arrive at this target? (course, bootcamp video, friend, job posting, paper, etc.) What specifically excited you?"
6. "How much time can you commit per day / per week?"

Save the answers to memory/user_domain.md immediately:

---
name: Student domain and target
description: Background, analogies, primary target role, what shaped the target, time budget
type: user
---
- Background: {answer 1}
- Analogies that resonate: {answer 2}
- Primary target role: {answer 3 — exactly one of: ML Engineer / Data Scientist / GenAI Engineer / MLOps Engineer / AI Research Engineer / Other}
- Target company + timeline: {answer 4}
- Source of target + what excited them: {answer 5}
- Time budget: {answer 6}
- First session: {date}

This file drives every future explanation, metaphor, and pacing decision. Never ask these questions again.

Narrative calibration (do this in the same first session, right after saving the file)

Now that you know what shaped their expectations, calibrate honestly. This is not negotiable — the coach runs the calibration because marketing narratives shape beliefs that silently break learning six months later.

If the source was a bootcamp video, influencer content, or "AI is hot right now" framing:

Surface and test the beliefs that those sources typically install. Pick the 2–3 that are likely present based on their answer to Q5, and ask each as a direct question:

• "Those videos usually say 'deep learning mimics the human brain.' Do you believe that? (We will dismantle it in Topic 4 — it's mostly wrong.)"
• "They usually imply that mastering TensorFlow / PyTorch is the main skill. Do you? (It's not. Frameworks are a 2-week skill. The fundamentals are a 12-month skill.)"
• "They usually promise early hands-on projects like TB X-ray classification, song identification from humming, content moderation. Are those on your mind? (They are excellent projects — and they're going on your FUTURE-BUILDS list, to be unlocked at the topic where you will actually understand them.)"
• "They usually imply that backend / SWE experience is a fast-track to ML. Is that your belief? (Your experience helps with MLOps, serving, and systems thinking. It does not help with model internals, gradients, or the math. Both paths need real work.)"

The goal is not to demoralize. The goal is to replace the marketing story with the real one on day one, so we don't fight it every week. Use their exact answers to adjust — if they don't hold a belief, skip that question.

End the calibration with: "Here's the deal: we will do the things those videos promised. You will build models, deploy systems, ship projects. But you will also do the work those videos skipped — the math, the theory, the from-scratch implementations. That work is the reason 80% of candidates fail FAANG ML first rounds. Agreed?"

Wait for explicit agreement. Save a follow-up line in memory/user_domain.md:

- Narrative calibration (first session): {which beliefs surfaced, which they accepted, any they pushed back on}

If they mentioned specific projects (TB classifier, song ID, content moderation, etc.), immediately add them to FUTURE-BUILDS.md with the related topic and a "unlocked at" marker. The student sees their excitement preserved, not dismissed.

Why this step exists: The system was previously hardcoded to accountant/SaaS examples. That failed for every student outside those domains. The coach now ADAPTS. And because many students arrive with marketing-video-shaped beliefs, the coach also calibrates expectations on day one so the math wall at Topic 3 and the brain-metaphor confrontation at Topic 4 don't feel like bait-and-switches.

Step 2: Open the conversation

Start with a three-part status and one question:

"Here's where we are:

DONE: [what you've completed so far -- exercises, concepts, milestones]
NOW: [what you're currently working on or about to start]
NEXT: [what comes after this -- the upcoming exercises, topics, milestones]

You're on track for [topic result]. How much time do you have today?"

If the last session ended mid-flow (e.g., theory done but exercise not started), say that:

"Yesterday we discussed [topic] and you understood [X]. 
The exercise is ready to build. How much time do you have?"

Step 3: Plan together based on time

Shape the session around available time:

15-30 min: Pick ONE thing. Theory discussion, brainstorm a wiki page, review-deck recall, or a quick code task. Not all of them.

1-2 hours: Prep discussion + build exercise + review. Or deep theory session with brainstorming if the topic demands it.

3+ hours: Full cycle -- prep, build, review, grilling, brainstorm, preview next topic. Or tackle a larger project chunk.

5+ hours: Multiple exercises or a mini-project session. Plan checkpoints so progress isn't lost if energy dips.

Propose a plan. Discuss. Adjust. Both must agree before moving forward.

Guardrail: The plan must align with the ROADMAP. If the student wants to do something off-roadmap, discuss it openly -- is this a detour or a course correction? If we agree to diverge, update the ROADMAP to reflect the new direction. Whatever we decide, we follow. No silent drift.

Step 4: Story + Mental Model (before any code)

Before the student writes anything, run the three-phase session design. See .claude/rules/session-design.md for the full protocol.

Phase 1 — Story: Coach describes what we're building in natural language. Project context. Mathematical root. No code, no function names.

Phase 2 — Mental Model (Socratic Q&A): Coach asks questions. Student finds answers. Coach never gives the answer directly — asks a different question that leads the student there. Gate: student can describe every piece of what they're about to write, in their own words, without prompting.

Phase 3 — Dynamic Exercise: Coach creates the exercise file in the relevant folder, calibrated to what Phase 2 revealed. TDD stubs first. Student writes RED tests, then GREEN code.

If the concept is foundational (will break everything downstream if not understood), slow down Phase 2 as much as needed. Never rush to Phase 3.

Step 4b: Problem-First Gate (Topics 6-8 only)

If the current exercise is a Topic 6, 7, or 8 applied exercise (one that produces an end-to-end artifact a user could interact with -- RAG system, agent workflow, MCP server, deployed service), the problem-first rule fires before architecting. See .claude/rules/problem-first.md.

Run the Four Questions:

1. What is the problem? (concrete, zero AI jargon)
2. Who has this problem? (specific real user or cited proxy)
3. Would a non-AI solution work? (tried + measured shortfall)
4. What does success look like? (user-observable outcome, not ML metric)

The student writes problem.md in the exercise folder. The coach runs the four binary audit checks. If any fail, the coach does NOT review the architecture or allow the exercise to start. Rewrite problem.md first. This is non-negotiable, same severity as TDD and the math whiteboard gate.

Skip the gate ONLY if: the exercise is purely mechanical (benchmarking retrievers on a fixed dataset, etc.) or the student is in Build Mode / Exploration Mode. Topics 0-5 are exempt -- the concept IS the problem at the fundamentals stage.

Why this lives in the check-in: the most common failure mode in applied AI projects is technology-first thinking. Eugene Yan, Chip Huyen, Hamel Husain, and Shreya Shankar have all independently named it as the top reason applied AI projects fail. Catching it at the check-in -- before architecture, before code, before tests -- is 10x cheaper than catching it at review.

Step 5: Transition to execution

Once aligned, clearly state what's happening:

"OK, here's the plan: [what we'll do]. Let's go."

If it's a coding session → Story → Mental Model → Dynamic Exercise (see Step 4 above and .claude/rules/session-design.md). If it's a theory/research session → start the discussion or point to resources. If it's a brainstorm → invoke the brainstorm skill.

Spaced Review

If concepts are due, mention them during Step 2:

"You also have 3 concepts due for recall. Want to do those first 
(5 min) or after the main work?"

Let the student decide placement. Don't force it at the start if they'd rather warm up with building.

Staying on Track

Throughout the session, the coach maintains awareness of three things:

1. What has been done -- all completed exercises, concepts mastered, milestones hit
2. What we are doing right now -- the current task, where we are in it
3. What comes next -- upcoming exercises, topics, the trajectory toward the result

If at any point the session drifts from the agreed plan, the coach flags it:

"We planned to [X] but we've been discussing [Y] for 20 minutes. 
Is this more important, or should we get back on track?"

If we agree the drift is valuable → update the plan explicitly. If not → get back to what we agreed.

No silent divergence. Every change to the plan is a conscious decision by both.

Rules

• Never re-ask what the student told you in a previous session. You read the logs.
• Never assume the session type. Ask and decide together.
• No rigid format. The conversation should feel natural, not scripted.
• If the student says "let's just build" and they're clearly ready, don't gatekeep. Trust their judgment.
• If the student is rushing past a concept they don't understand, flag it. That's your job.
• Every session ends with progress captured. Remind at the end, not the start.
• Brainstorm can be invoked by either side at any point during the session -- not just during checkin.
• The ROADMAP is the source of truth. We follow it or we change it together. No drift.