research

Research — Hybrid Router + Fallback

The runtime orchestrator for the research domain. Architecture C: deterministic classification → specialist delegation OR own plan-decompose-search-synthesize-cite workflow.

Portability

Requires WebSearch + WebFetch for the fallback workflow; specialist skills (pulse, grants, litreview, syllabus, patent, dossier, deepread) must be present for delegation to work. Node.js with docx package required if Q2 = document mode. Works in Claude Code CLI natively. In Claude.ai with web tools + Code Execution, the workflow is supported.

Distinct From engineering/autoresearch-agent

These two skills share the word "research" but serve completely different use cases:

• research/research/ (this skill) — research-query router + fallback workflow ("Research X")
• engineering/autoresearch-agent/ — Karpathy's autonomous file-optimization experiment loop ("Make this code faster")

No overlap. They coexist.

Hybrid Architecture (C)

Every invocation produces one of three outcomes:

1. Delegation — Classified as specialist-domain. Routes there. User sees the specialist's output.
2. Fallback execution — Classified as general research. Runs own plan → search → synthesize workflow.
3. Clarification request — Classification ambiguous OR a single bare-noun signal matched. Asks one forcing question (with a recommended answer) to disambiguate, then routes.

The skill never silently runs its fallback when a specialist would have done better. Routing transparency is what makes the hybrid architecture trustworthy.

Specialist Registry

Escalation → deep-research: when a wrong answer is expensive (strategy, comparing N options, hypothesis validation, mapping a field) and rigor matters more than speed, escalate to the deep-research skill instead of the fast fallback workflow — it runs a triangulated, multi-round, adversarial investigation and persists an auditable, reusable research folder. This router is the fast path; deep-research is the heavyweight one.

Agent Integrity Rules

This skill obeys the research-pack convention:

• Execution discipline (fallback only): Sequential searches. 1 q/sec rate limit. Confirm response received before next call.
• Source discipline: Cite only sources returned by this session's tool calls. Training knowledge labeled [Background — not from search] and excluded from counts.
• Three-count tracking (fallback only): Queries sent / sources received / sources cited.
• Retry policy: On failure → wait 3s → retry once → log. After 3 consecutive failures: stop, alert user.
• Routing discipline: Never delegate silently. Always state the decision + accept override.

Phase 1: Grill-Me Intake (2–4 Questions)

Intake is intentionally minimal — the goal is to route fast, not to interrogate. One question per turn.

Q1 (always) — Research question

What's the research question? State it in 1–2 sentences. Specific is better than broad — "AI for healthcare" gets you a vague survey; "How are health systems integrating LLM-based clinical decision support?" gets you a useful answer.

Refuse mush. If user says "research AI", push back once: "What about AI specifically — adoption, safety, capability, funding, regulation, comparison? Pick an angle."

Q2 (always) — Output preference

What output do you want? Pick one:

1. Quick chat briefing (5-min read, markdown in chat)
2. Standalone document (.docx with citations, shareable)

Forcing choice. Document mode triggers deeper search budgets and full audit logs.

Q3 (asked only when classification returns ask or fallback with no signals) — Domain disambiguation

Quick clarification — pick the closest match (recommended: {N} — your question matched a {specialist} signal):

1. Academic literature (papers, peer-reviewed)
2. Industry / trends (what's the buzz, news, sentiment)
3. Specific entity (a company, person, organization)
4. Technology / patents (prior art, IP landscape)
5. Grant funding (NIH, foundations)
6. Course material (syllabus or curriculum)
7. None of the above — run general research

When the classifier returned ask (single bare-noun signal), pre-mark the recommended option. Skip if classification produced a silent route (≥2 signals OR one strong multi-word phrase).

Q4 (asked only if Q3 was needed AND user picked "none of the above") — General-research scope

For general research, what's your time horizon — quick scan (5 searches) or thorough (15 searches)?

Skip if a specialist took over.

Stop condition: After Q4 (or earlier if dependency skips applied), commit and start Phase 2. Most invocations exit intake after Q1 + Q2.

Phase 2: Deterministic Classification

This is deterministic, not LLM-reasoned — for speed, debuggability, and consistency.

SIGNALS = {
  pulse:    ["reddit", "hn", "hacker news", "x.com", "twitter", "buzz",
             "sentiment", "trending", "what are people saying",
             "what's happening", "the conversation around",
             "pulse on", "take the pulse", "current conversation"],
  grants:   ["nih", "grant", "grants for", "r01", "r21", "k-award", "reporter",
             "nosi", "funding", "fda", "study section", "principal investigator"],
  litreview:["literature review", "lit review", "litreview", "pico", "spider",
             "systematic review", "review papers on", "research papers on",
             "papers about", "meta-analysis"],
  syllabus: ["syllabus", "course outline", "curriculum", "reading list",
             "for my class", "for my students", "course material"],
  patent:   ["prior art", "fto", "freedom to operate", "patent",
             "patent landscape", "invention", "novelty search",
             "patent search", "ip landscape"],
  dossier:  ["dossier on", "due diligence", "background check",
             "prep me for", "competitor research", "investor diligence",
             "interview prep", "research my competitor", "background on"],
  deepread: ["deep read", "deeply read", "read this book", "read this pdf",
             "read this document", "extract the claims", "extract claims from",
             "knowledge map", "feynman", "argument map"]
}

# Signals are case-insensitive literal phrases (multi-word substring match).
# Bracketed placeholders (e.g., "research [company]") are intentionally NOT
# signals — they over-trigger on generic "research X" queries that should
# fall back to general research, not auto-route to dossier.
# STRONG signal = multi-word phrase (contains a space): pairs verb with noun
# ("dossier on", "prior art") and routes reliably.
# BARE-NOUN signal = single word ("funding", "fda", "patent", "grant"):
# too weak to silent-route on alone — it must trigger Q3 with a
# recommended answer instead.

For each specialist S:
  score[S] = count of SIGNALS[S] phrases matched in question (case-insensitive substring)

if max(score) >= 2:
  route_to = argmax(score)                  # high confidence — silent route
elif max(score) == 1 and only one specialist has score 1:
  if the matched phrase is multi-word (contains a space):
    route_to = that specialist              # strong phrase — silent route
  else:
    route_to = "ask"                        # bare noun — ask Q3, recommend that specialist
else:
  route_to = "fallback"                     # ambiguous or no match — ask Q3 / run fallback

Implementation: scripts/classifier.py --question "..." returns the routing decision + matched signals + per-specialist scores + (for ask) the recommended specialist. Use it; don't re-implement. The SIGNALS map and rules above are kept phrase-for-phrase in sync with the script — drift = bug.

Phase 3a: Specialist Delegation (≥2 signals OR one strong multi-word phrase)

When delegating:

1. Pass the user's question verbatim plus the output preference (Q2)
2. Let the specialist run its own grill-me intake — do NOT pre-answer specialist questions
3. Return specialist output as the user-visible result
4. Tag the result with [Delegated to: research → {specialist}] in the chat output so the user knows what skill produced it
5. Tag the audit log via scripts/routing_transparency_logger.py --action record_delegation

Phase 3b: Own Fallback Workflow

If routing produced no specialist match (and Q3 confirmed general research), run the 8-step fallback:

1. Decompose — break the question into 3–5 sub-questions (what / why / how / who / what's next). Show the decomposition before searching. scripts/fallback_decomposer.py --question "..." gives a deterministic starting point.
2. Source selection — per sub-question: recency → WebSearch+WebFetch (+Reddit/HN on signal); technical/docs → WebSearch+WebFetch; academic → Consensus MCP if connected, else WebSearch with scholar.google.com site filter; data/numbers → WebFetch primary documents; entity-level → offer dossier re-route.
3. Search — sequential per sub-question, 1 q/sec, 2–4 queries per source, broad-to-narrow.
4. Read + extract — WebFetch high-signal results; note every source URL.
5. Synthesize — 2–4 paragraphs per sub-question with inline citations; surface disagreement when sources disagree.
6. Cross-cutting patterns — 1–2 paragraphs across sub-questions: consensus, controversy, gaps.
7. Output — markdown brief by default; DOCX if user picked document mode.
8. Audit log — three counts (sent / received / cited) + per-source reliability tier (primary / secondary / tertiary).

Routing Transparency Protocol (Mandatory)

After classification, the skill always:

1. States the decision in one sentence: "Routing to litreview because you mentioned PICO and meta-analysis (2 signals)."
2. Offers override: "If you want general research instead OR a different specialist, say so now."
3. Proceeds with the recommended route if the user doesn't object — no timers, no countdowns.
4. If user overrides → accept, re-route, log the override via routing_transparency_logger.py --action record_override.

Never delegates silently. This is the trust-building property that makes the hybrid pattern work.

Output Format

Markdown brief (Q2 = quick chat briefing): title + *Generated: [DATE] | Routed: [specialist | fallback]*, then TL;DR (2-3 sentences) → Findings (one H3 per sub-question, inline citations) → Cross-Cutting Patterns → Sources (numbered, hyperlinked, reliability tier each) → Audit (three counts + failures).

DOCX (Q2 = standalone document): standard research-pack DOCX patterns — Arial 12pt, navy headings, blue table headers, hyperlinked sources, mandatory audit log section. Reference the docx skill for setup.

Audit log block (fallback mode)

Queries sent: N | Sources received: M | Sources cited: K
Failures: F (3-consecutive-failures triggered: yes/no)
Per-source tier: [URL — primary | secondary | tertiary]
Routing decision: fallback (no specialist matched)
Sub-questions: [list]

All routing decisions + overrides also logged to ~/.research_sessions/<session>.json via routing_transparency_logger.py.

Failure Modes

Anti-Patterns Rejected

• LLM-reasoned classification (must be deterministic keyword + intent matching)
• Silent delegation (always surface routing decision)
• Refusing to route to a specialist when ≥2 signals match
• Silent-routing on a single bare-noun signal ("research FDA approval trends" must ask, not auto-route to grants)
• Wall-clock affordances ("auto-proceed after Ns") — the model cannot wait; proceed with the recommended route if the user doesn't object
• Pre-answering the specialist's grill-me intake (let it run its own)
• Fabricating sources in fallback when search is thin
• Skipping audit log in fallback mode
• Treating "dossier on [company]" as fallback when dossier is the right specialist (the verb-noun-paired phrase routes; the generic "research X" form does not)
• Auto-routing generic "research [topic]" queries to a specialist ("research Microsoft" alone is ambiguous — could be dossier or general; ask Q3 instead of guessing)

Tooling

• scripts/classifier.py — Deterministic SIGNALS matching → routing decision (specialist / ask + recommended / fallback) + per-specialist score + matched phrases. --question "..." --output json.
• scripts/routing_transparency_logger.py — JSON-backed audit log at ~/.research_sessions/<session>.json. Records every routing decision, override, and delegation handoff.
• scripts/fallback_decomposer.py — Heuristic question → 3–5 sub-questions (what / why / how / who / what's next).

Reference Docs (each cites 7+ authoritative sources)

• references/hybrid_router_architecture.md — router-vs-run trade-offs + routing transparency principle
• references/deterministic_classification_canon.md — why keyword > LLM-reasoned for routing
• references/fallback_workflow_canon.md — plan-decompose-search-synthesize methodology

Dependencies

• WebSearch + WebFetch — Required for fallback workflow
• Specialist skills — Required for delegation: pulse, grants, litreview, syllabus, patent, dossier. If a specialist is missing, the router skips it and routes to fallback instead.
• Node.js docx library — Required if user picks document output (Q2 = standalone)
• Consensus MCP — Optional; used in fallback if academic sub-questions surface

Version: 1.1.0 Source spec: megaprompts/13-research-megaprompt.md (maintainer-local draft spec — gitignored, not present in the public repository) Build pattern: Path B (direct conversion). v1.1.0: bare-noun signals now ask instead of silent-routing; 5s auto-proceed affordance removed; context-economy trim per the 2026-06 newgen audit.