---
name: field-onboarding-map
description: Build adaptive, source-grounded systems for entering, learning, and acting in unfamiliar or changing fields. Use when the user wants to clarify purpose and real problem awareness, acquire field-appropriate sources, synthesize problems, build or revise a problem-driven map, study a chapter or node, anchor knowledge in usable reality, execute a domain task, externalize or resume long-term state, or improve such a system from feedback.
---

# Field Onboarding Map

## Aim

Help the learner and agent enter a field from a real purpose, discover its
actual problems and sources, form a usable map, learn or act through reality,
and continue from an externalized working system that improves with evidence.

Use this as the default whole-system loop:

```text
Purpose -> initial problem awareness -> source acquisition
        -> source-revised problem awareness -> problem synthesis
        -> map construction -> chapter study or real task
        -> external feedback -> local revision -> external memory -> next loop
```

This is a lifecycle and default assembly, not a checklist for every answer.
Enter where the user needs, stop at explicit stage boundaries, reuse valid
prior state, and fuse or skip work when its cognitive result already exists.

## Stable Kernel

- Start from enough Purpose, context, or target artifact to choose well.
- Use initial problem awareness as a provisional search hypothesis, not as the
  final structure of the field.
- Acquire sources from where knowledge, competence, failure, and feedback
  actually live in that field.
- After source acquisition, state what the evidence kept, revised, removed, or
  added before constructing a confident map.
- Build maps from problems, capabilities, mechanisms, tensions, relations, and
  failure modes rather than a textbook or resource directory.
- Connect active concepts to usable anchors: when to call them to mind, how to
  operate with them, where they transfer, and what feedback tests them.
- Treat external feedback as revision pressure; change the smallest sufficient
  layer and keep unaffected regions stable.
- When continuation matters, maintain one compact canonical state that another
  session can read and use without hidden chat.
- Keep learner-facing output lighter than the investigation and control system.

A narrow explanation, one source, a bounded review, or a one-off fix may end
without a map, action plan, revision record, or state. Do not manufacture
downstream work to display the loop.

## Four Quality Gates

Judge the system through four gates rather than document completeness.

### 1. Source Fit

Did the agent search in the right places for this field, use field-appropriate
quality criteria, inspect concrete sources or artifacts, expose limitations and
lineage, and stop when another source would not change judgment?

### 2. Problem Synthesis

Did sources materially improve problem awareness? Preserve the useful
comparison between initial and source-revised awareness, then form a small set
of problem threads that explain required capabilities, mechanisms, failures,
feedback, and map regions.

### 3. Map And Anchor Quality

Do important nodes exist for a reason, use meaningful relations, guide a
current path, and connect to faithful, operable anchors with activation cues,
feedback, boundaries, and transfer directions?

### 4. Adaptive Improvement

Does feedback update the correct source judgment, problem, anchor, map node,
artifact, learner evidence, or Purpose? Does the system preserve rollback,
resume correctly, and become more useful without accumulating universal rules
from one success?

Failure at an earlier gate limits downstream claims. A polished map cannot
repair weak sources; more state cannot repair a decorative map.

## Resource Ceiling

Treat context, tool calls, latency, attention, cost, files, map nodes,
renderers, state copies, coordination, and future maintenance as one resource
envelope. Preserve honesty, decisive evidence, the requested artifact, and
consequential checks first.

Keep one current truth, one identity per reusable object, active-branch reads,
delta-first writes, and no permanent support artifact for one-off work. Add a
renderer, store, file, or control surface only when it changes inspection,
action, transfer, risk, or recovery; compress it when reading the control costs
more than reconstructing the work.

Let [runtime-loop.md](references/runtime-loop.md) own allocation and graceful
degradation during a run. Let [map-and-state.md](references/map-and-state.md)
own the persistence growth gate and pruning rules. Do not restate their full
decision procedures in other functions.

## Model Freedom Contract

The skill supplies strong defaults and proven functional assemblies. It does
not prescribe the model's hidden reasoning or freeze output shape.

A capable model may:

- fuse stages when their distinct results remain inspectable;
- skip a stage when valid state already supplies its exit evidence;
- invent a better representation, tool arrangement, or action;
- compress visible scaffolding after fresh no-scaffold performance preserves
  the four gates;
- restore scaffolding after failure, interruption, novelty, coordination need,
  or higher consequence.

When the active stage, a load-bearing claim, or consequence requires them, it
may not bypass actual source inspection, external feedback, safety checks, or
uncertainty merely because the answer is fluent. Skip the form, not the
cognitive protection the form was meant to provide.

## Functional Assemblies And Boundaries

Use intuitive functions when a packaged default helps:

- `full-map`: run enough of the whole loop to form a grounded, usable field
  system; stage it when source burden makes one-shot mapping shallow.
- `stage-only`: perform one named stage, write only its real result and minimal
  state delta, then stop.
- `chapter-study`: study one positioned node through adaptive explanation,
  comparison, use, mastery, parent recheck, and state update.
- `learning-note`: create or update a usable learning note from grounded study,
  preserving problem awareness, structure, boundaries, activation, and
  retrieval without treating the note as mastery or a second state.
- `task-build`: start from a real artifact or decision, acquire only blocking
  domain structure, build and check the result, then preserve reusable gains.
- `resume`: read canonical state, check staleness and readiness, choose the next
  valid function, and update the same state rather than restart.
- `review`: identify the failed gate or cognitive job and prescribe the
  smallest repair and downstream update.

Honor `first`, `only`, `before mapping`, `do not build`, `continue from state`,
and equivalent boundaries. `learning-note` produces or updates a note; it is
never another name for `resume` or state storage.

Use [runtime-loop.md](references/runtime-loop.md) for stage contracts, packaged
function routing, adaptive dynamics, and resource decisions.

## Sources, Maps, Action, And Memory

Use [evidence-ecology.md](references/evidence-ecology.md) for source
acquisition, internal source-ecology diagnosis, verification, lineage,
freshness, acquisition, and stopping.

Use [map-and-state.md](references/map-and-state.md) as the sole owner of map
semantics, external-memory layers, canonical `Field State`, `Revision Delta`,
storage projections, resume, and pruning. Do not invent a competing state or
revision schema. Agent-stored knowledge is not learner-demonstrated mastery.

Use [execution-and-routes.md](references/execution-and-routes.md) for usable
anchors, action design, task-embedded work, mastery, transfer, and field-shaped
action adapters.

Use [chapter-study.md](references/chapter-study.md) only for structured study of
one chapter, map node, mechanism, text, subsystem, tool, API, command family,
term, or concept cluster.

Use [learning-note.md](references/learning-note.md) only when the user asks to
create, improve, explain through, or update a learning note.

## Feedback, Review, And Safe Amplification

Reflection proposes a diagnosis; tests, primary or independent sources, real
artifacts, people, users, and environment response provide stronger correction.
Never claim search, inspection, comparison, testing, delegation, feedback, or
review that did not occur.

Use [review-and-evolution.md](references/review-and-evolution.md) for failure
repair, experience promotion, rule lifecycle, and explicit skill maintenance.
Separate three speeds of amplification:

1. verified feedback may immediately update project-local map, anchors,
   tactics, and state;
2. repeated conditional success may update the user's or project's preferred
   assembly without becoming universal;
3. only an explicitly requested maintenance run may patch the installed skill
   after target, contrast, mutation, overhead, and lighter-scaffold tests.

Ordinary use must not silently edit the skill, export private project data, or
promote one tactic globally. Stronger-model success is evidence for fading a
scaffold, not forcing it back.

## Progressive Loading And Delivery

Start with this kernel. Load only the owner needed for the active decision;
most runs need zero to two references. Never preload evaluation expectations
into an actor. Evaluators may load
[evaluation-scenarios.md](references/evaluation-scenarios.md) after fresh output
exists.

Show the requested result, not mode labels, ledgers, state fields, repositories,
or agent structure. Use Mermaid when relations or deltas become easier to
inspect and HTML only when filtering, search, layering, or interaction adds
real value. Representation and storage are replaceable projections.

Before the first package edit in each explicit optimization cycle, create and
verify an external milestone of the actual working tree. After edits, run
`scripts/audit_skill.py`, the skill-creator `quick_validate.py`,
`git diff --check`, and the smallest relevant fresh target and contrast tests.
Structural validation is necessary but not behavioral proof.