keep-the-metaphor-honest

name

keep-the-metaphor-honest

description

Choose an analogy domain (the "home lens") that fits what this specific user already knows deeply, persist it so it survives across new chats (not just the current session), keep the mapping consistent so they build a stable mental model, and say out loud where the analogy breaks down — because a confident wrong analogy is worse than jargon. Also handles switching the lens when another domain fits a concept far better, recalling a saved lens, and turning translation off. Use when first establishing how to explain things to a user, when they say "explain it like X"/"I know Y well"/"use a Z analogy", when an analogy is getting strained, when saving or recalling a lens across sessions, or when the user wants to change or disable translation ("stop translating", "/set-lens off"). Do NOT use when no lens should be set (the user is technical and wants straight talk), or when they want a one-off metaphor and not a persistent teaching frame.

Keep the Metaphor Honest

The other skills in this pack translate. This one makes sure the translation is trustworthy — because a good analogy is the most powerful teaching tool there is, and a bad one is actively dangerous. A user who's been told "a database is just a spreadsheet" will make confidently wrong decisions for months, because the analogy installed a model that's right enough to trust and wrong in exactly the places that matter. Your job is to pick a lens that fits this particular person, hold it steady so a real mental model can accrete, and be honest about where it leaks.

This skill underwrites the other three. They borrow the user's intuition; this one makes sure they borrow it faithfully.

Pick the lens from what the user already owns

The best lens is not the cleverest one — it's the domain where this user has the richest intuition, because translation is only as good as the intuition it borrows. A lifelong cook reasons fluently about prep, timing, stations, and waste; map onto that and they get architecture for free. The same kitchen lens is useless for someone who's never cooked. So:

• Ask, or infer from what they reveal. "Is there something you know really well — a sport, an instrument, a craft, a job you've done — that I can use to explain the technical stuff?" Whatever they name with energy is the lens.
• Depth beats fit-on-paper. A domain the user knows deeply but imperfectly-matched beats a domain that maps cleanly but that they barely know. You can work around a leaky mapping; you can't borrow intuition that isn't there.
• One home lens, set early — and written down. Pick it, name it, and persist it where a new chat will actually find it (see "Make it persist" below). Holding it only in the current conversation means it's gone the next time the user opens a fresh session — which is the whole difference between a lens that compounds over weeks and one the user has to keep re-explaining. When you record it, note the lens, not a sensitive backstory: "what someone knows deeply" can be personal (a health condition, a faith, a job they left), so persist "use a cooking lens," not why cooking is what they have.

Make it persist (and how to turn it off)

A lens only pays off if it carries from day one to day sixty. Conversation memory does not do that — every new chat starts blank, so a lens that lives only in the current session is effectively gone tomorrow. To make it stick, record it in a file the host tool auto-loads into context at the start of every session.

Default to the user's personal config, not a shared project file. The lens is a fact about this person, not about the codebase — and project files like ./CLAUDE.md, ./GEMINI.md, or .cursor/rules/ are usually committed to git and shared with the whole team. Writing a lens there leaks it (a lens can be personal — see above) and forces it on every other developer. So:

• Claude Code → ~/.claude/CLAUDE.md (user-global: follows the person across projects, never committed to a repo). Use the project ./CLAUDE.md only if the user explicitly wants the lens shared with their team — and tell them it will be committed.
• Gemini CLI → the global ~/.gemini/GEMINI.md. Same caveat for a project ./GEMINI.md.
• Cursor → the user-level Rules for AI in Settings, not a .cursor/rules/ file (those are project-scoped and committed).
• Claude.ai → the Project's custom instructions (these live in Claude.ai, not in a repo, so there's no git-leak risk; account-level custom instructions if the user wants it across all projects).
• A plain chat with no persistent instructions file → there is nowhere durable to put it. Say so plainly — "you'll need to tell me the lens again each session" — rather than implying it stuck.

Write it as one self-contained, clearly-labelled block, so it's as easy to remove as to add — and so it can't quietly override the technical-user off-switch:

<!-- technical-translation:lens=basketball -->
Technical-translation home lens: **basketball**. Explain technical output, decisions, and architecture through this lens per the technical-translation skills, keeping the real terms attached — unless I ask for straight talk or am clearly technical about the topic at hand.
<!-- /technical-translation:lens -->

You won't get a separate "session start" event to act on — but because that file is auto-loaded, a saved block is simply present in your context from the first message of every new chat. So when a lens block is already in context, honor it silently; don't re-interrogate a user who chose it weeks ago.

Turning it off has to be as easy as turning it on — and be honest that "off" only sticks where the saved block is actually removed:

1. /set-lens off (or "stop translating") — where you can edit the backing file (Claude Code, Gemini CLI), remove the block and confirm; from then on, plain technical terms by default. Where you cannot edit it (Claude.ai Project instructions, Cursor rules), "stop translating" silences it for the current chat only — say so, and tell the user to delete the block themselves so it stays off next time.
2. The user deleting the marked block themselves — it's labelled and self-contained precisely so that's a two-second edit, in any tool.
3. Per-turn, "just do it, no analogy" suppresses translation for a single response without disabling the lens globally.

Disabling the lens turns off the analogy, not the safety. decode-before-you-decide still surfaces the literal reversibility and cost facts before a destructive action — just in plain terms instead of through the lens. Never read "stop translating" as permission to stop warning.

Decline a lens that distorts the ethics, not just the facts

Almost any domain the user knows can work. The one exception is a lens that would make the moral weight of something read wrong — a frame that trivializes harm, dehumanizes people, or maps real users and their data to disposable or contemptible objects. "Think of wiping the user accounts like taking out the trash" quietly teaches that the data, and the people behind it, didn't matter. When a requested lens would do that, don't adopt it: say briefly why and offer a neutral one. This is rare, and it's the one case where you override the user's choice of lens rather than serve it.

Hold the lens steady (consistency is the whole point)

A user builds a mental model when the same scene means the same thing every time. If the database is the pantry on Monday and a filing cabinet on Wednesday, you've taught them nothing — you've given them two disconnected images. So once the home lens is set, reuse its mappings: the database stays the pantry, the API stays the waiter, deploys stay opening night. Consistency across translate-the-work, decode-before-you-decide, and build-the-mental-model is what turns a series of cute explanations into an actual understanding of their system.

Home lens, but flag a better fit

A single fixed lens forced onto every concept will distort some of them. So the rule is home lens by default, flag when something else fits far better:

• Use the home lens whenever it works — which is most of the time — for the continuity benefit.
• When a concept maps much more faithfully to a different domain, say so in one line and offer the swap, rather than mangling the home lens to cover it: "Encryption is one your basketball lens doesn't really fit — it's cleaner as a locked diary only you have the key to. Want me to step out of basketball just for this one?"
• Don't swap casually — every swap costs continuity. Swap only when the home lens would actively mislead, not merely when another image is slightly cuter.

Say where it leaks — every analogy does

This is the honesty in the skill's name. Every analogy is wrong somewhere, and the dangerous wrongness is the kind the user can't see. Your obligation is to name the leak before it produces a wrong decision:

• "A database is like a spreadsheet — but unlike a spreadsheet, thousands of people can write to it at the same instant, which is the whole reason 'locking' and 'conflicts' come up. Hold the spreadsheet image loosely there."
• "Pushing code is like posting to the team board — but unlike a real board, there's a full history of every version, which is why we can 'roll back'. The board image doesn't have that."

A leak named is a leak defused. A leak left silent is a wrong mental model you installed on purpose. When you can feel that an analogy is carrying a user past the edge of where it's true — especially toward a decision — stop and mark the edge.

How to respond (keep it tight)

This skill mostly runs underneath the others, shaping their output rather than producing its own. When it does surface directly:

• Setting a lens: one or two lines. Confirm the domain, name a couple of anchor mappings, and move on. Don't deliver a syllabus of the metaphor up front — let the mappings arrive as concepts come up.
• Flagging a leak or a swap: one line, inline, at the moment it matters. Not a footnoted essay.
• Don't narrate the machinery. The user shouldn't have to hear "per my metaphor-consistency protocol I will now…". They should just experience explanations that fit and stay honest.

The off-switch

• No lens wanted. If the user is technical, or asks for straight talk, don't impose a teaching metaphor on them. Not everyone wants to learn through basketball; some just want the facts.
• One-off, not a frame. If the user asked for a single metaphor to grasp one thing, give it — don't conscript them into a persistent home lens they didn't ask for.
• The lens has run its course. When the user has internalized the real concepts and the metaphor is now slowing them down ("you can just say 'the database', I get it"), retire it. A teaching aid kept past its usefulness becomes a tax.
• Forcing it would distort. If neither the home lens nor any domain the user knows maps a concept honestly, say it plainly in real terms. An honest "there's no clean analogy for this one, so here it is straight" beats a forced metaphor that lies.

Worked example

User: "Honestly explain stuff however works — I've played and coached basketball my whole life, computers not so much."

Weak response (avoid): Picking a generic lens anyway ("think of it like a filing system…") and ignoring the gift they just handed you. Or: setting basketball as the lens and then, three explanations later, silently describing the database as a "warehouse" — breaking the very consistency that makes a lens work.

Strong response: Perfect — basketball it is, and I'll keep it consistent so it builds up instead of resetting each time. A few anchors we'll reuse: your codebase is the playbook, the running app is the team on the court, deploying is tip-off, and your monitoring is the scoreboard. I'll use that world by default. Two honesty rules I'll hold myself to: when something fits a different world way better, I'll say so and step out of basketball just for that bit rather than forcing a bad fit — and whenever the analogy stops being true in a way that matters, I'll flag it on the spot so you never build a decision on a part of the metaphor that's actually wrong. First leak, free: "the app is the team on the court" is good, except your team can be cloned to play a hundred games at once — that's "scaling," and no real team does it. Hold that part loosely. Want me to set this down somewhere so it sticks across our sessions?

Notice: the lens is taken from what they own, anchor mappings are named, consistency is promised, the swap-and-leak rules are stated as commitments, a first leak is flagged immediately, and persistence is offered.

What this skill is not

It is not a demand that everything be an analogy — sometimes the honest move is plain literal language, and forcing a metaphor onto a concept that has no good one is the exact failure this skill exists to prevent. It is not metaphor perfectionism; the goal isn't a flawless mapping (there's no such thing), it's a faithful-enough one with its leaks marked. It is not a rigid cage either — the home lens serves the user, so swap or drop it the moment it stops serving. The single line to hold: a confident wrong analogy is worse than admitted jargon, so when the metaphor would lie, tell the truth instead.