anentrypoint/research

Research

Declare the discipline before fetching anything. The first line of work names the @<discipline> the corpus belongs to — fresh material lives at .gm/disciplines/<name>/corpus/raw/, concise rewrites at .gm/disciplines/<name>/corpus/concise/<chunk-id>.md, the merged synthesis at .gm/disciplines/<name>/deep-understanding.md. A run without a discipline declaration falls back to the default store and the orchestrator says so in one line.

Lead orchestrates. Workers fetch. Findings converge on disk. The lead never reads pages — workers do.

Treat a thousand-document corpus with the same care as a codebase. Material above roughly ten pages — about eight thousand tokens — splits at paragraph boundaries into chunks each owned by one parallel gm:research-worker (haiku model). Each worker emits a fact-preserving concise rewrite to corpus/concise/<chunk-id>.md — every claim, number, name, caveat from the source survives, prose density rises, citations stay attached. Once every chunk returns, the lead merges into deep-understanding.md enumerating the opportunities the corpus opens and the reasonable opinionations it forces. Concise files and the merged document auto-ingest via exec:memorize @<name> so the next pass recalls instead of re-fetching.

Effort matches stakes. A single fact is one short fetch. A vendor comparison is a handful of workers, each owning one vendor. A landscape survey is ten or more, each owning one axis. Spending a fan-out on a fact wastes tokens; spending a fact-fetch on a landscape under-delivers.

Breadth first, depth on demand. Open with a wide sweep that maps the terrain, then commit deep dives only where the sweep surfaces something load-bearing. A narrow opening misses the alternative the user actually needed.

Worker contract

Each worker receives the precise question it owns, the shape of the answer (bullets, table row, prose paragraph), the boundary of what it must not pursue, and the destination path under .gm/research/<slug>/<worker-id>.md. Workers write structured findings to disk and return only a path plus a one-line summary. The lead reads the paths it cares about; the rest stay on disk. Returning full prose through the agent boundary burns context that the synthesis pass needs.

Workers run in parallel — independent questions launch in one message, never serialized.

Citations

A claim without a source URL is a hallucination waiting to be quoted. Workers attach the URL and the quoted span beside every non-trivial assertion. The lead refuses to lift a claim into the final answer if its citation field is empty.

Source quality

Vendor docs, RFCs, primary repos, dated blog posts from named authors, and academic preprints beat aggregator pages. When two sources disagree, the older primary usually beats the newer aggregator.

Convergence

Synthesis happens once, after all workers return. Mid-flight summarisation truncates findings the next worker would have built on. If a worker's return reveals a new axis the original plan missed, expand the fan-out — do not stretch an existing worker past its brief.

When not to fan out

One question, one page, one fetch. A single WebFetch answers it. The fan-out machinery has overhead; spending it on a lookup is the same mistake as skipping it on a survey.

Handoff

Final answer cites every load-bearing claim, names the workers' output paths for audit, and surfaces disagreements rather than averaging them away.