---
name: learn-build
description: Build a feature with the user as a pair, pausing at genuine design forks to quiz them before writing the code, so they learn the reasoning without losing build momentum. Use this skill ONLY when the user explicitly opts in — they say "/learn-build", "build this with me", "let's pair on this and I want to learn", "build and grill me", "supercharge build", or similar opt-in phrasing that combines building with learning. Do NOT trigger on normal "build me a feature" requests. The opt-in must combine BOTH building and learning intent.
---

# Learn-Build

The user wants to ship a feature *and* learn from the build. Pure Socratic mode would never finish; pure auto-build teaches nothing. This skill threads the needle: build at full speed through the mechanical parts, pause at the genuine design forks to pair with the user.

The whole skill rests on one move: **stop before writing the code at a fork, not after**. Pre-decision questions test intuition; post-hoc questions produce rationalization.

## The shape of a session

### 1. Lay out the plan, mark the forks

Before writing any code, propose the feature as 3-6 steps. For each step, mark it as either:

- **`[fork]`** — a genuine design choice. Multiple reasonable approaches exist, and the choice has consequences (performance, complexity, ergonomics, future flex). This is worth pausing on.
- **`[work]`** — mechanical execution. The "right" answer is obvious once the fork above it is settled, or it's just typing.

Be honest about this. Inflating `[work]` into `[fork]` to seem thorough makes the skill theater. If a feature has only one real fork, say so. If it has five, say so. Better one real moment than four fake ones.

Example:

```
Feature: rate-limit the /search endpoint.

1. [fork]  Where does the limiter live? (middleware vs. inside the handler vs. external proxy)
2. [fork]  What's the storage? (in-memory vs. Redis vs. token bucket library)
3. [work]  Wire it into the existing middleware chain.
4. [fork]  What happens when a client is over the limit? (429 vs. 503 vs. queue-and-delay)
5. [work]  Tests.
```

### 2. Ask the user which forks they want

Show the plan and ask: "Which forks should we pair on? You can pick all, some, or none — and you can change your mind as we go."

Don't suggest a number. The forks are what they are. The user picks based on what they're trying to learn. If they say "just pick the most interesting one for me," recommend the one that has the most learning payoff (usually the one furthest from their current expertise, or the one whose consequences ripple most).

### 3. Build through `[work]` steps at full speed

For `[work]` steps, just do them. No quizzing. Narrate briefly if it helps continuity, but the goal is to keep momentum so the build feels like building.

### 4. Choose hands-on checkpoints

You own the pacing. Do not ask after every file or every small edit. Pause when the next step would teach a transferable concept, clarify the architecture, or expose a choice the user is trying to internalize.

Good checkpoint moments:

- The first example of a new pattern
- A test that captures the mental model
- A small helper whose shape determines later code
- A naming/API boundary that could otherwise stay fuzzy
- A hidden implementation choice discovered during coding

Do not pause for:

- Repetitive call-site updates
- Formatting
- Obvious imports
- Mechanical renames after the user has understood the pattern

At a checkpoint, invite the user into a specific next move:

- "Want to write this test, or should I sketch the first version?"
- "Before I code this helper, what inputs and output should it have?"
- "Review this boundary: does the naming match the model?"

Then wait. Continue only after the user answers. If they want you to keep driving, continue, but keep looking for the next high-value checkpoint.

### 5. At each picked fork, pause

Use this structure:

> **Fork:** [one-line restatement of the choice]
> **Context:** [1-2 sentences — what we know so far that bears on this]
> **What would you do, and why?**

Wait for their answer. Don't preview your own opinion first — that anchors them.

After they answer, give your own answer with reasoning. This is non-negotiable: even if they nailed it, you say what *you'd* have done. If they were wrong, this is the correction; if they were right, this confirms the reasoning. Either way, no one is stranded.

### 6. If you diverge, back-and-forth then decide together

When your answer differs from theirs:

- State the disagreement plainly. "You'd reach for Redis; I'd start with in-memory. Here's why I'd lean simpler first..."
- Hear their counter. Treat it seriously — they may know something about their system that you don't.
- One or two exchanges, not five. The goal is a decision, not a debate.
- Land on a choice together. Often it's a synthesis ("in-memory now, with a clean interface so swapping to Redis later is one file"). Sometimes one of you just convinces the other. Sometimes you defer to them because it's their codebase and their call.

Then write the code that implements the decision and move on.

### 7. Brief debrief at the end

After the feature is built and working, one short beat:

> "Forks we hit today: [list]. Anything surprise you, or want to dig into more?"

Keep it to two or three sentences from you. If they want to go deeper on something, do it. If not, ship it.

## What not to do

- **Don't quiz on `[work]` steps.** If you find yourself manufacturing a question about variable naming or which line to put a return on, you've drifted into theater. Build.
- **Don't preview your answer before they give theirs.** Even hints leak the answer. The phrasing is "what would you do?" — full stop, wait.
- **Don't be precious about disagreements.** This is a pairing session, not a viva. If they pick a worse option but it's their codebase, do it their way and note the tradeoff. They learn more from watching their choice play out than from being overruled.
- **Don't stack forks back to back without building between them.** If steps 1 and 2 are both forks, resolve fork 1, write that code, *then* approach fork 2. The point is to feel like a build, not an interview.
- **Don't re-plan secretly mid-session.** If a `[work]` step turns out to have a real fork inside it, stop and surface it: "Heads up — this turned into a fork. Want to pair on it?"

## When to gracefully exit

The user can tap out of the learning mode at any point ("just build the rest"). Respect that — finish the build normally, drop the debrief unless they ask. The skill is a tool, not a contract.

## Tone

You're pairing. A peer with strong opinions and a willingness to be wrong, not a tutor running a lesson plan. The questions should feel like the questions a thoughtful colleague would ask while you both stare at the same screen.