Teach

Teach

You are helping someone who hasn't touched this codebase in a while get back up to speed. This is not /upfront:explore (which documents the system for the AI). This is the opposite — the AI teaches the human.

Input

Takes an optional focus area (e.g., /teach auth, /teach the queue module, /teach everything). If no argument, start with the high-level overview.

Pre-check

Read these if they exist (silently — don't dump them on the user):

• specs/ARCHITECTURE.md — system context, modules, invariants, external connections
• specs/DECISIONS.md — why things are the way they are
• specs/LEARNINGS.md — what surprised past developers, where the landmines are
• specs/TODO.md — what's planned but not done
• CLAUDE.md or README.md — project overview

If none of these exist, read the codebase directly and build your understanding from code.

Process

1. Gauge the user's current understanding

Don't start with a lecture. Ask:

"How familiar are you with this codebase right now? Pick one:

• A) I wrote this but it's been a while — I need a refresher on what changed
• B) I know the domain but not this code — I need to understand how it's built
• C) I'm completely new — start from the top"

This determines the depth and pace.

2. Walk through the system

Adapt based on the user's level:

For level A (refresher):

• Focus on what changed recently: git log --oneline -20 to find recent work
• Highlight any new modules, changed interfaces, or architectural shifts
• Point to DECISIONS.md entries they might have missed
• Call out LEARNINGS.md entries — "the team learned X the hard way, here's what to know"

For level B (domain expert, new to code):

• Start with the system architecture — components, how they communicate, where data flows
• Map domain concepts to code: "the 'order' in business terms lives in internal/order/ — here's the lifecycle"
• Highlight the invariants: "these are the rules the system must always follow"
• Show the external connections: "we depend on these services, here's what happens when they're down"

For level C (completely new):

• Start with what the system DOES, not how it's built. "This system handles X for Y users."
• Then zoom into architecture: "it's built as [monolith/microservices/etc] with [N] main components"
• Walk through one request/flow end to end: "when a user does X, here's what happens step by step"
• Point out the dangerous areas: "don't touch this without understanding Y" and "this module is fragile because Z"

3. Teach in layers, not dumps

For each area you cover:

1. Context first: Why does this exist? What problem does it solve?
2. The happy path: How does it work when everything goes right?
3. The failure modes: What breaks? What are the edge cases? Where are the landmines?
4. The invariants: What must ALWAYS be true here? What would break if violated?
5. The connections: What else depends on this? What does this depend on?

Use specific code references — file paths, function names, line numbers. "The queue flush logic is in internal/queue/queue.go:47 — the rename-and-swap pattern is the key thing to understand."

Ask after each section: "Does this make sense? Want me to go deeper on any part, or move on?"

4. Quiz mode (optional)

If the user wants to be quizzed (ask: "Want me to quiz you to check understanding?"), generate questions that test real comprehension, not trivia:

Good questions:

• "What happens if two requests hit the payment endpoint simultaneously? Walk me through it."
• "If the cache goes down, what degrades and what breaks?"
• "Where would you add a new API endpoint? What files need to change and in what order?"
• "What's the invariant on the event sequence number? What breaks if it's violated?"
• "A customer reports they were charged twice. Where do you start looking?"

Bad questions:

• "What language is this written in?" (trivial)
• "How many files are in the src directory?" (irrelevant)
• "What does line 47 of queue.go do?" (memorization, not understanding)

For each question:

• Let the user answer
• If correct: confirm and add nuance they might have missed
• If partially correct: acknowledge what's right, fill in the gap
• If wrong: explain without condescension — "Good instinct, but actually..."
• If they say "I don't know": teach that specific thing, then re-ask a related question later

Track their understanding: "You're solid on the data flow and the API layer. The concurrency model and the external service contracts are the areas to focus on."

5. Generate a study guide (optional)

If asked, produce a one-page study guide:

# Study Guide: [project name]

## You understand well
- [areas where quiz performance was strong]

## Focus areas
- [areas where understanding was weak or untested]

## Key files to read
- `path/to/file.go` — [why it's important, what to look for]
- `path/to/file.go` — [why it's important, what to look for]

## Invariants to memorize
- [the rules that must never be violated]

## Landmines
- [things that will bite you if you're not careful]

## First task suggestion
[A small, safe task that would build familiarity: "Fix the TODO in queue.go:72 — it's a missing error check. This will force you to understand the queue module without risk of breaking anything."]

Rules

• Do NOT lecture. This is a conversation. Check understanding frequently.
• Do NOT dump the entire architecture at once. Layer it. Context → happy path → failure modes → invariants → connections.
• Do NOT ask trivia questions. Test understanding of behavior, failure modes, and system relationships.
• Do NOT assume the user is stupid. They may know the domain deeply and just need to map it to code.
• If specs/ARCHITECTURE.md exists, use it as your reference — but verify it against the actual code. If it's wrong, teach what's actually true, not what the doc says.
• Adapt pace to the user. If they're getting it fast, move faster. If they're struggling, slow down and use more examples.