Onboard

Onboard Skill

Start with a quick recommendation based on recent sessions, then optionally continue to guided learning — so users experience value first, learn second.

Invoke directly with /onboard when the user wants onboarding or protocol discovery.

When to Use

Invoke this skill when:

• A new user wants to discover which epistemic protocols fit their workflow
• A user wants to experience protocols through guided practice
• Re-onboarding after new protocols are added or workflow changes

Skip when:

• User already knows which protocol to use (direct invocation)
• Quick single-protocol question (answer directly)

Workflow Overview

Quick Proof:    ENTRY → QUICKSCAN → PICK-1 → EVIDENCE → TRIAL → INSIGHT → NEXT
Targeted:       ENTRY → QUICKSCAN → MAP → SCENARIO → TRIAL → QUIZ → GUIDE
Targeted + std: ENTRY → SCENARIO → TRIAL → QUIZ → GUIDE

Data Sources

Compact mapping for inline use.

Phase Execution

Paths below written {config_dir}/… take {config_dir} = CLAUDE_CONFIG_DIR when set, else ~/.claude. Resolve it ONCE per invocation with Bash printf '%s\n' "${CLAUDE_CONFIG_DIR-$HOME/.claude}" and substitute the absolute result before any Read/Glob/Grep call.

Phase 0: Entry (Path Selection)

Begin with a concise welcome and path selection, reserving the full catalog for the Browse-all path.

Gate #1:

• Text: Path selection prompt
• Options:
  • Quick recommendation (Recommended)
  • Learn a specific protocol
  • Browse all protocols

If Quick recommendation: set path = quick, proceed to Phase 1.

If Browse all: Present the protocol catalog (check installation status via Glob {config_dir}/plugins/cache/epistemic-protocols/*/, then render all core protocols from Data Sources as a numbered list grouped by Cluster with name + "When to Use" + installation badge). After catalog, present:

• Text: Post-catalog path selection
• Options:
  • Quick recommendation
  • Learn a specific protocol (type name in Other)

Then proceed based on selection.

If Targeted + Other contains protocol name: proceed directly to session source question.

If Targeted + no protocol specified:

Present a condensed catalog as text output: render the Data Sources table grouped by Cluster, each protocol as /command — When to Use description.

Then Gate #2:

• Text: Protocol selection (type name or number in Other)
• Options:
  • Pre-execution (Planning) — /inquire, /elicit, /ideate, /preview, /sketch
  • Analysis — /ground, /induce
  • Execution / Verification / Cross-cutting — /apportion, /contextualize, /sublate, /bound, /recollect, /conduct, /grasp

Gate #3 (Targeted only, session source):

• Text: Session source selection
• Options:
  • Personalize with my recent sessions
  • Use standard examples (no session needed)

State after Phase 0:

• path: quick | targeted
• target_protocol: (targeted only) selected protocol name
• session_source: (targeted only) scan | standard — Quick path always runs Quick Scan

Skip rule: If targeted + standard → skip Phases 1-2, jump to Phase 3 with preset scenarios from references/scenarios.md.

Phase 1: Quick Scan (User Context Profile) — Inline

Build a User Context Profile from the person's own opening turns in their recent Claude Code conversations. Runs inline (no subagent delegation). Both Quick and Targeted paths share this phase.

Step 1: Collect recent opening turns

• Records: Glob {config_dir}/projects/*/*.jsonl — a session record sits directly inside a project partition; anything nested deeper is a subordinate capture and is excluded by depth. Exclude partitions whose name contains -worktrees-, which hold delegated work rather than the person's own sessions. Take the ~10 most recently modified records.
• Bounded head read: read only the first 256 KB of each record (a byte-bounded read such as head -c 262144 <record>), never the whole file. Skip a line that does not parse — the last one may be cut by the bound.
• Person turns only: a line is the person's turn when its type is user, isMeta and isCompactSummary are both absent, and its text (message.content as a string, or the text parts of a content list — tool results are not text parts) neither opens with < nor is a bare control marker such as [Request interrupted by user]. Hook output, command wrappers, and injected envelopes arrive in the same user stream and are excluded by this rule.
• From each record keep its first 2-3 person turns. A record whose head holds none contributes nothing.

Step 2: Infer User Context Profile

From the collected turns, infer:

• Work domains: What areas the user works in (e.g., API development, infrastructure, data pipeline)
• Conversation patterns: Request clarity level, incremental vs. batch requests, question types (how/why/what)
• Task types: Ratio of feature development, debugging, refactoring, documentation

If no person turns were collected — a fresh install, or a host that keeps no such records: Quick path proceeds to Pick-1 with fallback (/elicit); Targeted path falls back to Onboarding Pool (/elicit, /inquire).

Output for Phase 2: User Context Profile (work domains, conversation patterns, task types). Quick Scan infers user context for protocol matching and scenario personalization.

Phase 2a: Pick-1 (Quick Path — Single Recommendation)

Quick path only. Select exactly 1 protocol recommendation from the auto-recommend pool.

Onboarding Pool: /elicit (Euporia), /inquire (Aitesis). These two are chosen because users can quickly experience their value. Protocols like /grasp are user-initiated by nature and should not be proactively suggested in the first encounter.

Recommendation rules (applied to Quick Scan Profile):

Decision logic:

1. Score each protocol by signal match count across the collected person turns
2. Ideation route-away: ideation asks ("ideas for", "brainstorm") score no pool protocol — when they are the only matched signals, relay in one sentence that the ask itself maps to /ideate (user-initiated: named as the route for that ask, not presented as the onboarding recommendation), then continue via the Fallback rule; the Phase 2b evidence card follows its fallback form, since the recommendation rests on the default, not on a matched signal
3. Select the single strongest match
4. Tie-break: /elicit > /inquire
5. Fallback: If no signals detected (no records, or too few person turns) — or every detected signal was routed away — recommend /elicit

Output: Present exactly one recommendation as a single sentence.

Format: Present as a single sentence stating which protocol is most likely to help right now.

Phase 2b: Evidence (Quick Path — Evidence Card)

Quick path only. Present exactly 1 evidence card explaining why this recommendation was made.

Evidence generation (per protocol, referencing Data Sources table):

• Line 1: Cite the specific signal pattern from Quick Scan Profile that matched this protocol's "Key Patterns" column in Data Sources
• Line 2: State the expected benefit, derived from the protocol's "When to Use" column in Data Sources

Fallback (no session data): State that no patterns were detected, then cite the protocol's core value proposition from Data Sources "When to Use."

Rules:

• Evidence is maximum 2 lines — a focused cue.
• Do not show confidence scores or numbers.
• Do not quote session content verbatim.

After presenting evidence, present:

• Text: Trial invitation
• Options:
  • Try it now
  • Learn more about this recommendation
  • See a different recommendation
  • Go to full learning path

Branch: Try it now → Phase 4 (quick trial), Learn more about this recommendation → show Data Sources row for the recommended protocol then re-ask, See a different recommendation → pick next from pool and re-present from Phase 2a, Go to full learning path → set path = targeted and go to Phase 0 targeted flow.

Phase 2: Map (Targeted Path — Protocol Matching)

Targeted path only. Apply User Context Profile to match protocols to the user's context.

1. Match Profile against the compact mapping table (Data Sources section). Select 2-3 protocols most relevant to the user's work domains and conversation patterns, defaulting to Onboarding Pool (/elicit, /inquire).
2. Targeted sub-path: Filter to target protocol, use Profile for scenario personalization. Note related protocols from the compact mapping table.
3. Fallback: If Profile quality is insufficient (no records, or too few person turns) → use Onboarding Pool (/elicit, /inquire). Proceed immediately without blocking the onboarding flow.

Phase 3: Scenario (Targeted Path — Intervention Point)

Targeted path only. Present a concrete scenario showing where the protocol would have helped.

Scenario construction (2-tier fallback):

• Tier 1 (User Context Profile available): Generate a hypothetical scenario grounded in the user's work context (domains, task types, conversation patterns from Quick Scan). Personalize standard scenarios from references/scenarios.md using Profile data.
• Tier 2 (no data / Onboarding Pool fallback): Use preset scenarios directly from references/scenarios.md.

Present scenarios for each of the top 2-3 protocols sequentially.

Scenario format:

Scenario: /X (Protocol Name)

[Situation]: [Concrete situation grounded in user's work context — or preset from scenarios.md]

[Intervention]: If you had called /X at this point:
- [what the protocol would have done — step 1]
- [step 2]
Expected outcome: [e.g., reduced rework, clearer direction]

Clarity rule: Scenarios must present clear-cut protocol fits where the mapping is unambiguous. If a situation could plausibly map to multiple protocols (e.g., "exploration" could be /elicit or /ideate), reserve it for Phase 5 quiz material instead of using it as a scenario. The scenario phase builds confidence through recognition; the quiz phase builds discrimination through ambiguity.

Anti-pattern: Scenarios must be self-contained (situation + intervention) with unambiguous protocol fit. Ambiguous patterns belong in Phase 5 quiz.

Present each scenario as regular text output (Tier 1/2 format above). Then present for navigation only:

Gate (per scenario):

• Text: Scenario navigation
• Options:
  • Try it — practice this protocol
  • Show another example
  • Skip to quiz

Phase 4: Trial (Protocol Execution)

Guide the user through a real, abbreviated protocol experience.

Quick Path Trial

Mini practice prompt: Present a single realistic request (one sentence) that naturally triggers the selected protocol's deficit. When User Context Profile is available, adapt the domain to match the user's work context. Source from references/scenarios.md Trial prompt field, or generate from Data Sources context. Follow with gate interaction:

• Text: Trial scenario confirmation (user can also define their own)
• Options:
  • Start with this scenario — call /X
  • Start with my own scenario (type in Other)

Execution: The user invokes the actual protocol (e.g., type /elicit). The protocol runs in the same session with the mini prompt as context. Trial ends when the invoked protocol reaches its natural termination. After protocol termination, proceed to Quick Post-Trial below.

Quick Post-Trial Insight (2 lines max):

Generate from the protocol just experienced:

• Line 1: Name the epistemic operation performed (source: protocol's deficit → resolution type, or references/scenarios.md Philosophy field)
• Line 2: Connect to a concrete workflow benefit

Quick Post-Trial Navigation:

Present via gate interaction:

• Text: Post-trial navigation
• Options:
  • That's enough for today
  • Try a different protocol
  • Continue to full onboarding

Branch: That's enough for today → end session with brief closing, Try a different protocol → check pool exhaustion: if unrecommended protocols remain in Onboarding Pool, pick next and restart from Phase 2a; if pool exhausted (every pool protocol recommended in session), present You've experienced all core recommendations and offer Targeted transition, Continue to full onboarding → set path = targeted and go to Phase 2 MAP with Quick Scan results.