Research Thread

Research threads

A research thread is one of the four thread profiles, alongside the implementation thread (build-the-decided-thing, the implementation-thread skill), the plan thread (settle-the-approach, the plan-thread skill), and the audit thread (verify-parity, the audit-thread skill). Its deliverable is a fact, written down — wiki/research/<topic>.md. It is the thread you open when what is true is the open question.

Scope gate — is this a research THREAD?

Most questions are not. The alternative to guessing is not only "dispatch a researcher" — it is "go read it". A few greps and the file they land in answer nearly every question about this codebase, first-hand and faster than a second-hand claim you must re-verify. AGENTS.md's prior-art reflex — spend the first few minutes finding out how a thing has already been solved — fires on EVERY non-trivial work item, and that scan is not a thread.

A research thread earns its own effort when the question needs breadth you cannot hold in one pass: a survey across several projects, independent sources that must be reconciled, a long empirical sweep, or a decision that will be cited for months. If the answer fits in a paragraph of your handoff, write the paragraph and skip the doc.

The method

The order is the point — each step is cheaper than the one after it, and each kills theories the next would otherwise have to disprove.

1. Search before theorizing. Reach for web search eagerly and repeatedly; one search either hands you the answer or tells you you are first. When a dependency, runtime, or API surprises you, search its issue tracker, release notes, and the integrating projects' issues FIRST. A theory built from local evidence alone produces a confident, wrong story that survives until the next piece of evidence kills it.
2. Read the source locally, never one file at a time over HTTP. git clone --depth 1 <repo> .repos/<name> (gitignored), then grep and read a whole consistent tree. Check what .repos/ already holds first — it carries 290 clones today, node/, bun/, pnpm/ and tsx/ among them. Never modify anything under .repos/.
3. Read the resolution, not the issue body. A body says what someone wanted; the maintainer comments and the reason it closed say what is true. An "open feature request" is often a deliberate rejection with the rationale in the thread.
4. Hunt what was TRIED AND ABANDONED. It lives in issue threads, release notes, and RFCs, and it is invisible in the code. A knob that shrank across releases, or a feature reverted one release after it shipped, tells you more than the current implementation does.
5. Probe rather than reason. A throwaway fixture, a standalone rustc file, or a differential run against the real tool answers "what does it actually do" faster and more reliably than tracing source. Ground every claim in code or an experiment, never memory — and label UNVERIFIED anything you could not run.
6. Check whether their constraint is YOUR constraint. Another project's rejected approach may have been rejected for a reason nub does not share, which can make an option they closed off correct here. A survey that only tells you what to copy is half-read.

Reversing a conclusion on new evidence is correct, not flip-flopping. State the current verdict, keep probing, and let evidence move you rather than defend the first answer.

The publication gate — wiki/ is TRACKED and PUBLIC

Read AGENTS.local.md → "What goes in the PUBLIC wiki/ vs the PRIVATE internal/" before writing a line. Default to internal/: a wrong exclusion costs a later copy, a wrong inclusion is permanent. Four things never go public — unimplemented roadmap, the narrative of a dead end pursued too long, competitor SCORECARDS (a factual technical statement about another tool is fine and makes the mechanism legible), and any deliberation about how benchmark results were framed.

A doc that is mostly publishable with one bad section gets the section cut, not the doc dropped — then re-read the remainder for framing that only made sense next to what you removed. Separately, even a perfectly publishable doc about an UNSHIPPED feature stays on that feature's branch until it ships.