onboard-deepen
Skill0 starsChanged 4 months agoMITView on GitHub
Phase 2 of 3 in the onboard chain (map → deepen → digest). Runs targeted deep reads, via durable explore-role quests, of the hotspot files the map phase surfaced — how core modules work, key data flows, and non-obvious conventions — and optionally records durable facts via the fairy-tales memory `remember` tool. Trigger when the previous phase says "run onboard-deepen next", or standalone via "onboard-deepen", "phase 2 of onboard", "deepen the repo map", "read the hotspots".
In this repository21 other files it gives its agents.
- bughunt-diagnoseSkill
- bughunt-fixSkill
- bughunt-reproSkill
- bughunt-verifySkill
- feature-ship-buildSkill
- feature-ship-reviewSkill
- feature-ship-shipSkill
- feature-ship-specSkill
- migrate-inventorySkill
- migrate-transformSkill
- migrate-verifySkill
- onboard-digestSkill
- onboard-mapSkill
- release-bumpSkill
- release-changelogSkill
- release-publishSkill
- release-tagSkill
- release-verifySkill
- research-artifactSkill
- research-gatherSkill
- research-synthesizeSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
All chain state is managed by the chain tool: authoritative JSON at .pi/fairy-tales/chains/onboard/state.json with a human-readable …
- Very specific: line 34
Call the chain tool with action: "status", chain: "onboard" (a legacy .onboard-state.md from an older version is imported automatically):
- Very specific: line 37
If there is no run → abort: "No onboard run found.
- Very specific: line 38
If the run is not active with currentPhase: "deepen" → abort: "Expected the run to be at phase deepen but it is at <currentPhase/status>.
- Very specific: line 41
If data.hotspots (or the map phase summary) is missing → abort: "Phase pointer looks right but the Phase 1 output is missing.
- Very specific: line 44
If the tool reports the chain is locked by another session, abort.
- Distinctive: line 91
Call the chain tool:
- Distinctive: line 109
After completing this phase, output exactly:
- Distinctive: line 114
Do not start the next phase.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Onboard: Deepen
Chain version: 2 (durable state contract — see docs/STATE-CONTRACT.md)
Phase 2 of 3: onboard-map → onboard-deepen → onboard-digest
Overview
Takes the hotspot list produced by onboard-map (data.hotspots) and reads those
files deeply — not just structurally — to understand how the core modules actually
work, trace the key data flows through them, and catch conventions that aren't obvious
from file names alone. Where a fact is durable enough to matter beyond this session, it
is recorded with the fairy-tales memory remember tool so future sessions on this repo
start ahead.
All chain state is managed by the chain tool: authoritative JSON at
.pi/fairy-tales/chains/onboard/state.json with a human-readable state.md
projection beside it. Never create or edit state files by hand, and never create lock
files — the tool locks for you.
Load State
Call the chain tool with action: "status", chain: "onboard" (a legacy
.onboard-state.md from an older version is imported automatically):
- If there is no run → abort: "No onboard run found. Run
onboard-mapfirst." - If the run is not
activewithcurrentPhase: "deepen"→ abort: "Expected the run to be at phasedeepenbut it is at<currentPhase/status>. Run that phase's skill instead." - If
data.hotspots(or the map phase summary) is missing → abort: "Phase pointer looks right but the Phase 1 output is missing. Treat as corrupted — restart the chain or repair via chain action 'update'." - If the tool reports the chain is locked by another session, abort; a dead session's
lock can be cleared with
action: "unlock". Never create lock files yourself.
Note the run's runId — it keys this phase's quest dedupe keys.
Workflow
Step 1 — Select deep-read targets
Take data.hotspots (top 3-6 flagged files). Add any files those hotspots most
heavily import from, if not already covered.
Step 2 — Deep read each hotspot via durable quests
Because deep-reading several files can be long-running and must survive a session
restart, use the quest tool rather than bare agent calls. For each target,
enqueue a quest with role: "explore", a self-contained task (read the full file —
not an excerpt — and report back: what it's responsible for and why it's a hotspot,
the key data flow(s) through it, and non-obvious conventions it embodies), and:
dedupeKey: "onboard/<runId>/deepen/<hotspot-id>"(<hotspot-id>a sanitized form of the file path) — re-running a crashed phase returns the same quest instead of duplicating the read;chain: { chain: "onboard", runId: "<runId>", phase: "deepen" };retainUntilConsumed: true.
Issue all targets' enqueue calls in one message so they run in parallel. If a
returned quest is already done (crash-resume case), reuse its stored result;
otherwise quest action run with its id and collect the result. After extracting
what's needed into chain state (Step 4), quest action consume each quest by id.
Step 3 — Record durable facts in memory
For facts likely to matter in future sessions on this repo (architectural decisions,
gotchas, "always/never do X here" rules), call the fairy-tales memory remember tool
to persist them. Keep entries short and specific — one fact per call, not a dump of the
whole map.
Step 4 — Assemble the deepened understanding
Merge the per-hotspot quest results into a single deepened-understanding section: core
module summaries, the key data flows traced end-to-end, and the non-obvious
conventions found. This is what Phase 3 (onboard-digest) will turn into the
architecture overview.
Step 5 — Complete the phase
Call the chain tool:
action: "complete-phase", chain: "onboard", phase: "deepen",
summary: "deep-read findings assembled for N hotspot files (module summaries, data flows, conventions); facts written to fairy-tales memory: <list, or 'none'>",
data: {
"deepened": [
{ "file": "<path>", "summary": "<what it's responsible for / why hotspot>", "dataFlow": "<traced flow>", "conventions": "<non-obvious conventions>" }
]
},
artifacts: { "deepenQuests": "<quest ids>" }The tool validates this is the current phase, advances the run to digest, and
rewrites the JSON + markdown projection atomically.
Handoff
After completing this phase, output exactly:
Phase 2 complete. Chain state updated (
.pi/fairy-tales/chains/onboard/state.json). Run/onboard-digestto begin Phase 3.
Do not start the next phase. Do not offer to continue. Output only the handoff line and stop.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

