eli12
Give a curious new teammate a correct mental model of how the code works, in plain language, anchored to real files and symbols. Inspired by poteto/how, tuned for accessibility.
Scope
Infer a bounded scope from the conversation and repository. A broad "explain this repo" can be answered with a stated overview or one representative flow; ask one short question only when materially different targets remain, as with two unrelated subsystems. A question about one function or file is answered directly from that code. If the user mainly wants bugs, risks or critique, explain only enough to ground it, then switch to normal review.
Trace the real path from trigger to effect before explaining; never explain from filenames. Fan out read-only exploration only for questions that span several packages or layers and when independent angles add coverage; otherwise trace it yourself.
Writing it
- Smart new teammate, not a child: plain, concrete, no cutesy tone. Short paragraphs, few bullets.
- Open with the big picture, then the few concepts that matter, then the story from input to output. Teach responsibilities, boundaries and decision points, not line-by-line syntax.
- Define jargon (middleware, idempotent, hydration) where it first appears.
- Name the actual files and symbols so the reader can verify. Say which statements are inferred rather than observed.
- Use an analogy only when it matches the real job of the code and can be tied back to exact symbols at once ("the retry queue is a call-back list at a repair shop: the worker re-enqueues failed tasks with a delay"). Skip analogies for exact algorithms, security constraints and concurrency, where they hide races or limits. If the analogy mismatches the code somewhere that matters, name the mismatch.
- A tiny ASCII sketch (
request -> auth -> controller -> service -> db) when flow or ownership is faster to see than to read.
- End with where to look next when it helps.
Pick only the sections that help from: Big Picture, Main Pieces, The Story, Sketch, Analogy, Where To Look, Sharp Edges.
Gotchas
- Simple is not hand-waving: if retries, caching, feature flags, tenant state or background jobs change the behaviour, say so plainly.
- Listing folders is not an explanation; trace what happens.
- Answer the asked flow first instead of ballooning into an architecture tour.
- If the code is tangled, say so and point to the confusing seams.
- Repository behaviour outranks any analogy; when framework behaviour is unclear, check the installed version or official docs and flag the uncertainty.
1---2name: eli123description: "Explains how a codebase, subsystem or feature flow works in plain language with grounded analogies. Use for 'explain this simply', walkthroughs and mental models. Not for bug triage, code review or code changes."4metadata:5 source: https://skillmd.com/skills/jpcaparas/eli126---78# eli12910Give a curious new teammate a correct mental model of how the code works, in plain language, anchored to real files and symbols. Inspired by [`poteto/how`](https://github.com/poteto/how), tuned for accessibility.1112## Scope1314Infer a bounded scope from the conversation and repository. A broad "explain this repo" can be answered with a stated overview or one representative flow; ask one short question only when materially different targets remain, as with two unrelated subsystems. A question about one function or file is answered directly from that code. If the user mainly wants bugs, risks or critique, explain only enough to ground it, then switch to normal review.1516Trace the real path from trigger to effect before explaining; never explain from filenames. Fan out read-only exploration only for questions that span several packages or layers and when independent angles add coverage; otherwise trace it yourself.1718## Writing it1920- Smart new teammate, not a child: plain, concrete, no cutesy tone. Short paragraphs, few bullets.21- Open with the big picture, then the few concepts that matter, then the story from input to output. Teach responsibilities, boundaries and decision points, not line-by-line syntax.22- Define jargon (middleware, idempotent, hydration) where it first appears.23- Name the actual files and symbols so the reader can verify. Say which statements are inferred rather than observed.24- Use an analogy only when it matches the real job of the code and can be tied back to exact symbols at once ("the retry queue is a call-back list at a repair shop: the worker re-enqueues failed tasks with a delay"). Skip analogies for exact algorithms, security constraints and concurrency, where they hide races or limits. If the analogy mismatches the code somewhere that matters, name the mismatch.25- A tiny ASCII sketch (`request -> auth -> controller -> service -> db`) when flow or ownership is faster to see than to read.26- End with where to look next when it helps.2728Pick only the sections that help from: Big Picture, Main Pieces, The Story, Sketch, Analogy, Where To Look, Sharp Edges.2930## Gotchas3132- Simple is not hand-waving: if retries, caching, feature flags, tenant state or background jobs change the behaviour, say so plainly.33- Listing folders is not an explanation; trace what happens.34- Answer the asked flow first instead of ballooning into an architecture tour.35- If the code is tangled, say so and point to the confusing seams.36- Repository behaviour outranks any analogy; when framework behaviour is unclear, check the installed version or official docs and flag the uncertainty.