Research Methodology — Multi-Dimensional Grounding

Status: Reference

Invoked on every RESEARCH phase, every Explore/Plan agent spawn, every "find best practices" or root-cause request. Referenced by the UserPromptSubmit reminder, the 6-Phase Pipeline (CLAUDE.md), and the Agent prompt template.

Why this exists

We research primarily from text. Text research is excellent at the semantic / conceptual direction — what to do and why — but it routinely misses how the direction is actually embodied in practice. The result is changes that are directionally right but practically wrong or inert.

Two real misses that motivated this doc:

• Dead-theme-file (2026-05-27). Goal understood perfectly ("differentiate participation colors"). The fix edited packages/ui/src/themes.ts — the plausibly-named theme file. But the runtime loads themes from packages/app/src/config/themes/* (via apps/mobile/tamagui.config.ts). The change was inert on-device, shipped + OTA'd, and the bug persisted. The concept was right; the concrete runtime reality was never verified.
• "Best-practice color system." The conceptual answer ("semantic palette + cues") is correct, but acting on it from intuition would have meant inventing hex values instead of grounding the palette in how real systems (Material 3, Radix Colors, IBM Carbon, Apple HIG, Toss) concretely structure semantic tokens, scales, and contrast.

The ethos of a direction lives in concrete details — the file that runs, the token architecture, the real values, the actual mechanics — not in the principle alone.

The principle

Every research effort must capture BOTH the conceptual/semantic direction AND its concrete implementation reality. Pair the idea with its embodiment before concluding research or writing a plan.

The four dimensions — cover every one that applies

1. Runtime reality — determine which code / file / config / migration actually executes. Trace the import + config chain; never trust the obvious-named file. ("Which theme file does the app actually load?" → read tamagui.config.ts, not assume themes.ts.)
2. Concrete reference grounding — for design / UX / algorithm / protocol / regulatory work, study how real, authoritative systems implement it: actual token architecture, values, mechanics, reference code — not the abstract principle. ("Semantic color palette" → fetch Material 3 / Radix Colors / Carbon: their actual scale steps, role tokens, and contrast rules.)
3. Multi-modal sources — combine text + code + images/screenshots + live inspection (DB probes, runtime telemetry, real data). Prose alone is the weakest mode. Look at the actual thing.
4. Cross-validation — confirm the embodiment against ≥2 independent concrete sources or a direct runtime check. Never relay a single agent's claim about runtime behavior without verifying it yourself (the dead-theme claim was confirmed by reading the tamagui config import before acting).

Tool mapping (make it concrete)

To establish…	Use
Which artifact actually runs	Grep/Read the import + config chain; run the real command
Design / approach grounding	WebSearch + WebFetch the authoritative reference; capture actual values/structures; view reference images where the concern is visual
Data reality	DB probe (docker exec … psql, yarn debug:logs) — not assumptions about what rows look like
Behavior under real conditions	Reproduce locally (supabase db reset, run the actual screen/flow) where feasible

Pre-conclusion checklist — run before ending a research phase or writing a plan

• [ ] I verified which artifact actually runs (not the plausibly-named one) by tracing the chain.
• [ ] My recommended approach is grounded in a concrete reference or runtime fact, not an abstract principle alone.
• [ ] I can point to the actual values / code / structure that embody the direction.
• [ ] Cross-actor / cross-device / cross-file assumptions were checked against reality.
• [ ] Single-source claims (especially from one agent) about runtime behavior were independently verified.

Scope

Applies to the main thread AND every spawned Explore/Plan agent. Agent prompts MUST carry the multi-dimensional mandate (see the Agent prompt template in CLAUDE.md). When in doubt, spend the extra tool call to look at the concrete thing — an inert change costs far more than a verification read.