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/state-runtime.md

View on GitHub
# Optional state runtime

Use the bundled `scripts/knowledge_state.py` only as an invisible implementation
detail. Never ask the user to run commands, prepare event JSON, choose storage
paths, or understand the state schema.

## Capability gate

Use the helper when all of these are true:

- the environment can run Python 3.10+ and write a temporary file;
- the request has entered the multi-turn ladder rather than Decode mode or a
  one-turn answer;
- keeping explicit state would help across several concepts or rungs.

Otherwise keep state in the conversation and continue normally. Do not mention
the missing helper unless it prevents something the user explicitly requested.

## Storage boundary

Create the state file in a temporary or task-local working directory, never in
the installed skill directory. Treat it as session data. Do not persist it
across sessions, copy it elsewhere, or commit it unless the user explicitly
asks to save their learning record.

The helper never carries the field map between sessions; the closing artifact
does, when the user pastes it back. On a pasted map, initialize a fresh state,
record the map, and restore each node with `mark`.

## Agent workflow

After Step 0:

1. Initialize a session with the target, target artifact, language, selected
   explanation style, and technical register.
2. Set the field status.
3. Add the three or four calibrated prerequisites in dependency order. Use stable,
   lowercase concept IDs.
4. Record the field map, whether or not the user chose to see it: `set-map`
   with its source and label, `add --on-map`
   for each node with its dependencies, then `mark --as skipped --reason` for
   every node off the path. Map nodes take no self-report; skip one the user
   already has. Beyond the map, add concepts only when they become relevant;
   do not attempt to build a universal ontology.
5. Ask the helper for `next`, choose one ready concept on the path, and
   activate it. Each path node is one turn.
6. Teach and checkpoint as required by the main skill.
7. Judge the scientific answer yourself, then record `pass`, `partial`, or
   `fail`. Code routes the result; it does not judge scientific correctness.
   If the user skipped the checkpoint, `mark --as taught` instead.
8. Ask for `next` again. At the end, read `summary` to prepare the closing
   artifact; its `map_states` gives every node's state.

Invoke the helper with the environment's Python executable:

```text
python <skill-root>/scripts/knowledge_state.py <command> <state-file> ...
```

Available commands are `init`, `validate`, `add`, `set-field-status`,
`set-preferences`, `set-map`, `next`, `activate`, `checkpoint`, `mark`, and
`summary`. Run `--help` for exact arguments.

Use `--operation-id` with a stable value when retrying a mutating command. The
same operation ID is applied at most once.

## State semantics

Keep these dimensions distinct:

- `preferences`: explanation style and technical register selected at intake;
- `self_report`: `used`, `learned`, or `new` from calibration;
- `evidence`: `untested`, `pass`, `partial`, or `fail` from checkpoints;
- `progress`: `queued`, `active`, `covered`, or `skipped` for workflow routing.

An item marked `used` starts covered for routing but remains untested. A later
partial or failed checkpoint overrides that shortcut and blocks dependents.

A skipped node carries its reason and never blocks dependents; when a path node
leans on one, state it as a black box. `summary` derives each map node's state
from the dimensions above: `skipped`, else `checked` on a pass, else `shaky` on
a partial or failed checkpoint, else `taught` once activated or covered, else
`new`. A `shaky` node blocks its dependents until a later check passes.
`mark --as checked` and `mark --as shaky` exist only to restore a pasted map;
in-session, checkpoints record them.

Keep the runtime invisible in the response. The user should experience only a
well-paced lesson that remembers what happened.
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