realm-fathom

realm-fathom

Investigate anything. Code truth + vault context. Drift flagged.

Syntax

/realm-fathom function:validateUser          # named function
/realm-fathom class:UserService              # named class
/realm-fathom system:PaymentPipeline         # named subsystem
/realm-fathom "how does auth flow work"      # freeform question
/realm-fathom validateUser                   # bare name (auto-detect type)
/realm-fathom "payment pipeline"             # concept

Examples

/realm-fathom function:validateUser
→ Live: signature, flow, callers, error paths
→ Vault: why JWT, ADR refs, invariant notes
→ DRIFT flagged if vault says bool return but code returns Result<User>

/realm-fathom "how does the auth middleware chain work"
→ Investigator maps relevant files + functions end-to-end
→ Vault adds architectural intent, prior decisions
→ VERDICT: consolidated what + why

/realm-fathom class:PaymentService
→ Full class: responsibility, methods, deps from live code
→ Vault: why this abstraction exists, linked ADRs

Source Hierarchy

Source	Authoritative for
Live code (cavecrew-investigator)	behavior, signatures, flow, callers, current state
Vault (realm-agent-query)	why, ADR refs, architectural intent, invariant rationale
Conflict	flagged as VAULT DRIFT — never silently blended

Guards

Condition	Behavior
.realm/realm-state.json missing	SOFT — proceed code-only, note vault unavailable
Vault initialized but no nodes match query	Note "no vault nodes" — proceed code-only
Entity not found in codebase	Flag "cannot locate in codebase"
Vault and code conflict on any fact	Flag VAULT DRIFT with both values

When to Use

Trigger	Example
Understand how a function works before modifying it	/realm-fathom function:processPayment
Map a class before refactoring	/realm-fathom class:AuthMiddleware
Answer a freeform design question	/realm-fathom "how does session refresh work"
Audit: what vault says vs what code actually does	any vaulted entity

When NOT to Use

• Writing to vault → /realm-flourish or /realm-manifest
• Vault-only lookup (already documented) → /realm-recall
• Full repo scan for documentation → /realm-phase
• Pipeline health check → /realm-status

---

Procedure

Step 0 — Parse input

From invocation args:

• Detect entity specifiers: function:X, class:X, system:X → extract entityType and entityName
• No specifier → set entityType: freeform, entityName: "", use full arg as query
• Bare single word without prefix → treat as freeform (investigator will auto-detect type)

Step 1 — Soft vault guard

Read .realm/realm-state.json from current working directory:

• Present → load vaultPath, projectSlug, projectDir → set vaultAvailable: true
• Missing → set vaultAvailable: false
  • Print: Vault not initialized — proceeding code-only. Run /realm-forge to enable architectural context.

Step 2 — Spawn fathom agent

Spawn agent realm-agent-fathom with this prompt:

projectRoot: <absolute path to current working directory>
query: <full original query string, e.g. "function:validateUser" or "how does auth flow work">
entityType: <function|class|system|freeform>
entityName: <extracted name, or empty string if freeform>
vaultAvailable: <true|false>
vaultPath: <vaultPath or empty>
projectSlug: <projectSlug or empty>
projectDir: <projectDir or empty>

Investigate the query and return a consolidated fathom report.
Follow the full procedure in your instructions.

Wait for completion. Surface the agent's fathom report directly to the user.