skills / research

---
name: research
description: Runs deep, task-independent research with parallel subagents and turns it into one evidence-backed decision. Use whenever the user asks to research, investigate, explore options, find the best way or best practice, compare approaches, look at how others do it, check sources, "google it", do a deep dive, or decide whether a library, tool or an article's approach is usable for us (read the library itself, not just the article), even when the word research is never used. Works for code changes, new components, bugs, performance, design and visual exploration, animation and physics, writing, naming and product ideas. Not for a single fact lookup in a known file or for applying a fix that is already chosen.
argument-hint: "[question, task or topic]"
---

# Research

Research question: $ARGUMENTS

The output is a decision the user can act on, with evidence they can check. Research fails on a claim checked somewhere other than where the result lives, a gain measured against the wrong baseline, or a costly path nobody re-decided. These rules hold for every later wave and fix round, not only the first pass.

## 0. Frame it before spawning anything

1. **Look at our own reality first.** Read the relevant code, design file, assets, memory and prior notes, so research answers questions about this project; note what could be reused or is already broken. Check a prior analysis against the versions installed now; stale analyses are the most common hidden error. Before claiming something is unreleased, missing or "latest", refresh upstream (`git fetch` + `origin/<default>`, `npm view <pkg> versions`) and state the ref and date read. Before changing an existing setup, find out why it is that way (commit, PR, memory); odd settings are often deliberate.
2. **Write the framing block.** Every brief inherits it:
   - **Goal**, paraphrased.
   - **Keep vs may change.** Search for options that keep everything before offering a trade-off. Unless the user says otherwise, Keep includes current consumers' behaviour (presets, defaults, semantics) and the perceived look of an existing visual system (weight, density, zoom scaling); changing one is a fork, never part of the pick. A new surface beside the old (a new attribute or API) is free.
   - **Hard constraints**: stated, plus implied wherever it can end up (a library in other hosts, a name in other languages, a pipeline at other volumes).
   - **Policies only the user knows**: compatibility and whether unused things may be removed; which code stays, gets rewritten or is legacy; the range of inputs future users or themes will set; what may appear in the UI; new dependencies and cost; what may be pushed, PR'd or published; whether heavy local runs (servers, builds, browsers) are allowed. Check memory, then ask the open ones in one batched question before launch. In don't-ask or delegated mode, take the cheapest-to-reverse default and list it as an assumption at launch (§3).
   - **Who builds and maintains it** (you and agents, the user, a team), when not obvious.
   - **Taste**, quoted: liked and rejected, from this request or memory.
3. **Pin down every domain word.** "Drawer", "card", "loop" mean different things in UI, furniture and music.
4. **Name the real environment** where the result will run or be judged and how it differs from your setup (hardware, settings, data volume, real integration, real audience). For code that includes the consumer's runtime and framework versions (check every API against them), every build target its users hit, and its real config or transformer, not library defaults. A result from a different setup is a hypothesis about the real one.
5. **Beyond a one-agent question, state value and budget.** Its worth in the user's units next to the honest cost (time, risk, breaking changes, complexity), with "do nothing" as an option. State effort in the builder's units (sessions, not engineer-weeks, when you build it). Set a budget and what sends the choice back to the user; reuse this value at every fork.
6. **Scale the effort to the question.**
   - **One fact, one file:** no agents. **Small change, one unknown:** one agent or yourself.
   - **Several unknowns:** 3–5 agents, one axis each.
   - **"Find the best way", taste, physics, an unknown field:** 4–6 agents, then a narrower round of 2–3.
   - **Divergent visual or idea exploration:** 4–10 agents, one variant each along a real axis; 20+ only when the user asks (a standing rule in memory counts).

   More agents is not better (a fan-out costs roughly 15× a chat). A large `Workflow` fan-out needs the user's explicit opt-in. When the user asks for depth (a huge research, as many agents as needed, spend the tokens, ultracode), plan the larger budget and at least two rounds from the start, with prototypes where alternatives remain (§4).
7. **Ask only what research cannot answer**, once, with options and a recommendation.
8. **When the user reports a defect, collect what they observed first** (steps, setup, timing). Unreproduced, any fix is a guess.

## 1. Choose directions

Orthogonal axes, one per agent. Drop what does not apply:

- **What we build on.** Source and issues at the installed version; newer changelogs.
- **How others do it.** Their source and bug trackers, not READMEs.
- **Our own conventions.** Existing patterns with exact code and values, so the result looks native.
- **Real usage.** Where it is used today: counts, inconsistent copies, latent bugs; search by what changes, not only importers. This is the baseline for every claimed gain.
- **The craft or physics.** For visual or behavioural work, the domain the effect comes from (animation, perspective, painters' shadows, biomechanics, physics, typography, music, browser internals, accessibility specs).
- **The unnamed option.** Approaches nobody listed, or the case against the favourite, including "keep what we have" and "remove the mechanism entirely".

List who would see the problem differently and route their questions into the briefs (`references/briefs.md`). With 2–4 known alternatives, each becomes its own direction and the cross-cutting axes stay separate; otherwise each agent compares every option it finds.

## 2. Write the briefs

A subagent knows nothing about this conversation. Read `references/briefs.md` (shared context block, templates 1–9) before writing. Every brief has:

1. **Context**: stack, versions, the framing block, what was tried or rejected and why, method lessons ("the isolated test overstated the gain").
2. **Numbered questions that name the suspected pitfalls.**
3. **Primary sources**: `file:line`, specs, maintainers, named craft authors, exact URLs; the real artefact.
4. **Method**: measure in the 0.4 environment and say whether the method exercises the mechanism (a still frame does not test motion). Read-only unless it is a prototype; a missing build or browser policy is asked in the 0.2 batch, not silently written into the brief as "no builds".
5. **Isolation**: own copy; nothing shared touched without checking what the write triggers. A time budget for long steps and what to do when it runs out.
6. **Honesty**: tag each claim [S] sourced, [M] measured or [I] inferred, including why a number moved; say what could not be verified and where each measurement ran. Never fill a gap from templates or memory silently.
7. **Deliverable**: a word cap (500–1500), a fixed shape, a closing "must do or avoid" list. Long notes go to the scratchpad.

## 3. Run

- Launch every independent agent in one message, in the background, and post the framing in 3–5 lines (goal, keep, constraints, assumed policies including ones from memory, one line per agent); the user can correct it while agents run, don't wait. Meanwhile read our code, measure the current state, build a test page or harness. Don't redo a delegated search, predict pending findings, or build or show deliverable variants before the agents that shape them report.
- Agent reports are invisible to the user. Relay each finding that changes the picture in a sentence or two as it lands, with what is still running; skip interim relays when everything lands within minutes, and don't retell relayed findings in the final report. Asked what you are doing, give the problem and the finding.
- Summarise what the agent returned, not what you asked for. Its "X does not exist" is [I] until you search yourself under a few names (and folders like theming/, utils/, internal/) at the latest remote or release; list what you searched.
- Your own claims carry the same tags, including numbers in the deliverable (drawing, spec, table): a fitted value is ≈ with what it was fitted to. An unisolated cause is a hypothesis.
- Correct a running agent with SendMessage instead of restarting it. If a step is over-scoped, reread your brief first; restart only if cheaper.
- Check elapsed time against each budget, your own background commands included; anything expected past ~10 min gets a watchdog (Monitor with a deadline). ETAs come from measured throughput with the arithmetic shown, never from the plan; name what they leave out (reviews, retries, the user's checks).
- The machine is the user's. Run timings alone; run tests under nice with 2 workers. Keep a ledger of every agent, shell, server, browser, worktree, scratch folder and moved user file you start or touch.
- Sweeps and inventories can run on `model: "haiku"` or `"sonnet"`; keep judgment for yourself.

## 4. Synthesise and choose

- **Fix the criteria before scoring**, compare in a table, steelman each option. A new dependency's size, licence and upkeep are criteria.
- **For an API, config, naming or architecture choice, write out three cases**: the common one, the maximal one with every option set (planned ones too), and the most different realistic future case from memory, open work or the user's examples. Show each call site and the cost of one more item; if each case needs a new key or every call site repeats the same wiring, the shape is wrong.
- **Settle disagreements with a measurement**, between agents and against existing instruments; explain the gap before claiming a result. When 2–4 alternatives remain and synthetic tests cannot settle them, prototype each on one shared harness plus a control build and measure in real builds and browsers.
- **Look for the gap between reports**: the check no agent ran. When one axis's finding touches another's pick, re-score it. When prior art argues against a clever winner, recommend the simplest variant that fixes the symptom, removal included, and offer the clever one as an add-on with its cost. In production with no reported problem, "do nothing" is the default.
- **Turn references into principles, then recombine.**
- **Do a second, narrower round**; if the first method misled, change it.
- **Treat a review finding as a class**: name it, sweep every instance, then fix.
- **Two strikes, then change method.** This holds in the build and fix loop too, visual defects the user reports included. When two fixes in a row each reveal a new defect, or the user says "still wrong" a third time in a row, stop patching. Before the next fix, rethink the model, build an automated check that catches the class (frame capture, a diff against the reference), or run a narrow research round. If none fits or the 0.5 budget runs out, put continue / simplify / revert to the user with 0.5's value and cost, even in don't-ask mode. Sunk effort is no reason to continue.
- **Variant gate, before showing anything.** Write each variant's model in one phrase (the idea, not placement, layout or colour); merge any two that share one. Include the user's earlier pick or approved work as a baseline, the mainstream pattern the research found, and one that goes too far. A requested count is met only with distinct phrases: when ideas run out, run another axis or method, never reskin. Show each in a faithful frame of the real product (chrome rebuilt from code), a page part inside its whole page. A pattern for many items goes on a fixed set (none, one, many, complex, nested, phone) as a model-by-item matrix; a component with options gets a state matrix (each option alone and combined, open/closed, light/dark). Edge cases: longest, empty, both locales, mobile, RTL, reduced motion. Check each at real size against slop patterns and the user's recorded rejects; show every survivor, 2–3 picks marked, weak spots named.
- **Explore beside the work**: a separate page; merge what the user picks; roll out on approval. Boards nobody asked for go to the scratchpad. Never delete undecided work.
- **The user decides the forks.** Cost in visible terms ("20px of empty column on page 1"), one recommendation; if the user overrides an agent, follow the user.

## 5. Verify before every report

Before every report and hand-off, each fix round included:

1. **Run the real path yourself**: the 0.4 environment, the real integration, the user's own steps and timing (scrolling during load, not after idle). Motion as full uncropped frames or a recording at real fps; every theme, state and breakpoint you changed. "Built" or "tsc passes" is not checked; a stand-in is reported as unchecked.
2. **Keep a regression list** in a scratchpad file that survives compaction: every defect and wish the user raised in this task, re-checked with a before/after pair.
3. **An anomaly is a defect until disproven**, never explained away (crossfade, noise, "probably expected") or hidden with a tweak.
4. **Diff against the last approved version.** Report every visible change, side effects included, from the code, not memory ("didn't touch X").
5. **Render, run or record it yourself first.** "Unchecked, please look" is only for what you cannot run (sound, the user's device).

Then, with details in `references/verify.md`:

- **One acceptance list, scoped by risk**: the default environment plus one check per constraint and mechanism difference.
- **Keep every check the gate enforces.** A narrowed local set still includes what CI or review will run, or you report "passed the reduced set". CI runs the rest: after a push or PR (only when allowed), watch it to the end (`gh pr checks --watch`) and explain each failure. Never end the turn on "CI is still running".
- **Calibrate the measuring tool** on a known answer (a no-change comparison shows zero).
- **Measure the target and what it can worsen**; drop the change if the target does not move. Intermittent effects get a rate over a stated number of runs.
- **Load-bearing claims** (versions, numbers, support, licences): two independent sources or your own run.
- **Adversarial review before calling code done**, unasked and before pushing. One named risk each, pinned to a commit: consumers, contract, the claimed win, the tests.
- **Apply it completely**: other states, sizes, themes, locales; an approved change to a shared component reaches every page or file that renders it.
- **The user's eyes come after yours**: one artefact with every real context and weak spot, and what to check; ship only after they have.

## 6. Report

First clean up from the §3 ledger (`references/verify.md`): stop what this run started except what the user needs for checking; save undecided work as a patch before deleting a worktree; put moved files back.

Chat uses the user's language; what others read (artifacts, PR and commit text, docs, captions, canvas copy) uses its audience's or repo's, English for work unless memory says otherwise, sized for that reader. Chat report short, full tables in a file:

1. The decision in one or two sentences, then one line per hard constraint: kept or not, how checked. Unchecked parts go in the headline ("fixed in A and B, C unverified").
2. The 3–6 facts that decided it, each with source or measurement and where.
3. Alternatives, including doing nothing; for something the user built, theirs vs proposed first, 3–4 pros and cons each.
4. What was verified, what only in a stand-in; "not verified" lists only what you could not run. Each defect names its setup (DPR, browser, OS, data size) and whether that is the user's.
5. Forks the user still owns: what they would notice, a recommendation, its cost, readable without the earlier chat.
6. Visual or runnable work: running and opened, with the URL, old beside new; what to check and how to reply (a line per browser or context, what counts as a pass).
7. One line: what was stopped, what still runs and why, what is left on disk with sizes.

## Red flags

Failures from real sessions, and the fix.

- **Building the first idea.** Candidates, research, compare, then pick.
- **"Verified" or "done" via a bypass, or without a screenshot or number.** Re-check where it lives, or say unchecked.
- **The fix scales, rotates or hides the symptom.** Rethink the model; name the principle you broke.
- **Two variants share one phrase, the count came from reskins, or agents were told "make 5 more".** Give each a distinct axis value; rerun the gate and research new axes.
- **The output looks like the reference, or drifts from one given as a spec.** In exploration, extract principles. When it is the spec, measure it, compare side by side, add nothing it lacks.
- **Research says X, the spec or physics says Y.** Spec and physics win; state the deviation.
- **A fix deletes or restyles something the user liked.** When feedback names a quality of X (slow, crooked, too big), fix that quality and keep X. When told you broke it, restore the last approved state exactly (git or snapshot), not a new interpretation.
- **A bot, agent or reviewer claim you have not reproduced.** Reproduce or disprove it before acting.
- **Asking "which next?" in a delegated exploration.** Pick, continue, report.
- **The user rejected a whole wave.** Restate the goal and what they liked; research before making more.

# Brief templates

Adapt one per direction. Each is a real prompt shape that produced a report the lead could act on. Fill every `<…>`; delete lines that do not apply. Keep the shared context block identical across the agents of one round so their reports are comparable.

## Who sees it differently

Before writing questions, list who would see the problem differently (implementer, maintainer, end user on touch, screen-reader user, the skeptic) and put their questions into the briefs of the axes they belong to.

## Shared context block (paste at the top of every brief in a round)

```
Read-only research; do not edit project files. You may write notes to <session scratchpad dir>/<topic>/. Measurement and prototype agents may install, build and run inside their own scratchpad dir when the lead asked for prototypes.
Work in your own copy (<worktree / sandbox / instance>) and on your own port. Stop every server, browser and process you started before you return. Touch nothing shared (the user's screen and input, production data or jobs, deploying branches, notifying channels) without checking what the write triggers.
Unattended run: nobody is watching to approve prompts. Never run a command that raises one (rm with globs or relative paths, cd followed by a delete, broad pkill, installs outside the sandbox). Don't delete files; write each run to a new folder.
Context: <stack and exact versions>. We are building <thing> for <who/where>.
Keep: <what must stay as it is>. May change: <what is free>.
Hard constraints: <stated by the owner> + <implied by where it can end up, not just today's use>.
Real environment: <where it runs or is seen>; what differs from your test setup: <hardware and settings, data volume, real integration vs isolated copy, real audience vs you>.
Value and budget: <benefit in measured units>; stop and report if <time / failed attempts>.
Owner taste, in their words: liked "<…>", rejected "<…>" because <…>.
Already tried or decided: <…>. Do not re-propose these.
Method lessons so far: <e.g. "the isolated test overstated the gain; measure in the real integration">.
```

## 1. Ecosystem survey ("how do others do it")

```
<shared context>
Survey every serious implementation of <problem>: at least <libs, design systems, native platforms, notable products>.
Read their actual source, not the README, and their bug trackers for complaints.
For each: approach, how it handles <pitfall 1>, <pitfall 2>, <edge case>, performance, accessibility, known bugs (link the issue).
Write full notes to <scratch>/<name>.md.
Return ≤ 900 words: a comparison table, the ideas worth stealing, the pitfalls each one hit, and your recommendation for us.
Tag each claim [S] sourced, [M] measured or [I] inferred; say what you could not verify.
```

## 2. What we build on (library, spec, API internals)

```
<shared context>
<Library> <version> is installed at <how to resolve the path>. Run git fetch / npm view <pkg> versions first and state the ref and date you read. Also search its GitHub issues and PRs (gh search issues --repo <repo> <term>), and check whether a newer release fixes anything relevant.
I need precise facts, each with file:line and a short code excerpt:
1. <What it renders / exposes>
2. <Behaviour under X, including edge case Y>
3. <What happens when Z is interrupted / disabled / reversed>
…
Before reporting that something does not exist, search for it under the other names it may go by and list what you searched.
Return ≤ 900 words, ending with "things our wrapper must do or avoid".
```

## 3. Measure and prototype

```
<shared context>
Investigate by measuring in the real environment named above (<how: the real device, integration, data or audience>). Use our own <fonts / data / assets> from <path>.
Before measuring, calibrate: run the tool on a case with a known answer (a no-change comparison shows zero) and on the owner's known-bad case, and confirm it reproduces what they see. Drive input the way the real user does (e.g. real wheel or trackpad, not synthetic events; a headed window at the real DPR, not an emulated scale factor; live compositing, not paused or seeked frames). For every A/B, screenshot each variant on the real target page and confirm only the variable under test differs (same layout, nothing broken, no background prefetch).
State why your method exercises the mechanism under study; if it cannot (a simulator, a sample, an isolated copy), say so and treat the result as a hint.
1. <Quantity to measure>, under <conditions>, in <the default environment>; in other engines or platforms only for <named mechanism risk>.
2. Compare strategies (a) <…> (b) <…> (c) <…>: pros, cons, measured cost.
3. <Edge case to reproduce>.
Return ≤ 800 words with the numbers, the environment each was measured in, the script you used, and a concrete recommended formula or setting.
```

## 4. Our own conventions (internal audit)

```
<shared context>
Read every <similar part> in <paths> fully. Quote exact <class strings / tokens / values> with file:line for: <sizes>, <states: rest, hover, focus, invalid, disabled>, <theming>, <a11y wiring>, <tests>.
Note which parts are shared and which are duplicated per component.
Return ≤ 1200 words, ending with a proposal for <new thing> derived ONLY from existing patterns, and the decisions those patterns cannot settle.
```

## 5. Real usage (consumer or data audit)

```
<shared context>
In <consumer repo / dataset>, find every place that <does the thing>, including hand-rolled versions.
For each: file:line, the exact code, <fields that matter: size, colour, behaviour, loading, RTL…>.
Report: a table of occurrences, the dominant pattern, the variations and inconsistencies, latent bugs, and what a standard <API> would need to replace them all. ≤ 700 words.
```

## 6. The craft or physics domain

```
<shared context>
Current result and why it fails: <the user's words, e.g. "flat", "stiff", "just rotating">.
Research how <animators / illustrators / painters / physicists / typographers / musicians> solve <this>, from primary sources: <named authors or texts, e.g. Williams, Thomas & Johnston, Loomis, Gurney, Robertson; papers>. Follow leads to second-level sources.
Translate the rules into numbers we can implement: <timings in frames at N fps, angles, ratios, thresholds, formulas>. Check feasibility against our real dimensions: <sizes>.
Tag each claim [S] sourced, [M] measured or observed in a reference you looked at, [I] inferred. Treat [I] as a hypothesis to test.
Return ≤ 1500 words ending with a checklist of rules the builder must follow.
```

## 7. External references with a quality bar

```
<shared context>
Find <12–18> current (<year>) examples of <thing> at the level of <bar>, chosen by the makers' craft reputation, not popularity or size. Seed list, verify each and add others: <urls>.
Return live URLs I can open (not gallery pages), one line each on the mechanic worth taking, then 6–8 distinct mechanics across them.
Return verbatim text when the text itself is the material. Max ~700 words. Mark anything you could not verify or open.
```

## 8. Variant fork (divergent exploration)

```
<shared context>
You own exactly one direction: <axis value, e.g. one reference, one domain, one layout concept, one style school>. Touch nothing else (<file, frame, coordinates>).
Concept: <one concrete paragraph>.
Quality bar: <the finished exemplar to match>. Use real content: <data>.
Frame and coverage: <real chrome source>; show it on <representative set or state matrix from SKILL.md §4 variant gate>.
Rules: <hard rules and known tool gotchas, short>.
Check your own output (<screenshot, crop, run>), critique it honestly, iterate at least once.
Report in ≤ 3 lines: what you made, what is weak, anything you were unsure about.
```

## 9. Independent verification of a claim

```
Without seeing our draft, answer: <claim turned into a question>. Use primary sources dated <after X>, and run <check> if possible.
Return the answer, the sources with URLs and dates, and anything that contradicts it.
```

# Verification details

The five-step gate at the top of SKILL.md §5 runs before every report. This file holds the detail behind the §5 bullets and the §6 cleanup.

## Acceptance list

The default environment plus one targeted check per named risk: each constraint from step 0.2 and each mechanism-level difference. A finding that shows a new variable matters adds its check. After a mechanism swap, re-run this list, not a wider matrix. Estimate how long the list takes before starting it. Breadth without a named risk burns hours and finds nothing.

## The gate and CI

- Read the gate's own config (`.github/workflows`, required checks, a review checklist) so you know what CI and review will run. If you narrowed local verification, the narrowed set still includes those checks.
- When local checks are narrowed by memory, cost or the user's machine, CI runs the rest. Report "passed the reduced set", not "passed". Don't override a memory policy that limits local runs.
- Push or open a PR only when the request or memory allows it (step 0.2). Opening a PR is publishing.
- After a push or PR, watch the runs in the background until they finish (`gh pr checks --watch` or `gh run watch`). Report each failure with its cause, or say why it is unrelated (a flake, a check waiting on a label). Don't end the turn on "CI is still running".

## Measuring

- Calibrate the tool on a case with a known answer (a no-change comparison must show zero) and check it consumes the thing the way the real system does.
- Measure the target and what it can worsen. Drop the change if the target does not move in the real setup.
- For intermittent effects, measure the rate before and after over enough runs, and say how many.
- Run timing measurements alone. Contention from parallel browsers or builds skews the numbers.

## Claims

Check load-bearing claims (versions, numbers, support, licences) against two independent sources or a run of your own.

## Adversarial reviewers

Run them before reporting a code change done and before pushing, without being asked. Give each one a single named risk and pin it to the exact commit or state it reviews; discard findings made against code that has since changed.

1. Consumers: every current consumer and its customisations (customer CSS, settings), plus every path that rewrites the shared surface the change touches (e.g. server render, hydration, client navigation).
2. Contract: the declared support range (peer versions) for every API used, consumer props or options that can override internals, failure paths that must fail loudly instead of returning a bad result.
3. The claimed win: re-measured in the real consumer and compared with the cheapest simple alternative.
4. Tests: would each new test fail on a broken implementation?

They catch in minutes what long test runs miss.

## Cleanup

Clean up from the §3 ledger before reporting (SKILL.md §6):

- Stop every agent, shell, server and browser this run started, finished agents included, except those the user needs for checking. Name those with their ports and offer to stop them.
- Before deleting a worktree or scratch copy, push or save as a patch any commit or variant the user has not decided on.
- Put moved user files back.
- Leave processes and files this run did not create alone.
- Report in one line what you stopped, what is still running and why, and what is left on disk with its size.