unclejobs-ai/second-claude-code/research

Resolve runtime paths before operations.

Iron Law

No guessing. If there is no data, collect it first.

Red Flags

• "This one article covers everything" → STOP. Single-source = blind spots. Depth minimums (3/5/10) exist for a reason.
• "I already know the answer, just need a citation" → STOP. Confirmation bias produces cherry-picked sources.
• "Source is from 2022 but topic hasn't changed" → STOP. Staleness must be verified, not assumed.
• "Skip the analyst step, just list links" → STOP. Raw link dumps without gap analysis are rejected.
• "Page was blocked so I'll summarize from the URL title" → STOP. Use fallback chain (Jina → Playwright → Gaps), never hallucinate from metadata.

Research

Autonomous multi-round web research that produces structured Research Briefs.

When to Use

• User asks to research a topic, trend, or question
• Another skill (e.g., /scc:write, /scc:analyze) needs source material
• User wants competitive intelligence, market data, or literature review

Web Engine

The researcher uses Jina Search (s.jina.ai) as the primary tool. Fallback chain: Jina Search → WebSearch + WebFetch → the unblock chain (/scc:unblock, zero-key 9-phase) → Playwright. See references/jina-guide.md and docs/skills/unblock.md.

MMBridge Enhancement

When mmbridge is detected (see references/mmbridge-integration.md), dispatch mmbridge research in parallel with the internal researcher.

Dispatch

At Step 1, also run via Bash:

mmbridge research "<topic>" --type <type> --json > /tmp/mmbridge-research-${RUN_ID}.json

• --type code-aware: when topic relates to the current codebase
• --type open: for general topics unrelated to code
• --depth shallow: skip mmbridge
• --depth medium|deep: mmbridge enabled

Merge

At Step 3, parse the mmbridge JSON output file as supplemental source material. Count each distinct cited URL from mmbridge as one source and deduplicate overlaps during gap analysis.

Step-by-Step

1. Auto-load references/research-methodology.md and references/jina-guide.md.
2. Dispatch researcher (sonnet): run depth-appropriate Jina Search calls with varied query phrasings. If $JINA_API_KEY is unavailable, fall back to WebSearch + WebFetch. If mmbridge is available at medium or deep depth, dispatch it in parallel.
3. Validate sources: reject login walls, blocked pages, empty content. For blocked URLs, run the unblock chain (node "<plugin-root>/skills/unblock/engine/cli.mjs" "<URL>" --json); read the trace before any retry.
4. Dispatch analyst (sonnet): merge internal and mmbridge findings, identify gaps, and apply conflict-resolution rules from references/research-methodology.md.
5. Optional second round: only when depth allows and the analyst found critical gaps.
6. Dispatch writer (sonnet): synthesize the final brief with conflict annotations.
7. Verify actual search counts before output. If counts exceed the depth cap, discard excess results and re-synthesize.

Options

Depth Behavior

• shallow: EXACTLY 3 Jina Search calls. No deep reads. No gap analysis round.
• medium: EXACTLY 5 Jina Search calls plus up to 2 Jina Reader deep reads.
• deep: 10+ Jina Search calls, unlimited Jina Reader deep reads, and at most 3 gap-fill rounds before documenting remaining gaps.

When --engine legacy is set or $JINA_API_KEY is unavailable, replace "Jina Search" with "WebSearch" and "Jina Reader" with "WebFetch" in the above counts.

Coverage requirements and conflict resolution rules are in references/research-methodology.md.

Source Domain (--sources)

• web (default): General web search. No domain restrictions.
• academic: Bias at least half the calls toward Google Scholar or arXiv.
• news: Add after:30d and prefer established editorial sources over blogs.

Fallback Chain

Jina Search (s.jina.ai) ─── primary: search + content in one call
  └─ blocked/empty → Jina Reader (r.jina.ai) with X-Engine: browser
       └─ still fails → Playwright (browser_navigate + browser_snapshot)
            └─ unavailable → note in Gaps & Limitations

When --engine legacy or $JINA_API_KEY is unavailable:

WebSearch → WebFetch → Playwright → Gaps & Limitations

When --interactive is set, skip Jina/WebFetch and use Playwright for every URL.

Cost controls: Max 3 Playwright navigations per round. Exceeding the cap means skip the rest and note the gap.

Graceful degradation: Both Jina and Playwright are optional. If $JINA_API_KEY is missing, fall back silently. If Playwright MCP is unavailable, proceed without it and note unreachable URLs.

Auto-Save

• Path: .captures/research-{slug}-{YYYY-MM-DD}.md
• {slug} = topic lowercased, spaces to hyphens, max 40 chars
• Write the full brief using the Write tool and tell the user the saved path.

Gotchas

Subagents

researcher: { model: sonnet, tools: [Bash, WebSearch, WebFetch, browser_navigate, browser_snapshot], constraint: "Jina Search when $JINA_API_KEY set, else WebSearch+WebFetch; meet depth minimums, vary phrasing, validate content, flag staleness; Playwright only when Jina+WebFetch both fail; max 3 navigations" }
analyst: { model: sonnet, tools: [], constraint: "produce gap list, flag data conflicts, verify coverage requirements" }
writer: { model: sonnet, tools: [], constraint: "every claim needs a source, no invented URLs, include conflict annotations" }

Output & Integration

See references/research-methodology.md for output format template, extended gotchas table, and integration notes.