Skip to content

ljx-chase/research-field-onboarding / field-onboarding

field-onboarding

Verified

Guide a researcher step by step into an unfamiliar research field, or decode a paper, abstract, figure caption, or referee comment they cannot parse. Builds understanding in rungs (motivation, vocabulary, core framework, methods, frontier), anchored to what the user already knows, with a checkpoint before each advance. Use when the user says they are new to a field, asks what a research area or method is, says an explanation was too technical, asks to be walked through something step by step, asks for a reading path, or supplies dense research text. Trigger even when the user only names an unfamiliar field or pastes an abstract without asking to be taught. Do not trigger for a one-line summary, a short overview request, or a direct factual answer; do not use it for translation, editing, search, debugging, or specialist questions inside the user's own field. Also trigger in other languages, including Chinese such as 入门, 一步一步讲, 看不懂, 这篇论文讲什么, 帮我理解这个领域.

references/explanation-styles.md

View on GitHub
# Explanation styles

Load before Rung 1. Use physical picture first unless the user has asked for
another mode; Step 0 does not ask, and the end of Rung 1 says they can switch.
The mode controls the order and emphasis of an explanation, not how intelligent
the reader is. Names such as
“Feynman/Griffiths-like” or “Landau-like” are shorthand for these priorities;
do not imitate an author's voice.

## Default register

Unless the user's answers show otherwise, address a **capable researcher who is
new to this field**:

- explain field-specific vocabulary, notation, and tacit assumptions;
- keep the mechanism, relevant scales, boundary conditions, and equations;
- do not reteach general algebra, calculus, or scientific reasoning unless a
  calibrated prerequisite requires it;
- use plain language without baby talk, fake cheerleading, or toy analogies
  that replace the science.

Plain language changes the representation, not the intellectual content.

## 1. Physical picture first — default

Use this order:

1. Name the observable phenomenon or concrete system.
2. Build a spatial, dynamical, geometric, or energetic picture of what changes.
3. State a prediction or limiting case the picture gets right.
4. Introduce the equation as a compact statement of that picture.
5. Interpret every symbol and mathematical step physically.
6. State the assumptions and the point where the picture fails.

Prefer causal mechanisms, diagrams in words, scale comparisons, symmetry,
conservation laws, and limiting cases. Include derivations when they carry
understanding; do not present formulas as decoration or omit them in the name of
accessibility.

## 2. Balanced

Move between picture and formalism in short loops:

1. State one physical claim.
2. Write the mathematical object that represents it.
3. Explain what the equation adds or constrains.
4. Test both on the same worked example.

Do not leave a long block of analogy waiting for its equation, or a long
derivation waiting for its meaning.

## 3. Derivation first

Use this order:

1. Define objects, conventions, assumptions, and the target result.
2. Derive the result without skipping load-bearing steps.
3. Mark approximations at the line where they enter.
4. Interpret the result physically and test a limiting case.
5. Give one concrete worked example.

“Derivation first” does not license unexplained notation or a proof dump. Keep
the logical dependencies visible and say why each step is allowed.

## Correcting a mismatch

Treat style and prerequisite depth as independent controls.

- If the user says **too technical**, keep the scientific claim and equations,
  fill the smallest missing prerequisite, and change representation: add a
  physical picture, limiting case, or worked number.
- If the user says **too basic**, raise the abstraction and compression, skip
  already demonstrated prerequisites, and retain one physical interpretation
  for each central equation.
- If an analogy fails to land, replace it with a different representation; do
  not repeat it more loudly.
- If the user requests a mode change, switch immediately and keep the same
  target and knowledge state.

At a checkpoint, diagnose which axis failed: missing prerequisite, explanation
order, notation, or pace. Change only the failed axis rather than resetting the
whole lesson.
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall