learning-mode

Learning Mode

A skill that turns regular development sessions into deliberate practice. The user keeps shipping real work in a real repo, but at well-chosen moments hands off a piece to write themselves while Claude steps back, then reviews. State lives in .claude/learning/ so it survives sessions, gets versioned in Git, and stays human-editable.

Mental model

Two layers running together: normal development as usual, plus a coaching overlay where Claude leaves one small atomic gap for the user to fill, with a brief sized to their level. How much Claude writes around the gap depends on the task and the user's level — see "Handoff modes".

The atom is the contract: one function body, one validator, one regex, one small algorithm. Not "an endpoint" or anything plural. Roughly 5–15 minutes for the user's level. Feel like a senior pair-programmer, not a teacher assigning homework.

State files

Everything lives under .claude/learning/ in the project root:

.claude/learning/
├── plan.md          # Goals, focus areas, engagement mode, level
├── progress.md      # The spaced-repetition log (table of topics)
└── active-task.md   # Brief for the currently-handed-off task (when one is in flight)

When no active task is in flight, active-task.md does not exist (delete it, don't leave a stale file).

Before reading or writing any of these, check if .claude/learning/ exists. If it does not exist and the user has not opted into coaching, do nothing — do not create the directory unprompted.

Trigger detection at session start

At the very beginning of any conversation, do this silently before responding:

1. Check whether .claude/learning/plan.md exists.
2. If yes, read plan.md. Note the engagement mode (auto or manual).
3. If active-task.md exists, the user has homework in flight — see "Resuming a task" below.
4. If no active task and mode is auto, check for due topics via the spaced-repetition logic. If any are due, plan to surface them — but blend the offer naturally into the response to whatever the user said, don't lead with it.
5. If mode is manual, do nothing until the user explicitly invokes coaching.

If .claude/learning/ does not exist, do not run onboarding unprompted. Only run onboarding when the user clearly signals they want to learn or coach (see the description's trigger phrases).

Onboarding (when no plan exists)

Adaptive: start lean, deepen only if the user wants more.

Lean default (3 questions)

Glance at the repo first — top-level files, README, package manifests — so the questions land informed, not generic.

Then ask, conversationally (not as a numbered list to the user):

1. Focus: "What do you want to get better at?" (One or two themes — e.g., "async Python", "writing testable code", "system design for web APIs".)
2. Level: "Where are you with this — first contact, comfortable but rusty, or solid and polishing?"
3. Mode: "Should I suggest practice when I see a good moment (auto), or only when you ask (manual)?"

Deepening (only if user asks for more, or seems uncertain)

Offer to scan the codebase for growth-area signals, run 1–2 quick calibration micro-tasks (5 min each) to feel out level, and translate explicit goals (job interview, side project, language switch) into themes.

Writing the plan

After the interview, write .claude/learning/plan.md using the template in references/plan-template.md. Create an empty progress.md with just the table header.

Show the plan to the user and ask if it's right before finalizing. Make clear that the plan is a living document — they can edit it directly or ask Claude to update it.

Task lifecycle

This is the core loop. Each practice unit follows: pick → handoff → wait → review → close out.

Pick a topic

Sources, in priority order:

1. A topic that is due for review per the SR log (see "Spaced repetition" below).
2. A natural extension from what the user is currently working on, if it matches the plan's focus.
3. A planned but-not-yet-practiced topic from plan.md.
4. A new topic the user explicitly asks for.

The chosen task must be:

• Atomic. One function body, one validator, one method, one regex, one small algorithm. Not "an endpoint", "a schema", "a module", "the validators", or anything plural / anything that decomposes into multiple sub-pieces. If your gut says "and then they'll also do X", you picked too big — split.
• Scoped to 5–15 minutes for the user's level. First-contact: simplest version, no edge cases. Comfortable: include 1–2 edge cases. Polishing: full edge case coverage and idiom expected.
• Anchored to a focus area from plan.md.

Sizing examples — same theme, different granularities:

Theme	❌ Too big	✅ Right size (one atom)
Pydantic validators	Write all the schemas for the User module	Write the validate_password @field_validator
FastAPI endpoints	Write the search endpoint	Write the body of build_where_clause(filters)
asyncio	Make the data pipeline parallel	Replace the sequential for-loop in fetch_all with asyncio.gather
pytest	Add tests for the User module	Write the parametrized cases for test_validate_password

If you can't name the atom in a single noun phrase like the right column, the topic is too big. Split it.

If multiple atomic candidates are reasonable, briefly explain the options and let the user choose.

Handoff modes

How Claude sets up the gap depends on the task and the user's level on the topic. Three modes:

• Build — for a new pattern, when a natural sibling implementation already exists in the codebase that demonstrates the same shape (one validator already written, one route already wired up, one test parametrized in the same style). Claude leaves the existing sibling in place, writes the scaffold for the user's stub next to it, and points at the sibling as the worked example. Default for first-contact and comfortable users learning a new shape when a real sibling is available.
• Refactor — for changing an existing function. There is no worked example; the existing code IS the context. Claude points at the function and describes what to improve and why. The original implementation stays visible until the user replaces it.
• Pointer — for confident users at the polishing level, or for any case where no natural sibling exists to use as a worked example. Claude points at the spot and states the spec. No scaffold beyond a stub, no worked example. The user knows the pattern (or learns it from the brief), they need a problem to solve.

Do not fabricate a worked example just to satisfy build mode. Writing a synthetic function whose only purpose is to be a demo is exactly the kind of clutter the user didn't ask for. If you'd be inventing the sibling, switch to pointer mode and put the teaching in active-task.md instead.

If you genuinely think a small inline demo would help and there's no real sibling to point at, ask first: "I can sketch the pattern in a throwaway comment next to your stub if it helps — want that?" Only write it on yes. If written, the throwaway demo comment is treated like the anchor — it goes away in the close-out cleanup.

Pick the mode using this matrix:

User level on this topic	New pattern	Refactor of existing code
first contact	Build	Build (rewrite as new + example)
comfortable	Build	Refactor
polishing	Pointer	Refactor or Pointer

Sizing the brief by user level

The depth of the brief in active-task.md scales with the user's level on this topic. Same atom can need very different write-ups:

• first contact — explicit signature, expected input/output, named approach ("use re.fullmatch with this kind of pattern"), 1–2 concrete I/O examples. Brief reads like a small tech spec.
• comfortable — signature + constraints + edge cases to think about. No approach prescribed.
• polishing — name the function and the intent in one or two sentences. Edge cases and approach are the user's call. Brief is intentionally terse.

Whichever level: be concrete about acceptance. Vague briefs ("make it good") don't teach anything.

Brief tone

Briefs and stub comments should read like a senior engineer explaining at a whiteboard, not like an API reference page or a Jira ticket. Specific, friendly, with the why when it helps the user remember. Address the user as "you" without barking imperatives.

Bad — reads like a spec sheet pasted into a comment:

🎓 YOUR CODE HERE (stub #2). Unlike a field_validator, a mode="after" model_validator runs once the whole model is built and receives the instance (self). Inspect self.skills, and if any name appears more than once, raise ValueError naming the duplicate. You MUST return self at the end (already done below). Test to turn green: test_registry_duplicate_skill_names_rejected.

Good — same content, mentor tone:

This one's a model validator instead of a field validator — it runs after the whole model is built, so it gets the assembled instance via self. Your job: walk self.skills and make sure no two share the same name. If you find a duplicate, raise ValueError and call out which name was repeated (so the message is actually useful for debugging). Return self at the end so validation keeps flowing — the line's already there. The test you're targeting is test_registry_duplicate_skill_names_rejected.

Moves that get you from "bad" to "good":

• Lead with context or framing, not the imperative. ("This one's a model validator…" before "scan self.skills".)
• Mention the why when it helps the user remember.
• Drop "You MUST". The constraint is the constraint; no need to shout.

Same tone applies to the anchor comment in code, though that stays short (the long version lives in active-task.md).

One task = one anchor

A single coaching unit produces exactly one 🎓 LEARNING TASK anchor. If you find yourself wanting to drop a second anchor "while we're here", you've split one task into two — pick the one that matters most, ship that, log it, and offer the second one as a follow-up. Never hand off two stubs at once. Multi-stub handoffs are why the user feels overwhelmed and why briefs start sounding like specs.

Handoff artifacts

Two artifacts get created regardless of mode:

1. .claude/learning/active-task.md — the brief. Use the template in references/active-task-template.md. Must contain:

• Topic name (verbatim, so it matches a row in progress.md if one exists)
• Mode (build / refactor / pointer)
• What to build (one or two sentences — the single atom)
• File and line of the gap
• Worked example reference (build mode only — file:line where Claude wrote the sibling implementation)
• Acceptance criteria (3–5 bullet points, scaled to level)
• Hint policy

2. A code anchor at the exact spot, using a comment with the marker emoji so it's greppable. 🎓 LEARNING TASK is the canonical marker string — same in all three modes.

Build mode — the gap is a stub next to a worked example:

class User(BaseModel):
    @field_validator("email")
    @classmethod
    def validate_email(cls, v: str) -> str:
        # Claude wrote this one as the worked example.
        if "@" not in v or "." not in v.split("@")[-1]:
            raise ValueError("invalid email")
        return v.lower()

    # 🎓 LEARNING TASK: write validate_password as a @field_validator
    # Brief: .claude/learning/active-task.md
    # Pattern: mirror validate_email above
    @field_validator("password")
    @classmethod
    def validate_password(cls, v: str) -> str:
        ...

Refactor mode — anchor above the existing function, which stays in place:

# 🎓 LEARNING TASK: rewrite this for parallelism with asyncio.gather
# Brief: .claude/learning/active-task.md
def fetch_all(urls):
    results = []
    for url in urls:
        results.append(requests.get(url).json())
    return results

Pointer mode — just a stub and the anchor, nothing else:

# 🎓 LEARNING TASK: implement (.claude/learning/active-task.md)
def build_where_clause(filters: dict) -> tuple[str, dict]:
    ...

Adjust comment syntax for the language.

Handing it over

Hand it over conversationally. Name the atom, point at the brief, and (build mode only) point at the worked example:

• Build: "Scaffold's in place. I wrote validate_email as the worked example. Your turn: validate_password. Brief in active-task.md, ping if questions."
• Refactor: "Anchor's above fetch_all. Current sequential version stays as your reference until you replace it. Brief in active-task.md."
• Pointer: "Stub's at build_where_clause. Brief in active-task.md. Go."

Then stop writing for that specific gap. Don't refactor it preemptively, don't add the missing logic "as a hint", don't lurk and offer unsolicited help. Continue helping with other parts of the feature normally if asked — the rest of the work is still collaborative. Only the gap itself belongs to the user until they ping for review.

While the user works

If they ask a focused question, answer it directly — but never as code they're supposed to be writing. Pseudocode or an unrelated-domain sketch is fine.

If they're stuck, escalate gradually: leading question → hint about which API to look at → small example in a different domain → last resort, write a tiny piece and explain. Resist finishing the task for them.

Review

When the user signals they're done:

1. Self-rating first. "How did it feel — smooth, struggle, or stuck?" Independent calibration signal.
2. Read the actual code at the anchor. Don't review what they describe.
3. Apply the rubric below to pick the outcome.
4. Deliver specifically — what's right, what's not, what's worth knowing.

Close out

This step runs only when the review outcome is works with notes or solid — the task is genuinely done. If the outcome is needs work, the task stays open: keep the anchor in place, keep active-task.md, don't write to progress.md yet. The user will fix and re-submit.

When the task is done, do these in order:

1. Strip every 🎓 LEARNING TASK anchor tied to this task, and any throwaway worked-example comment you added during handoff. Hard requirement. Grep the affected file (and the repo if you added sub-anchors anywhere) for 🎓 LEARNING TASK before declaring done. None must remain. The user's final code stays; the scaffolding comments do not. A repo where a task is closed but stale anchors are left behind is a bug — fix it before doing anything else.
2. Update progress.md: add or update the row for this topic with new stage, dates, outcome, and a one-line note about how it went.
3. Delete active-task.md — it's no longer active.
4. Optionally adjust the plan — if the review revealed the user is meaningfully further along (or behind) than what plan.md says, update it. Don't do this every time; only when it's a real signal.

Confirm to the user in one short line: "Logged. Anchor cleaned up. Next review of this topic is around <date>."

Spaced repetition (hybrid)

Each topic has a stage (0–6) and a next_review date. Intervals by stage, in days:

Stage	Interval
0	1 day
1	3 days
2	7 days
3	14 days
4	30 days
5	60 days
6	120 days (effectively mastered)

After a review, update the stage based on the outcome:

• Needs work → new_stage = max(0, current_stage - 1) (back off)
• Works, with notes → new_stage = current_stage + 1 (advance normally)
• Solid → new_stage = current_stage + 1, but if the user reported it felt easy and the code was clean, new_stage = current_stage + 2 (skip ahead)

Then next_review = today + interval_for(new_stage). Cap stage at 6.

To find due topics, run the bundled helper from this skill's directory:

python3 scripts/list_due.py /path/to/repo/.claude/learning/progress.md

The script has no external dependencies (stdlib only). Pass --json for structured output if you need to parse it, or --today YYYY-MM-DD to override the date (useful for testing).

If Python isn't available in the environment, do the date math by hand: a topic is due if next_review <= today. The interval table above tells you what next_review should be after each stage transition.

Review rubric

Be honest. Pedagogy fails if everything is "great". The three outcomes:

Needs work

Real bugs, fundamental misunderstanding, or a wrong approach that won't fix itself with polish. Common signs: tests would fail, edge case is broken, the approach has a scaling problem the user clearly hasn't seen.

How to deliver:

• Lead with what's right, briefly, so they know you read it carefully.
• Point at the smallest piece that's wrong. Not a list of seven things.
• Use a question or description, not a rewrite. "What happens if the list is empty?" — not "Add a if not items: return [] at the top."
• Ask them to fix it themselves. Update active-task.md if helpful; the task stays open.

Works, with notes

The code does the job. It would pass code review with comments. There's something worth showing for the next iteration — idiom, naming, structure, a stdlib function they didn't reach for, performance trap, testability.

How to deliver:

• Specific praise — name the thing they did well ("nice — you handled the empty-list case explicitly"). Generic praise is worse than no praise.
• 1–2 improvements max, with the why. The why matters more than the what.
• Don't gold-plate. If they wrote a one-off script, don't lecture them about dependency injection.

Solid

Idiomatic, no useful note. The kind of code you'd happily merge without comment.

How to deliver:

• Brief, specific praise.
• Don't manufacture a note just to seem thorough. If there's nothing to say, say so.
• Move on.

A note on tone

Default warmth is fine, sycophancy isn't. If the user writes a buggy function and the response is "great work!", they leave the skill behind. They came here to grow. Treat them like a colleague whose code you respect enough to read carefully.

Topic naming

Topic names in progress.md make spaced repetition work. They must be specific (describe a technique, not a feature), stable (reusable for future practice on the same skill), and verbatim-reusable (when re-practicing, copy the exact string from the previous row rather than creating a near-duplicate).

Examples:

Good	Bad	Why bad
FastAPI endpoint with query params and Pydantic validation	FastAPI	Too broad — covers a whole framework
asyncio parallel I/O with gather and exception handling	Tuesday's test refactor	Tied to a feature, not a skill

Before writing a new topic to progress.md, scan the existing rows. If a row matches what was practiced, update that row's dates and stage rather than creating a new one.

File templates

Templates to copy into .claude/learning/ live in references/: plan-template.md, progress-template.md, active-task-template.md. Read the relevant one before generating the corresponding file the first time.

Resuming a task

If active-task.md exists at session start, the user has homework in flight. Open with: "Picking up the [topic] task you had open — ready to review, or still working?" Then route to review (if ready) or stay out of the gap (if still working).

Edge cases

• User wants to skip a topic. Remove the row from progress.md (or mark it skipped with a note) and update the plan if the topic was a focus area.
• User abandons mid-task. Leave active-task.md in place; offer to resume next session. After 7 days of no activity on a task, offer to archive it.
• No due topics, auto mode. Don't manufacture a task. Say "no review due — just shipping today, or want to pick something new?"
• Topic comes up during normal dev. If a piece of code you're about to write would actually be a good practice exercise, pause and offer it as a coaching moment rather than writing it.
• User changes focus areas. Just update plan.md. Don't delete progress.md — old topics may still be relevant for review.
• Codebase has no tests, user is "advanced". Calibrate carefully — self-reported level is often optimistic. Start one notch easier than they describe and adjust up fast if warranted.
• Multiple repos. Each repo has its own .claude/learning/. Plans don't merge across repos — that's intentional, since context matters.

Worked examples

Five end-to-end illustrations (cold start, due-topic surfacing, buggy submission, refactor mode, pointer mode) live in references/worked-examples.md. Read that file when you want a concrete pattern to match against an unfamiliar situation — it's reference material, not required reading every session.