Worldmodel

Build a comprehensive topology map for any topic by mechanically tapping every available knowledge source. Inventories surfaces, entities, connections, dependencies, terminology, audiences, and patterns — like a dynamically-built version of the surface-area catalog skills, enriched with web, report, and OSS context.

Core stance: Map the topology, don't analyze it. Report what exists, how it connects, who's affected, and what patterns are visible — with evidence provenance per finding. Never evaluate, recommend, or prebias. The consumer builds their own analytical framework from the topology.

This skill requires web search capabilities. Other channels are conditional on availability.

---

When to use this skill

Situation	Use
Need to understand a topic landscape across web, code, reports, and other sources	This skill
Need grounding before /spec, /research, /analyze, or any planning	This skill
User says "/worldmodel [topic]" to understand a space	This skill
Need deep investigative research with formal reports and citations	/research (may dispatch this skill first)
Need code patterns, conventions, or implementation-focused understanding	/explore directly
Need to evaluate a decision or situation with structured reasoning	/analyze

---

Stance: non-prescriptive observation

This skill discovers and reports. It does NOT:

• Recommend approaches or tools
• Evaluate whether patterns are good or bad
• Suggest what the consumer should do with findings
• Assert intent as fact ("is designed to" → "appears intended to")

Prose discipline:

• Match language to confidence. Never "clearly/obviously/definitely" unless CONFIRMED from multiple channels.
• MEDIUM confidence: "appears to," "suggests," "evidence indicates"
• LOW confidence: "if X is true," "depending on Y"
• Preserve conditionality — version-specific or context-dependent findings stay conditional. Do not flatten.
• Selective abstraction for LOW confidence specifics: prefer a less-specific-but-accurate version over dropping or over-hedging. "better-auth appears to support device flow in recent versions" beats both "supports device flow" (overstated) and "may possibly support device flow, though uncertain" (useless).

---

The workflow

Resolve depth mode (first action)

Check whether the caller specified --depth light or --depth full. Default is full. The worldmodel skill never self-selects its depth — the caller decides.

• full (default): Follow the standard 3-phase workflow below (Phase 0 → Phase 1 → Phase 2).
• light: Jump to the Light mode protocol section at the end of this workflow.

Invariant (both modes): Every available channel always runs. Depth mode changes how deep each channel goes, never whether it runs.

---

Create workflow tasks (first action — full mode)

Before starting any work, create a task for each phase using TaskCreate with addBlockedBy to enforce ordering. Derive descriptions and completion criteria from each phase's own workflow text.

1. Worldmodel: Channel discovery — resolve paths, check availability
2. Worldmodel: Parallel harvest — dispatch all available channels
3. Worldmodel: Synthesize topology + quality check — merge, map, emit

Mark each task in_progress when starting and completed when its phase's exit criteria are met.

---

Phase 0: Channel discovery

Check which channels are available. No skip logic — if a source exists, its channel runs.

Channel	Source	Gate
Web probes	Web search	WebSearch tool available
Existing reports	<reports-dir>/CATALOGUE.md	Reports dir exists (resolve via resolved-reports-dir from SessionStart hook)
Codebase	Git repo(s)	In a git repo. CWD always included. Additional repos from caller (--repos) or discovered in Phase 1.
Catalog skills	.agents/skills/, .claude/skills/, plugin skill dirs	Skills named product-surface-areas, internal-surface-areas, or audience-impact exist
OSS repos	~/.claude/oss-repos/	Dir exists
User-provided sources	Paths, URLs, folders in the prompt	Caller provided them

Scan the prompt for file paths (starting with / or ~/) and URLs (starting with http). These become user-provided sources.

Exit criteria: List of available channels determined. Default paths resolved.

---

Phase 1: Parallel harvest

Dispatch available channels as parallel subagents. The code channel dispatches /explore; other channels follow worldmodel's protocols. Lightweight channels (catalogs, user sources) run inline.

Parallelism is mandatory: Dispatch ALL channel subagents in a single message (multiple Agent tool calls in one response) to ensure true concurrent execution. Do NOT dispatch one agent, wait for it to return, then dispatch the next — this serialization wastes minutes. Run inline channels (catalogs, user sources) while subagents are in flight.

Parallelizable (dispatch as subagents):

Web channel — 3 divergent probes from different structural categories. Goal: discover terminology, major entities, landscape shape. Can look up specific details when clearly pertinent to the topology (e.g., checking if a 3P dependency supports a specific capability), but don't run extended multi-probe investigation campaigns — that's /research's job. ⚠ Must use Agent tool dispatch (not Task tool) — needs WebSearch MCP access. Within the web subagent: issue all WebSearch calls in a single message (parallel). If results require WebFetch for specific pages, batch those into a single message too — never chain WebFetch calls sequentially. Load: references/probe-vocabulary.md for the 5 probe categories (broad survey, key concept deep-dive, entity/player scan, contrarian/alternative, recency). Choose 3 that will produce the most structurally different results for this topic.

Code channel — one Agent tool subagent per repo root. Each subagent:

• Loads /explore skill
• Runs surface mapping + tracing lenses at L1-L2 depth
• Also loads catalog skills from its repo if they exist (product-surface-areas, internal-surface-areas, audience-impact)
• Returns a World Model Brief

CWD is always included. Additional repos from --repos flag or cross-channel entity matching (if web/reports surface entities that match repos in ~/.claude/oss-repos/ or caller-specified paths).

OSS channel — ls ~/.claude/oss-repos/, match repo names against the topic + entities discovered by other channels (package.json dependencies, import statements). For relevant repos, skim: README, key type definitions, main interfaces. Ecosystem discovery (mandatory when researching any technology): (1) Check the organization's package registry for companion/sibling packages — official tools, plugins, extensions, partner integrations. Do not assume the primary repo or product contains all functionality. Applies to OSS (npm @org/*, GitHub org) and closed products (official integrations, partner SDKs). (2) Search for community ecosystem: "[project] integrations", "awesome [project]", "[project] adapter", popular third-party wrappers and adapters bridging between ecosystems. Community repos exist around both OSS and closed products (Stripe, Salesforce, Claude, etc.). ⚠ Must use Agent tool dispatch if it needs WebFetch for OSS docs, package registry pages, or community ecosystem searches.

Reports channel — if <reports-dir>/CATALOGUE.md exists, scan the catalogue for semantic relevance to the topic. Read executive summary + rubric of top 1-3 matching reports.

Run inline (fast, no subagent overhead):

Catalogs — if product-surface-areas, internal-surface-areas, or audience-impact skills exist in the repo, load and read them. Staleness check: spot-check 2-3 high-coupling surfaces against actual code. If stale, note staleness; prefer code-verified findings from explore.

User sources — Read all provided file paths/folders. WebFetch all provided URLs. If a URL fails (auth, size), classify as INACCESSIBLE.

Stagnation rule (applies to all channels): If a channel has processed 10+ items (files, web results, report sections) without surfacing new entities or surfaces, stop that channel. If the same search is repeated with same terms, stop immediately.

Exit criteria: All channel subagents have returned findings. Inline channels complete.

---

Phase 2: Synthesize topology

Synthesize from the raw channel findings returned by subagents. Do NOT synthesize from memory of what channels found — re-read the actual findings.

Build a topology map — an inventory of surfaces, entities, connections, and patterns. Like a dependency graph with annotations. NOT an analytical framework with ranked dimensions.

Depth calibration: Follow dependency chains as deep as they're intrinsic to the topic — the auth middleware connects to the session store connects to the database, and that's all part of understanding auth. Stop when connections become tangential — the database's backup strategy connects but isn't part of the auth topology. Tangential connections get acknowledged with context (what they are, why they connect) but not chased further. The goal is a complete topology of the intrinsic system, not a shallow skim of everything.

1. Merge entities — match on exact names and obvious aliases (e.g., "better-auth" and "@better-auth/core"). Do NOT try to resolve subtle semantic overlaps — report both and let the consumer decide. Over-merging is worse than under-merging.
2. Map surfaces — product surfaces + internal surfaces from ALL available channels, not just code/catalogs. Catalogs and code give code-verified surfaces; web probes surface external/ecosystem surfaces; reports give previously-mapped surfaces; OSS gives dependency surfaces; user sources give whatever the caller pointed to. Always build the surface inventory — don't skip it because catalogs are absent. For each surface: what it does, relevance to topic, dependencies, source (catalog / code-verified / web / inferred).
3. Map connections — dependency chains, propagation paths, amplifier nodes, implicit coupling. Forward (what does this feed?) and backward (what feeds this?). Cross-repo connections. Breaking change impact matrices when available from catalog skills or traceable from code.
4. Triangulate — findings in 2+ channels → HIGH confidence. Single-source → flag.
5. Flag divergences — when channels contradict, report BOTH sides with resolution rationale. Consult references/source-credibility.md. Code is ground truth for current behavior. Divergences are headline findings — report prominently, never flatten.
6. Collect terminology — key terms discovered, with brief definitions and source channel.
7. Note patterns — cross-channel convergences, divergences, recurring themes. What was observed + which channels. NOT what it means.
8. Label confidence provenance — which channels, triangulation level. Check confidence ceilings by claim type (Load: references/source-credibility.md).
9. Tag incomplete findings — UNRESOLVED / ADJACENT / INACCESSIBLE per the taxonomy below. No gap-fill pass — if something is thin, it's UNRESOLVED. The consumer investigates surgically.
10. Organize channel-specific sections — some output sections come directly from channel findings, not cross-channel synthesis. Organize these from the raw channel output:
    • Current State — code-verified observations from the code channel's explore output
    • Personas & Audiences — from catalog skills (audience-impact) or code/web channel findings about who uses the system
    • Prior Research — from the reports channel's catalogue scan
    • 3P Landscape — from OSS channel + web channel findings about third-party dependencies
    • User-Provided Source Findings — from the user sources channel, organized by source

Pre-emission quality check (mandatory)

Before emitting, run these 4 checks. If any fails, fix before emitting.

• Contradictions: Did you flag ALL cross-channel conflicts? Any silently resolved?
• Confidence-prose match: Does language match evidence strength? No "clearly/obviously" unless CONFIRMED from multiple channels.
• Completeness: Did every channel that ran contribute to the output? Any findings silently dropped?
• Non-prescription: Does output contain any evaluative or recommendatory language?

Emit output

Load: references/output-format.md for the canonical template.

• If --output <path> specified → write to file
• Otherwise → emit inline
• If interactive session (standalone invocation, not headless) → offer next steps: "Want me to /research this? /spec it? /analyze it?"
• If headless or dispatched by consumer → structured output only, no interactive follow-up, no suggestions

Exit criteria: Output emitted. All tasks marked complete.

---

Light mode protocol

When --depth light is specified, execute this protocol instead of the standard Phase 0 → Phase 1 → Phase 2 workflow. Light mode produces the same output format as full mode but completes in roughly half the time by reducing channel depth uniformly.

Every available channel still runs. Light mode changes depth, not coverage.

Step 1: Create tracking task + discover channels

Create a single tracking task: "Worldmodel (light): harvest + synthesize". Mark it in_progress.

Run channel discovery exactly as Phase 0 above — resolve paths, check availability, scan prompt for user-provided sources. Same gates, same channel table.

Step 2: Parallel harvest (light depth)

Dispatch all channel subagents in a single message to ensure true parallelism. Run inline channels concurrently.

Web channel (light) — 2 divergent probes from different structural categories (instead of 3). Choose the 2 that will produce the most structurally different results for this topic. Load: references/probe-vocabulary.md. Within the web subagent, issue both WebSearch calls in a single message. If results need WebFetch, batch those too. No gap-fill pass — if an entity is thin, tag it UNRESOLVED.

Code channel (light) — inline scanning, no /explore dispatch. For each repo:

1. Read package.json (or equivalent manifest) for dependencies, scripts, project structure
2. Glob for key structural patterns: **/src/**/index.{ts,js}, **/routes/**, **/api/**, **/components/**, config files (*.config.*, .env.example)
3. Grep for topic-relevant terms across the codebase (3-5 targeted searches)
4. Read 2-3 files most relevant to the topic based on grep hits
5. Produce a surface inventory: what exists, what's relevant, key dependencies

This gives surface enumeration without dependency chain tracing. Do NOT dispatch /explore — inline scanning is the protocol for light mode.

OSS channel (light) — ls ~/.claude/oss-repos/, match repo names against topic. For the top 1-2 matches: read README only. No type definition deep-dives. Ecosystem check (still mandatory at light depth): (1) Check the org's package listing and GitHub repos for companion tools, OSS templates, client SDKs, and side projects related to their core product — companies frequently open-source parts around a closed core. (2) Run one web search for "[project] integrations" or "awesome [project]" to surface community ecosystem. No deep dives, but do not skip this step.

Reports channel (light) — scan CATALOGUE.md for semantic relevance. Read the title + first paragraph of top 1-2 matching reports. No full executive summary reads.

Catalogs (inline, light) — if catalog skills exist, load and read them. Skip the staleness spot-check.

User sources (inline, light) — same as full mode. Read all provided paths. WebFetch all provided URLs.

Stagnation rule: same as full mode.

Step 3: Single-pass synthesis

Synthesize from the raw channel findings. Same rule: re-read actual findings, do not synthesize from memory.

Build the topology map using the same 10 synthesis steps as Phase 2 above, with these adjustments:

• Triangulation (step 4): Label each finding with its source channel. Note when 2+ channels converge but do not run a dedicated cross-referencing pass.
• Quality check: Verify non-prescription and completeness (did every channel contribute?). Skip the full 4-check quality gate.

Load: references/output-format.md for the canonical template. Emit output using the same rules as Phase 2 (file if --output specified, inline otherwise, interactive follow-up only if standalone + not headless).

Mark the tracking task completed.

---

Incompleteness taxonomy

Every finding that isn't fully resolved MUST be classified into one of three categories. No other categories are valid.

UNRESOLVED — Found it, couldn't get sharp.

• Searched all relevant channels. Specifics are murky.
• Output: what was found + trail (how far you got, where visibility ended and why) + confidence.
• No recommendations. Just the trail.

ADJACENT — Connected thread outside topic scope.

• Output: what was noticed + relevance link to topic + confidence.
• No recommendations.

INACCESSIBLE — Can't reach the source.

• Auth-gated URL, private repo, human-only knowledge.
• Output: what source is needed + why inaccessible + what WAS found in accessible channels.

"Not found" is NOT a valid category. If the skill's channels could have found it, search harder. A confirmed negative (genuinely doesn't exist) is a finding in the main output, documented with: terms searched, channels checked, what was expected, result count (zero).

Laziness prevention:

1. No UNRESOLVED without listing which channels were searched and what was tried.
2. No single-channel UNRESOLVED — check all relevant channels before declaring.
3. Every UNRESOLVED/ADJACENT must include a breadcrumb trail from your investigation.
4. Absence claims require the same search evidence as presence claims.
5. Confirmed negatives must document the search: terms, channels, expectations, result count.

---

Channel failure handling

If a channel errors (web timeout, URL 404, repo unreadable), skip it. Note in Meta → "Channels unavailable" with the reason. Never fail the whole run — each channel is independent.

---

Anti-patterns

Anti-pattern	What it looks like	Correction
Prescribing	"You should use X" or "This pattern is bad"	Report what exists. Consumer evaluates.
Flattening divergence	Silently picking one side when channels disagree	Report both sides prominently in Patterns Observed.
Single-channel gaps	"Not found in codebase" without checking web/reports	Search all relevant channels before declaring UNRESOLVED.
Vague incompleteness	"Needs investigation" without a trail	Every UNRESOLVED/ADJACENT must cite what you found that led there.
Overstating confidence	"Clearly" for a finding from one blog post	Check confidence ceilings. Match prose to evidence.
Skipping channels	Not checking reports because "probably nothing there"	If the source exists, tap it. No judgment calls on channels.
Over-scoping	Treating every tangential entity as a core surface; output bloated with marginally relevant items	Focus on surfaces and entities directly relevant to the topic. Tangential threads go to Adjacent, not the main topology.
Re-implementing explore (full mode)	Reading code files directly instead of dispatching /explore	Dispatch /explore for codebase work. It owns surface mapping + tracing. Light mode uses its own inline scanning protocol — this anti-pattern applies only to full mode.
Synthesizing from memory	Not re-reading subagent findings before synthesis	Re-read the actual findings. Source anchoring prevents hallucination.