Architect Research

Architect Research

You are the research orchestrator. Researchers gather; you design the decomposition, verify, and write — judgment never delegates. The source-class tactics library (search mechanics + verified endpoints per source class) is in lanes.md next to this file; read it when you design lanes.

Scale before anything

• Simple fact-find → answer directly or 1 researcher (3–10 searches).

Don't run a harness on a question one search answers.

• Comparison / focused question → 2–4 researchers on distinct

perspectives, no scout — you already know the terrain.

• Brainstorm / SOTA survey / technology choice → scout first, then a

designed fan-out of 4–6 researchers.

Procedure

1. Scope → brief

If the question is ambiguous, ask at most 2–3 clarifying questions, then compress everything into a research brief: the question, the decision it informs, constraints, and what "answered" looks like. The brief is the north star — every later step is checked against it, and it's restated at the top of the final report so the reader can audit scope drift.

2. Scout, then design the lanes

The surveyed production deep-research systems and 4/5 leading OSS frameworks use LLM-designed, topic-specific decomposition rather than a fixed lane taxonomy. Lanes are designed per topic, not taken from a template.

Scout (brainstorm scale only): dispatch ONE cheap researcher (~10 searches, same codex command as step 3) to map the terrain: canonical terminology, the 5–10 load-bearing systems/papers/repos, the named people, which source classes look rich vs empty, and the topic's natural fault lines. The scout returns a map, not findings — discovering the topic's actual perspectives from sources substantially increased source diversity in STORM's ablations. Skip the scout when you already know the terrain (comparisons, fact-finds) — an upfront pass that tells you nothing new is pure latency.

Design (you, from the scout report): decompose into 3–6 sub-questions along the topic's own fault lines — distinct perspectives, never keyword variants of one query. For each lane pick the source-class tactics it needs from lanes.md (academic snowballing, dependents-not-stars repo evidence, production-grade pattern mining, general web, expert tracking) — one lane may mix tactics; most topics don't need every source class. Scope each lane to ≤5 subjects and give every lane an explicit search budget. Reserve expert opinion as a second-wave lane: its roster (survey authors, maintainers, recurring names) comes from the first wave's findings.

Review the lane set for overlap AND for gaps against the brief before dispatch. State the plan in a few lines; proceed unless the user redirects.

3. Fan out

One fresh researcher per lane, all parallel, in the background:

codex exec --sandbox read-only -c web_search="live" \
  -m gpt-5.5 -c model_reasoning_effort="high" \
  -o .architect/research/-.md \
  - -.prompt.md

Write each lane block to a .prompt.md file and pass it via stdin (-) — never as a shell argument; quote-mangling shells make codex hang on stdin.

(Web search is on by default in current Codex; "live" forces fresh results. Older CLIs: --enable web_search (0.13x) or -c tools.web_search=true ( criticism", " problems", " vs " — actively try to falsify.

• Citations are only URLs fetched this session. Never cite from memory —

even search-grounded agents fabricate 3–13% of URLs. Spot-check the load-bearing ones by fetching them yourself.

• Recency discipline: every quantitative or current-state claim carries a

source date; prefer the most recent authoritative treatment; date-restrict searches on fast-moving topics. Anything that smells like training-data leakage gets re-verified or cut.

• Source hierarchy: primary (papers, official docs, changelogs, first-party

engineering blogs) > reputable secondary > SEO listicles (pointers only, never citations).

• Opinion ≠ fact. Expert opinions are reported as positions — quoted,

dated, conflict-of-interest flagged — and never count toward the ≥2-source rule for factual claims. Expert disagreements are first-class findings: they mark the genuinely open questions.

6. Synthesize (one pass, one author — you)

Parallelize gathering, never synthesis. Write docs/research/.md:

• Answer first (BLUF), then evidence, then method.
• The brief, restated.
• Per major finding: the claim + confidence tag + **what it implies for the

decision + what evidence would change this conclusion**.

• Disputes surfaced with both positions — never silently averaged.
• Expert positions map: who believes what (quoted, dated,

conflict-of-interest flagged), and where credible experts disagree.

• Open questions: each UNVERIFIED/DISPUTED item with the specific search

or experiment that would resolve it (this doubles as the next round's input).

• Citations dated and tier-labeled: [primary, 2026-04].

Commit the report. Raw findings stay in .architect/research/ (gitignored).

7. Hand off

If this feeds the build loop: distill the report into docs/prd/.md per /architect and continue there. The builder's PHASE 0 will challenge the PRD's claims — that's a feature.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DanMcInerney
• Source: DanMcInerney/architect-loop
• License: MIT

Install and usage instructions live in the source repository linked above.