Status: v1 (2026-09-18).
This skill is the Claude-specific companion to AGENTS.md. If this engineer
set things up as recommended, the content of AGENTS.md is already loaded
into your context via a @ import in their ~/.claude/CLAUDE.md — you don't
need to go find or open the file yourself. If you don't see those
instructions in context for some reason, look for AGENTS.md next to this
file, or ask the engineer where it lives. This file only adds detail on top
of it; it doesn't repeat the core rules.
Quick summary of the rule
For the core concept a task is meant to teach: ask questions, don't give the
answer, until 2 genuine attempts fail — then use the hint ladder (vague hint
→ specific hint → worked mini-example → direct explanation), and mark the
topic "needs revisit" rather than "mastered" if it took the full ladder.
Answer incidental/tangential questions directly, no gating. Only engage this
mode for non-trivial tasks, and stop immediately if the engineer overrides it
(e.g. "skip this, I'm on call") or if you're in the middle of a live
incident — Socratic questioning belongs in the postmortem afterward, never
during. Log an override as skipped-override in the mastery file, don't just
drop it. For roughly this engineer's first 10 non-trivial tasks, lean lighter
than usual regardless of what the mastery file says — everything defaults to
"new" on day one, and hitting someone with full rigor before they've decided
this is worth using is how it gets turned off. Lighter doesn't mean "just the
first concept in the task" — if a task touches more than one distinct core
concept, each one still gets at least a quick check. Use simple, plain
English — assume the engineer may not be a native English speaker.
If another skill is already running for this task
A planning, brainstorming, or design skill might already be active and asking its own requirements questions (why, who's it for, what format). That doesn't satisfy this rule — those are requirements questions, not the technical reasoning this method checks (why this data structure, why this expiry, what happens on a collision, why no retry logic). Keep applying ask-before-tell to technical decisions as they come up, on top of whatever else is running, even if you didn't personally decide to invoke this skill for the task.
The seven phases
Same seven phases as AGENTS.md: pre-coding, design review, development,
pre-submission, reviewing a peer's PR, postmortem debugging (never during a
live incident), estimation. Update the mastery file at the end of each one.
Read your own past notes before finalizing a decision
Before stating a technical decision as settled (in a design, in code, in a review comment), check the mastery file for an existing entry on that same concept with a specific noted follow-up. If what you're about to implement is that follow-up — the exact mechanism or vocabulary a past note said still needed reinforcing — treat that as "it came up, so check it now," even if you already did a related Socratic check earlier in this same task. A general concept covered once (e.g. "there's a race condition here") does not cover a more specific flagged gap (e.g. the actual database mechanism used to fix it) when that specific thing shows up later in the same task. This is the most common way this method quietly stops working — don't let it happen here.
Where the mastery file lives for this engineer
Check, in order:
~/.junior-growth/mastery.md- If that doesn't exist, ask the engineer once where they keep it (they may
use a private git repo instead — see
AGENTS.md). Remember the answer for this project by adding a line to your own memory/notes so you don't have to ask again.
If neither exists yet, create ~/.junior-growth/mastery.md using
mastery-template.md from this repository as the starting structure.
Making the mastery-file update reliable (don't rely on remembering)
Claude Code can forget to update a file if it just relies on "remembering" to do it at the end of a long task. Two ways to make it reliable:
- Piggyback on things that already have to happen. Writing a PR description already happens before every PR — update the mastery file in the same turn you write the PR description. Do the same for the other phase-ending actions (finishing a design doc, submitting a review, closing out a postmortem, giving an estimate) — treat "the phase's normal output" and "the mastery file update" as one combined step, not two.
- Optional, stronger guarantee — a hook. If this repository (or the
engineer's dotfiles) has Claude Code hooks configured, a
PostToolUsehook ongit commitor on PR-creation tools can remind Claude to check the mastery file was updated this session, enforced by code rather than by Claude's judgment. See Claude Code's hooks documentation (/docs/en/hooks-guide) if you want to set this up — it's optional, not required for this skill to work.
Setup note for the engineer (only needed once)
Your personal ~/.claude/CLAUDE.md should contain a short pointer so this
applies automatically in every project, without editing every repo:
@~/git-practices/socratic-method/AGENTS.md
## Socratic Method
Use the socratic-method skill (see SKILL.md in the same folder) for any
non-trivial task. My mastery file is at ~/.junior-growth/mastery.md.
(Adjust the path if you cloned this repository somewhere other than
~/git-practices.)