jongwony/epistemic-protocols/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 → 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 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 as a numbered list, each protocol as /command — When to Use description.

Then Gate #2:

• Text: Protocol selection (type name or number in Other)
• Options: one per Onboarding Pool protocol (/elicit, /inquire), each as /command — When to Use; any other protocol is chosen by name or number in Other

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 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 (Quick Path — Recommendation)

Quick path only. Recommend 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):