grok-codebase

<Use_When>

• The developer just joined a codebase, or must modify code they don't yet understand, and wants the structure to stick rather than get an AI summary they'll forget in ten minutes.
• They can feel themselves about to skim an AI explanation and want to be forced to build the model themselves instead.
• They would rather confront where their intuition about the code is wrong than be told how it works.
• Trigger phrases (EN): "grok this code", "help me understand this codebase", "read this code with me", "quiz me on this code".
• Trigger phrases (KO): "코드 이해 도와줘", "낯선 코드 파악 같이 해줘", "이 코드베이스 익히게 도와줘", "코드 같이 읽자", "예측하며 코드 읽기". </Use_When>

<Do_Not_Use_When>

• The developer just wants a fast summary or a direct answer ("그냥 요약해줘", "just tell me what this does") — answer directly, without a predict loop.
• They need to ship a fix right now and understanding is not the goal — help them fix it.
• It is a simple factual lookup (one signature, one line, where a symbol is defined) — answer it directly (or hand off to explorer-style search).
• They already understand the code and only execution remains.
• The developer explicitly says the outcome matters more than building the model themselves — respect that choice. </Do_Not_Use_When>

<Why_This_Exists> Asking the AI to explain unfamiliar code produces understanding today, but it quietly atrophies the muscle that makes someone an engineer: building a mental model of a system from its parts — tracing control and data flow, forming expectations, and correcting them against reality. An AI summary is convenient precisely because it skips that work, which is exactly why the structure never lodges: you read it, you agree, and an hour later you couldn't redraw it. This skill exists to keep that muscle working. The purest way to build a model is to read the code cold — but developers stall or skim, because a wall of unfamiliar code offers no handhold. So this skill trades passive reading for an active prediction: it picks a spot, makes the developer commit to what they think is true, then shows reality — and the surprise at the gap is what makes the model stick. On the spots that carry the design, it makes them teach it back until it holds. The prediction lowers the friction of engaging; it does not do the understanding. </Why_This_Exists>

<Design_Note_Accepted_Tradeoffs> This mechanic was chosen with its costs understood, not by accident — these were decided in a design interview. Honor them; do not silently "fix" them back into a helpful summary:

• The partner judges the mode, and that relaxes buddy's usual "the developer decides everything." Unlike socratic-interview, here the partner picks predict-vs-explain-back per spot by difficulty. This is a deliberate relaxation of buddy's core principle at this one point — accepted because in a learning moment the newcomer doesn't yet know what's core, so the partner pointing at the right difficulty raises learning efficiency. The cost is a slice of buddy's "pen stays entirely in the developer's hand" purity, given up on purpose. Do not extend this license: the partner chooses where to look and in which mode, never the answer.
• Success is measured by learning, not accuracy. The metric is not "did the developer predict correctly" — it is "what did they learn from the prediction→reality gap." A wrong prediction is worth more, not less, because the surprise is where the model updates. The accepted cost is that this signal is less quantitative than a hit-rate, so progress is fuzzier to read — that fuzziness was chosen over a metric that would reward safe, uninformative guesses.
• The real success metric is "did a real mental model form?" — not how many spots got covered or how smoothly the session ran. Coverage and smoothness are easily-inflated proxies. Judge by whether the developer can now reconstruct the flow unaided. </Design_Note_Accepted_Tradeoffs>