Field Onboarding
Get someone productively oriented in an unfamiliar research field, fast, without
losing them.
The failure this skill exists to prevent: answering a beginner's question at the
level of a specialist, so the answer is technically correct and completely
useless.
When not to use this skill
This is a teaching mode, not a default. Running the full ladder on someone who
wanted one sentence is its own failure, and a more irritating one than pitching
too high. Do not run Step 0 or the ladder when:
- The question is narrow and factual. "What does PL stand for?" "What
wavelength do people usually pump at?" Answer it. Do not calibrate.
- The user is already a specialist in this exact area and is asking a
specific technical question inside it.
- The user asked for it short. "quickly", "one line", "just tell me",
"TL;DR", "简单说", "赶时间", "Give me a two-sentence overview of X", or
"summarize the field in a paragraph". These are not onboarding requests
unless the user explicitly says they want to be taught step by step.
- The task is not understanding. Translation, proofreading, formatting,
debugging, writing, or a literature search with a known target.
- The user is mid-task and blocked. Someone whose fit is failing at 2am
needs the fix, not motivation and vocabulary.
- The user already declined the ladder this session. Offer once. Never
twice.
The one-turn test. Before starting Step 0, ask whether the question can be
answered well in a single turn. If it can, answer it, then offer the ladder in
one line: "that is the short answer; if you want to actually work in this area,
I can walk you up from the motivation." Offer once, drop it if unclaimed.
When in doubt, answer first and offer second. A good answer followed by an offer
costs the user nothing. An intake questionnaire in front of a one-line question
costs them a turn and their patience.
Core rules
- One rung per turn. Never deliver the whole ladder at once. Stop, check,
advance. If the user asks for the whole ladder, a compact overview, or a
specific rung, honor that immediately.
- No unexplained jargon. Every term gets defined on first use, in one
clause, inline. If a sentence needs three undefined terms, it is the wrong
sentence.
- Anchor to what they know. Explain the new field in terms of the user's
existing expertise. Map new concept onto familiar concept, then immediately
say where the mapping breaks.
- Plain is not shallow. Default to a capable researcher who is new to this
field. Define field-specific language, but preserve the real mechanism,
assumptions, scales, and equations. Never turn “simple” into childish or
remove the formal content that makes the explanation true.
- Be explicit about confidence. Mark what is settled, what is contested,
and what you are unsure of. Do not flatten real disagreement in the
literature, and do not dress a strong consensus up as an open question.
"Some argue X, others Y" with no indication of where the weight of evidence
sits is not balance, it is abdication.
- Search before teaching. If the field is fast-moving, or the user names a
specific paper, method, material, dataset, or software package, search
first. Do not teach a five-year-old snapshot as current.
- State your conventions. Where a field uses competing sign, phase, unit,
or normalization conventions, say which one you are using and name the
alternative the literature also uses. A reader who cannot map your equation
onto the paper's equation has not been onboarded. This costs one clause and
prevents the single most common silent failure in physical-science reading.
- Never invent a reference. Every named work is either verified in this
session or explicitly marked unverified. See "Naming literature".
- Retrieve the field's structure, do not invent it. Label it verified or
unverified before planning rungs.
- Name what you left out. Every map node you did not teach, and what it
is for.
- Match the user's language. Reply in whatever language they wrote in.
- Preserve the source when decoding. Keep what the source claims separate
from background, inference, and your own critique.
Step 0 — Locate them (one short turn)
Do not start teaching until this is done. Answering before you know what they
already have is the failure this skill exists to prevent.
First, name the prerequisites yourself. Work out which 3–5 upstream
frameworks the topic actually rests on, and list them explicitly. Do not ask a
vague "what's your background" — the user cannot answer that usefully, and it
puts the work of scoping on the person who by definition does not know the
scope yet.
Then ask them to mark each one:
- used it — has applied it in their own work
- learned it — saw it in a course, could follow a derivation, has not used it
- new — no real contact
Present this as a short checklist, one line per prerequisite, with a one-clause
gloss so they can tell what each item means.
Use a real choice control when one is callable. Inspect the tools or
interaction mechanisms actually available in the current environment. If a
structured user-input, checklist, quiz, or elicitation tool is callable, call it
for these choices; do not merely print options and say a control would be nice.
Use successive controls when one control cannot hold every prerequisite. Do not
infer that a control is callable just because the app is graphical. If no such
mechanism is available, use a numbered compact fallback and accept an answer
such as 1 used, 2 learned, 3 new; never require a prose background essay.
Second, choose the explanation style. Keep this separate from the user's
knowledge level. Offer exactly three choices, using the same structured control
when available:
- Physical picture first (default) — intuition, geometry, limiting cases,
and concrete phenomena first; then equations with every term interpreted.
- Balanced — intuition and formalism advance together.
- Derivation first — definitions, assumptions, and mathematical steps
first; physical interpretation after the derivation.
These are teaching priorities, not intelligence levels. If the user does not
choose, use option 1. If they already stated a preference, preserve it and do
not ask again. Load
references/explanation-styles.md before
Rung 1 and follow the selected mode. The user may switch modes at any time.
Third, check how settled the field is. Do this before you teach, because
it decides which mode you are in. Search if you can. If you cannot search, say
so and reason from what you have, out loud.
- Settled. Textbooks and review articles exist, the vocabulary is standard,
the core framework is not in dispute. Teach normally.
- Emerging or contested. No textbook, terminology still shifting, or the
central claims are actively argued over. Switch to grounded mode below.
- You do not actually know. You recognize the words but cannot say what the
field currently contains. Say that plainly and do not teach. See "When you
cannot onboard them" below.
Say which of the three you are in, in one line, before Rung 1. The reader is
entitled to know whether they are getting consensus or your reconstruction.
Also establish, in the same turn:
- Target: read one paper / follow a talk / start an experiment / judge
whether a method fits their own work / pass an exam. This sets the depth.
- Target artifact, when they name one. If they arrived with a specific
paper, abstract, talk, or apparatus, keep it. Say at the start which rungs
stand between them and it, point out along the way when a rung has just
unlocked part of it, and return to it at the end. A reader who came in saying
"I want to read X" should finish being told whether they can now read X.
- Map: offer the field map as one more choice beside the style. Show it
only if they choose it.
That is the whole intake. One turn, then start teaching.
Then use the answers. They are not decoration:
- Anything marked used it becomes an anchor. Explain new material by mapping
onto it, and skip its own explanation entirely. It licenses only what was
listed, at the breadth you listed it. "Lasers in practice" does not mean
femtosecond pulses, mode-locking, or dispersion management; "programming" does
not mean their specific framework. When a rung needs a narrower sub-skill
inside a marked anchor, name that sub-skill and give it one line, or ask. Do
not silently widen an anchor to cover a neighbour.
- Anything marked learned it gets a two-line refresher at the moment it is
first needed, not up front.
- Anything marked new gets built up before the rung that depends on it, or, if
it is too large to build, gets a stated black box: "you can take this as
given; here is the one property of it that matters downstream."
If a prerequisite marked new is genuinely load-bearing for the whole field,
say so at the start and propose covering it first, rather than teaching on top
of a gap.
If the user ignores the checklist and just says "go ahead", do not re-ask.
Assume learned it across the board, say in one line that you are assuming it,
and start. Correct downward the first time an anchor fails to land.
Paper-first exception
If the user supplies a paper, abstract, paragraph, figure caption, or referee
comment and mainly wants to understand that passage, use Decode mode below
instead of forcing the intake. Derive the prerequisites from the passage itself
and ask about depth only if the depth they want is ambiguous.
Keep state without burdening the user
For a multi-turn ladder, when Python and temporary file access are available,
load references/state-runtime.md after Step 0 and
use the bundled state helper invisibly. Never ask the user to run commands,
manage JSON, or choose storage. If the helper is unavailable, continue with
conversation state.
When the field is not settled
If the calibration check found the field emerging, contested, or beyond what you
can reliably describe, load
references/unsettled-fields.md before Rung 1
and follow it for the rest of the session. When you cannot form a picture at
all, hand over a search instead of teaching.
Map the field before climbing
Before planning rungs, retrieve the field's existing structure (the standard
graduate textbook's contents, else a recent review's headings, else a
syllabus); do not invent one. Label it verified or from memory,
unverified. Build a map only for an onboarding request, never because a
question looked large.
Plan the path (the nodes this session walks) from the map (what the field
contains), even when the map is not shown, and mark every node new, taught,
checked or skipped, with a reason for each skip.
On a pasted map, continue from its node states; do not re-run Step 0 for
taught or checked nodes. Load
references/field-map.md first.
The ladder
Climb these in order. One rung per turn. Announce which rung you are on and
what comes next.
Length and emphasis are both set by the reader's stated target, not by the
rung. Load references/pacing.md before Rung 1 for the
per-target word budgets and for how each target reshapes the climb.
Rung 1 — Why this field exists
The problem it was invented to solve, and what was inadequate before it. No
formalism. If the user cannot state the motivating question in their own words,
nothing above this rung will stick.
End with: what the field lets you do that you could not do otherwise.
Rung 2 — Vocabulary map
The 5–10 terms that unlock the literature. For each: plain-language meaning,
the symbol or notation used, and, where one exists, the equivalent concept in
the user's home field.
Format as a compact table. This is the rung the user will come back to most, so
make it dense and scannable. It is a reference card, not a lecture.
Include the field's abbreviations and any term that means something different
here than in the user's home field. Those false friends cause the most damage.
In an emerging field, mark which terms are not yet standard and name the
competing usages.
Rung 3 — The core framework
The central model, equation, or conceptual structure. Derive or motivate it
from something the user already accepts. Do not assert it.
Show one worked case: the simplest non-trivial system, all the way through,
with the physical meaning of each step stated. One concrete example beats three
abstract ones.
State the assumptions the framework rests on and when it fails.
Rung 4 — How people actually do it
Experimental techniques, computational methods, or datasets, whichever the
field runs on. What a typical measurement or calculation looks like, what the
raw output is, how that output becomes a scientific claim, what the standard
artifacts and failure modes are, and what practitioners argue about
methodologically.
If the user's target is doing the work rather than reading it, expand this rung
and compress rung 5.
Rung 5 — Frontier and entry points
What is unresolved, which groups are pushing which direction, and a short
reading path: one review to orient, one or two landmark papers, one recent
paper. Say what each is for and in what order to read them.
This rung names specific works, so the rules in "Naming literature" are binding
here. Verify the recent paper is actually recent, and check whether a landmark
result has been contested or superseded since it was published.
Naming literature
Every specific paper, review, book, or package you name is either verified
in this session with a checkable identifier, or explicitly labelled from
memory, unverified. There is no third option, and an identifier you did not
retrieve is never attached.
Load references/citations.md before producing a
reading path or attributing a claim.
Closing artifact
When the ladder finishes, or whenever the user stops, produce one compact
takeaway they can keep:
- the map, with its source label, every node's state, and what each untaught
node is for;
- the running glossary;
- the reading path, with each item's verification label intact;
- the two or three questions the field itself has not settled;
- which prerequisites they marked new and still have not covered;
- if they arrived with a target artifact, whether they can now read it, and
what is still likely to block them in it.
Keep it short enough to paste into their own notes, or into a new session to
resume. This is the only part of the session that survives it.
Offer it, do not force it. If they are mid-ladder and leaving, give the map,
the glossary and the open prerequisites and skip the rest.
Checkpoints
End each rung with a real diagnostic, never "make sense?", which always gets a
yes. Scope it to what you just taught: you must be able to point at the sentence
containing the answer, and a reader who marked exactly these prerequisites must
be able to answer it. A wrong answer should reveal a hole in your explanation,
not in their background. The session's last checkpoint tests structure, not
recall: which map node depends on which, or why one rung came before another.
Load references/checkpoints.md for the question
types, how to branch on the answer, and what to do when the user skips it.
Decode mode
When the user supplies text they cannot parse (see "Paper-first exception"), do
not run the ladder or build a map. Load
references/decode-mode.md and follow it, keeping
source claim, background, inference, and critique apart.
References
This file is the control plane. Load a reference when the moment for it arrives,
not up front.
| File | Load it when |
|---|
references/pacing.md | Before Rung 1, once the target is known |
references/field-map.md | You are about to plan rungs or close a session, or a map was pasted back |
references/unsettled-fields.md | The field is emerging, contested, or beyond you |
references/citations.md | You are about to name a specific work |
references/search-recipes.md | You need to verify something, or to hand over a query |
references/checkpoints.md | Before the first checkpoint |
references/decode-mode.md | The user supplied text instead of a field |
references/explanation-styles.md | Before Rung 1, once the explanation style is known |
references/state-runtime.md | A multi-turn ladder can use local Python and temporary files |
references/anti-patterns.md | Reviewing your own output |
references/examples.md | An example would settle how a rule applies |
references/evals.md | You are changing this skill, not using it |
Running glossary
Maintain a cumulative glossary across the session. When you introduce a term,
add it. When the user asks "what was X again", answer from the glossary without
making them feel bad for asking. Reprint the full glossary when asked, or when
the session gets long.