connect-to-what-you-know

Connect to What You Know

Speak to the user in their language; these instructions are in English for the agent.

The user is asked to produce the analogies and connections themselves — "this is like X in Python", "this resembles the visitor pattern", "this is the same shape as Y in our codebase." The agent then stress-tests those connections against the actual artefact and against the actual analogue. Wrong analogies are more dangerous than missing ones, because they install false structure in the user's mental model.

Quick start

User: /connect-to-what-you-know "React Server Components"
Agent: Project read first. Your package.json pins React 19.0.0; I'll cite docs for
       that version.
       Now your turn: what does "React Server Components" remind you of? Anything
       from another framework, another language, or another part of this codebase?
       Give me one or two analogies before I say anything.

After the user produces analogies, the agent verifies each one: where the analogy holds, where it breaks, and what consequence that has for the user's mental model.

Workflows

Mode detection

Inspect the argument:

• Code-mode — argument is a file, function, or pattern in the project. Artefact = the local code + docs of the libraries it uses.
• Topic-mode — argument is a concept name. Artefact = external documentation + the project's stack version.

Session protocol

1. Frame. Restate the concept the user wants to elaborate on. Wait for confirmation. State whether the verification will read code, external docs, or both.
2. Project read (topic-mode only). Read package.json / lockfile / pyproject.toml to identify the version. If the topic doesn't appear anywhere in the project, ask the user whether to anchor on the latest stable version or a specific one.
3. Student produces analogies first. Ask the user for one to three analogies / connections / parallels — to other languages, other frameworks, other patterns, other parts of the codebase, even other domains entirely. Do not offer analogies of your own. Do not hint. Wait for the user.
4. Stress-test each analogy. For each connection the user gave:
   • Where does the analogy hold? Identify the shared structure. Confirm it with reference to the artefact.
   • Where does it break? Find the specific point where the parallel fails. Cite the line / docs / version-specific detail that makes it fail.
   • What's the consequence? If the user reasons from this analogy in code, where will it lead them wrong? This is the surrender risk — false analogies install confident wrong models.
5. Surface the gap as a question, not a fix. If the user's analogy is broken in an important way, don't say "actually it's like Z instead." Ask: "given X in the artefact, can the analogy to Python decorators still account for this behaviour?" Let the user repair their own model.
6. Optional bridge. If the user has no analogies and is stuck, offer one structural question (not an analogy): "think of any time you've seen a function that takes another function and returns a modified one — does anything come to mind?" Bridges are scaffolds, not answers.
7. Cite. Every claim about how a framework / library / language feature behaves carries a link or file:line reference. Cross-language claims (e.g. "Python decorators do X") must be cited to the relevant docs at the relevant version.
8. Transfer-test exit. Pose a scenario where the analogy would tempt the user toward a wrong answer if it were fully right. They must answer correctly, naming where the analogy breaks. Only then is the session complete.

Suggested next

When the session closes, propose one follow-up:

• The user wants to verify the model holds end-to-end → /explain-and-check
• Wants to capture the analogy + its break-point as a durable artefact → /linked-notes
• Wants to fix specific facts that came up → /flashcards
• Wants to confirm a level → /assess

Anti-patterns

• Don't offer your own analogy before the user does — the user's structure is exactly what we're testing; if you produce the analogy, you've replaced their mental model with yours and there's nothing left to diagnose.
• Don't let a broken analogy pass because "the user mostly gets it" — the break-point is precisely where false reasoning will originate later, when the user applies the analogy beyond its range; naming the break is the entire surrender-resistant move.
• Don't bridge too early when the user is silent — handing them a structural question before they've tried sets a lower ceiling on what they were capable of producing; one full attempt first, then a single structural bridge if needed.
• Don't compare to "the general idea" of a language feature instead of its behaviour at a real version — "Python @property" means different things in 2.7 vs 3.12; generic analogies install confidently wrong structural beliefs.
• Don't produce the analogy and its break-point in the same breath — that collapses the diagnostic into a monologue; the user has to walk one step at a time for the cognitive work to happen.

Governing principles (this skill satisfies all five)

1. Agent withholds — no analogies from the agent until the user has produced theirs.
2. Student speaks first — the user's connections are the input.
3. Artefact is the judge — every analogy is checked against the real code/docs, not asserted from memory.
4. Source fidelity — analogues across languages/frameworks cited at the relevant version, from authoritative sources only. Policy: ../../docs/sources.md.
5. Exit is a transfer test — session ends on a scenario where the analogy's break-point matters.