/xray

name: xray
description: Investigate how a concept, code path, application, network flow, system, incident, document, or local artifact actually works, then deliver a two-depth visual HTML explainer with a dead-simple big-picture first layer and source-backed technical depth behind it. Use when the user invokes $xray, asks how something works under the hood, wants a module or app behavior traced across boundaries, requests web, code, network, or safe static artifact research before explanation, or asks for an evidence-backed explainer. Do not use for answer-only definitions, general web design, full codebase audits, or invasive binary reverse engineering without explicit authorization.

X-Ray Explainer

Investigate first and explain second. The HTML is a projection of verified understanding, not decoration around an early guess.

Operating Boundary

• Directly perform read-only research, repository inspection, log/config examination, source archaeology, and creation of the requested explainer artifact.
• When the user asks to analyze a clearly identified app, CLI, or local compiled artifact they are entitled to inspect, include safe read-only static inspection when it can answer the teaching question. Record identity and hash first; inspect metadata, signatures, dependencies, imports, recoverable symbols, strings, entitlements, and bundled resources without modifying or executing the target.
• For an authorized native binary or compiled CLI, load `$claude-code-reverse` first and use its tested `extract.sh` workflow as the canonical identity, hash, cache, and safe static baseline. Do not duplicate that baseline inside X-Ray.
• When the canonical static baseline cannot establish the requested mechanism, or the authorized target is an APK, JavaScript bundle, or protocol flow, read [reverse-core.md](references/reverse-core.md). Load only the matching specialist adapter, use tools already available in the environment, and return its evidence to the ordinary X-Ray causal model. Reverse Core is an internal depth route, not a second user-facing skill or a reason to install a full security pack.
• Ask before executing an unknown binary, attaching a debugger, intercepting or decrypting traffic, patching an artifact, installing reverse-engineering tools, using a paid endpoint, touching production, accessing credentials, or changing product code.
• Never bypass access controls, fabricate evidence, or treat agreement between models as corroboration.
• If the target, revision, authorization, or intended audience would materially change the investigation, clarify that one fact before acting.

Investigate

Read [research-routing.md](references/research-routing.md), then choose the narrowest route that can answer the question.

| Target | Default route | |---|---| | Stable concept with adequate supplied material | Explain from supplied evidence; verify pivotal facts only | | Current, niche, disputed, or unfamiliar topic | Search the web; prefer primary and authoritative sources | | Repository, module, app behavior, API path, or architecture | Trace the reachable path across code, network, persistence, and background work | | Incident or wrong runtime behavior | Inspect persisted state, logs, metrics, running revision, then code | | Clearly identified local app, CLI, or compiled artifact | Use `$claude-code-reverse` for the native static baseline, then load one Reverse Core specialist adapter only if the question remains unresolved |

Do not invoke extra agents or external AI systems by default. Add them only when the user requests delegation or a separate workflow explicitly requires it.

Announce each stage in one line as it begins: the stage name, what is being checked, and the next visible output. A long investigation must never go silent while the user waits.

1. Frame the teaching question

Write one sentence naming what the reader must understand or decide after viewing the explainer. Default to a curious adult who is new to the topic; never infantilize the reader.

2. Acquire ground truth

Read [evidence-contract.md](references/evidence-contract.md). For code or runtime targets, also read [code-archaeology.md](references/code-archaeology.md).

• Establish the exact target and relevant version before explaining it.
• For a compiled target, record the artifact path, cryptographic hash, architecture, and signature before drawing conclusions. Treat strings, imports, symbols, and decompiled fragments as clues until another observation establishes their role.
• For authorized specialist reverse work, keep the reverse phase bounded to the teaching question. Prefer one reachable path over exhaustive decompilation, and bring exact addresses, symbols, tool versions, and uncertainty back into the same evidence model.
• Search the local target before searching the web for explanations of it.
• Use web research for current, niche, disputed, unfamiliar, or explicitly source-backed claims.
• For incidents, prefer the actual persisted state and running revision over remembered browser behavior or design intent.
• For application behavior, follow the user action through internal control flow, network boundaries, server handling, persistence or background work, and the result or failure path. Inspect or capture traffic only when it is safe, authorized, and materially useful.
• Keep exact URLs, code anchors, revision identifiers, timestamps, and uncertainty for the claims that matter to the explanation.

3. Form the causal model

• Write scratch notes in whatever form helps distinguish evidence from interpretation; do not create a manifest or fixed ledger unless the task genuinely benefits from one.
• Identify the input, meaningful transformations or decisions, state changes, outputs, and failure boundaries that explain the behavior. Use as many or as few steps as the mechanism needs.
• State confirmed behavior plainly. Label material inference and unknowns where a reader could otherwise m