agentleFS
KcAnomKcAnom/pi-fairy-tales-chains/skills/onboard-deepen/SKILL.md

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".

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
  1. Very specific:

    All chain state is managed by the chain tool: authoritative JSON at .pi/fairy-tales/chains/onboard/state.json with a human-readable …

    line 27
  2. Very specific:

    Call the chain tool with action: "status", chain: "onboard" (a legacy .onboard-state.md from an older version is imported automatically):

    line 34
  3. Very specific:

    If there is no run → abort: "No onboard run found.

    line 37
  4. Very specific:

    If the run is not active with currentPhase: "deepen" → abort: "Expected the run to be at phase deepen but it is at <currentPhase/status>.

    line 38
  5. Very specific:

    If data.hotspots (or the map phase summary) is missing → abort: "Phase pointer looks right but the Phase 1 output is missing.

    line 41
  6. Very specific:

    If the tool reports the chain is locked by another session, abort.

    line 44
  7. Distinctive:

    Call the chain tool:

    line 91
  8. Distinctive:

    After completing this phase, output exactly:

    line 109
  9. Distinctive:

    Do not start the next phase.

    line 114

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-map first."
  • If the run is not active with currentPhase: "deepen" → abort: "Expected the run to be at phase deepen but 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-digest to begin Phase 3.

Do not start the next phase. Do not offer to continue. Output only the handoff line and stop.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.