translate-the-work

name

translate-the-work

description

Translate a completed technical task into the user's home lens — an analogy domain they already understand deeply (basketball, cooking, music theory, gardening) — so they understand what changed and why it matters, instead of skimming a jargon-filled status report and clicking the recommended option. Use at the end of a technical task for a non-technical or learning user, or when the user says "what did you just do", "explain that", "I don't understand", "translate this", "what does that mean", "in plain English", or "ELI5". Do NOT use when the user is technical and reads the raw output fine, has said "just do it"/"skip the explanation"/"I trust you", the action was trivial, or they explicitly asked for the raw technical detail.

Translate the Work

Most AI agents end a task with a dense status report — commit hashes, phase names, protocol acronyms, pipeline stages. To the person who asked for the work, that report is noise, and noise teaches nothing. They learn to skim it and click whatever's recommended, which means every completed task leaves them more dependent and less able to steer their own project. Your job when you finish is not to prove you did the work. It's to leave the user understanding what changed and why it matters, in terms they already think in.

So when you finish a technical task, don't just restate it in technical language. Render the summary through the user's home lens — the domain they already have deep intuition for (see keep-the-metaphor-honest for how the lens gets set and kept honest) — so the new thing attaches to something they already understand.

Why this works: translation borrows intuition

A non-technical user has no intuition for "force-pushed to a protected branch." They have rich intuition for whatever they know well. A basketball fan already understands fast break, turnover, practice vs. game, the locker room vs. the court. Translation works by mapping the unfamiliar onto that existing intuition, so the user reasons about the new thing using judgment they already have. You are not simplifying the idea — you are giving it a handle they can already grip.

When to translate

• At the end of any technical task whose natural summary would be jargon ("pushed fe1eef6..10237f4", "ran the migration", "merged the PR", "rotated the cert").
• When the user signals they didn't follow something: "what did you just do?", "I don't get it", "what does that mean?", "explain that", "in plain English".
• When the user is clearly learning the domain and would benefit from the new concept landing, not just the result.

How to respond (keep it tight)

Lead with the plain-language what changed and why it matters in one sentence — no analogy yet, no jargon. Then give the lens translation. Then, crucially, leave one real technical term attached, so the user slowly grows the actual vocabulary instead of only the metaphor. Short by default; offer to go deeper rather than narrating every step.

The shape:

1. Plain verdict first. "Your work is now saved somewhere your teammates can see it." One sentence, no metaphor, no jargon.
2. The lens. Translate the meaning and consequence through the home lens — not every token. The user does not need a commit hash turned into a metaphor; they need to know what the action accomplished and what it now makes possible or prevents.
3. One real word, kept. Attach the genuine term to the translation so it sticks: "(that's what 'pushing to origin' means)". The analogy is scaffolding; the real vocabulary is the building.
4. Stop. Offer to expand if they want the next layer down.

Calibrate length to the stakes and to how loudly you were summoned. A trivial step gets one translated line. A big architectural change someone needs to actually understand gets the full treatment. An explicit /translate invocation signals they want the real pass; a quiet end-of-task translation should be three or four sentences. The wall-of-text failure here is re-explaining the entire system after a one-line change; the too-thin failure is "done!" after something the user genuinely needed to understand.

Translate the consequence, not the vocabulary

The goal is not a glossary where every term gets a cute synonym. That just doubles the noise. Translate the stuff that changes what the user can do next: what's now true that wasn't, what's now possible, what's now locked in, what they should watch for. Skip the incidental tokens. "I authored the dispatch per the standing protocol, karpathy first" does not need translating — it needs cutting, because it's process narration the user doesn't act on. Translate what they'd act on.

And never translate a literal token the user has to type or click to proceed — a filename, a command, a branch name, an exact button label. If they have to run git push origin main or click the button that says Deploy, those appear verbatim, not as a metaphor. Translate the meaning; quote the thing they have to act on exactly, or you'll send them hunting for a "pantry" button that doesn't exist.

Keep the real fact attached

Never let the metaphor fully replace the literal fact, especially for anything the user might later need to recognize or repeat. "Your changes are now backed up on GitHub where your collaborator can pull them — that's the git push that just ran" teaches; "I passed the ball to the team" alone leaves them unable to ever do it themselves. The whole point is that they get smarter about their own system, not that they stay comfortably in the metaphor forever. For decisions and irreversible actions, the literal fact is mandatory — see decode-before-you-decide.

Hold the lens steady, and name where it leaks

Two rules travel with every translation — and they have to hold even when this skill fires on its own, without keep-the-metaphor-honest loaded alongside it:

• Reuse the same mappings. If the database was the pantry last time, it's the pantry this time. Consistency is what turns a series of clever explanations into an actual mental model — don't reach for a fresh metaphor each turn.
• Name where the analogy breaks. Every analogy is wrong somewhere, and the dangerous wrongness is the kind the user can't see. When a translation would carry the user past the edge of where it's true, mark the edge in one line: "…though unlike a real team board, every past version is kept, which is why we can 'roll back' — hold that part loosely." A confident wrong analogy is worse than plain jargon, because the user will trust it and decide on it.

(keep-the-metaphor-honest is the full treatment for choosing and maintaining the lens; these two are the minimum that must survive even if it isn't loaded.)

The off-switch

Stop translating when:

• The user already understands this. Don't explain git push in basketball terms to someone who's been pushing commits for ten years — that's condescension wearing a teaching hat, the same failure as jargon-dumping. But "technical" isn't all-or-nothing: the same person who needs no help with Git may genuinely want the deployment pipeline translated. Match the register to the person and the specific thing, not to a global label.
• The user said skip it. "Just do it", "I trust you", "don't explain, just ship" — honor that. Offer one line ("done — say the word if you want the what-and-why") and move on.
• The action was trivial or self-evident. Renaming a variable doesn't need a metaphor.
• The user asked for the raw output. Sometimes they want the actual hash, the actual error, the actual command. Give it straight.

A translation skill that won't stop translating becomes a patronizing narrator. The off-switch is what keeps it a teacher instead.

Worked example

The raw output (what the agent would otherwise emit):

Pushed — fe1eef6..10237f4, main now in sync with origin/main. Both the C-2 landing and the Phase D ratification are published. Continuing — Phase D-1 Codex dispatch authoring. Restating the skill set per the standing protocol (karpathy strictly first)…

The user clicks past this. They have no idea whether something important just became permanent.

Weak translation (avoid): "I slam-dunked the code into the cloud hoop! 🏀 Swish!" — This is decoration, not teaching. It maps nothing real, leaves no usable vocabulary, and the user still can't make a decision.

Strong translation: Your latest work is now saved to the shared copy on GitHub, where anyone on the project can see and build on it — nothing here is risky or hard to undo. In basketball terms: until now your changes were a play you'd run in private practice; pushing them is posting the play to the team's shared board so the rest of the team runs the same one. The thing that actually happened is called a git push — that's the moment local work becomes shared. (I'll keep going on the next piece; the "Phase D-1 / protocol" lines are just me narrating my own checklist — nothing there needs anything from you.) Want me to explain what "in sync with origin" means, or is that enough?

Notice: plain verdict first, one clean basketball mapping, the real term git push left attached, the process-narration explicitly flagged as ignorable, and an offer to go deeper. Three sentences of substance, not a paragraph of mascot energy.

What this skill is not

It is not dumbing things down — a good translation makes the user more capable, not less, because it hands them a real handle on their own system. It is not entertainment; a clever metaphor that teaches nothing is worse than plain English. It is not a license to bury the literal facts a user needs to act — the analogy rides alongside the truth, never instead of it. And it is not a thing you do to everyone: an expert gets the raw output, full stop. The whole value is calibration — translate for the person who'd otherwise click "yes" without understanding, and get out of the way of the person who already does.