| name | eli5 |
| effort | max |
| description | Explain current work plainly for a teammate without recent context, defining mechanisms and removing task-specific shorthand. |
| argument-hint | ["topic","or empty = \"what we're doing right now\""] |
/eli5 — Explain Like a Teammate Just Walked In
Keywords: eli5, explain, plain, lost, context-drift, jargon
The user has only general project knowledge — what the project and its top-level packages ARE. Nothing else from the last N minutes of your work. Reset to that floor.
The 4 rules
- Mechanism, not option name. ❌ "we could enable singlePassLayout." ✅ "the framework currently runs layout → re-renders → runs layout again until stable. The option would force one pass."
- Define names on first use. "the cascade", "the feedback loop", "Suspect 3",
Content.tsx — gloss on first mention even if it's the 20th time you've thought it.
- Numbers, not adjectives. "200 violations", not "still many". "1 second", not "briefly". "70% drop", not "big improvement".
- One screen, ~25 lines. If it doesn't fit, drop secondary detail. Pick the load-bearing parts.
Structure (when explaining problem + options)
What's happening: mechanism — 2-3 sentences
What I did: change + concrete result
What's left: remaining mechanism
Options, plainly: (a) <name> — what it changes, tradeoff
(b) ...
Recommendation: 1 sentence
For a simple question, just write prose under "What's happening" and stop.
Before / after (a real one)
❌ "Should I (a) try singlePassLayout, (b) hunt the 336-wide text, or (c) audit useBoxRect call sites? Suspect 3 didn't pan out and AsideLayout was reverted."
✅ "The remaining churn is the rendering framework doing layout, then re-rendering, then doing layout again until things settle — call this the cascade. Three angles:
- Force one layout pass — the framework has a setting that runs layout exactly once. Risk: components that read their own size get 0 on first paint.
- Find the long unwrappable text — one chat element measures 336 columns wide inside an 85-column parent. Adding
wrap="wrap" fixes that one leaf.
- Reduce measurement reads — every measurement-hook call is a re-render trigger. We have 3; some may be redundant."
Self-trigger when you catch yourself
Writing any of these in user-facing text → stop, run /eli5:
- "the X fix" / "the Y change" — name what changed mechanically
- "Suspect N" / "Phase N" / "Attempt N" — your enumeration isn't theirs
- "Per the diagnosis" / "Per the bead" — they haven't read it
- A bare file path — gloss it ("
Content.tsx — the chat-layout file")
