Skip to content

majiayu000/spellbook / skills/xray

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.

references/research-routing.md

View on GitHub
# Research Routing

Choose enough investigation to establish the mechanism, not the maximum amount of research available.

## Research Modes

| Mode | Use when | Typical evidence |
|---|---|---|
| Supplied | The user supplied a trustworthy document, trace, or dataset and asks for explanation | Supplied material plus spot checks of pivotal claims |
| Grounded | A stable topic is reasonably known but needs exact explanation | A primary source and current local evidence where applicable |
| Deep | The topic is current, niche, disputed, unfamiliar, or failure-sensitive | Primary sources plus current implementation or runtime evidence sufficient to resolve the mechanism |

## Target Decision Table

| Target | Start here | Add only when needed |
|---|---|---|
| Concept, protocol, or algorithm | Original paper, standard, official documentation | High-quality secondary explanation for pedagogy |
| Repository or module | Exact worktree, nearest instructions, entry point, tests, schema/config | Git history, issue or PR for rationale |
| Application behavior | User-visible action, exact app version, reachable client code | Network contract or observed request, server path, persistence, jobs, platform-specific behavior |
| Incident | Persisted state, logs, metrics, request IDs, deployed revision | Source trace and documentation |
| Supplied document | Document claims and cited sources | External verification of material/current claims |
| Clearly identified local app, CLI, or compiled artifact | Identify the exact artifact, version, and hash; perform safe read-only static inspection | Ask only when deeper work requires execution, debugging, interception, patching, new tooling, credentials, or protection bypass |

## Scope and Cost Controls

- Do not call paid services, external AI systems, or multiple agents unless the user explicitly asks or another binding workflow requires them.
- Do not scan an entire repository when an entry point and its reachable path can answer the question.
- Do not collect redundant sources after a material claim is already corroborated.
- Do not require every evidence type. Add web, history, network observation, runtime experiments, or artifact inspection only when it can resolve a real gap.
- Begin broad enough to locate the authoritative source, then use targeted queries for unresolved gaps.
- Ask one minimal clarifying question only when different answers would materially change the target, authorization, or output.

## Stop Condition

Stop research when:

- the input, key decision or transformation, state change, output, and important failure boundary are supported or labeled unknown;
- no unresolved contradiction changes the central explanation;
- a new reader can follow the causal chain without relying on the researcher's private context; and
- additional sources would add detail rather than change the model.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall