hint-shu/deep-research / skills/expert-research
expert-research
VerifiedExpert-level research (L3) — runs /deep-research (L2) then adds critic agent, fact-checking pass, multi-perspective search, and human-in-the-loop plan approval. ~20 min, 40-60 sources, 3000+ word report with executive summary. Use for strategic decisions, technology migrations, important investigations.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.0 KB |
SKILL.md
View on GitHub---
name: expert-research
description: Expert-level research (L3) — runs /deep-research (L2) then adds critic agent, fact-checking pass, multi-perspective search, and human-in-the-loop plan approval. ~20 min, 40-60 sources, 3000+ word report with executive summary. Use for strategic decisions, technology migrations, important investigations.
user_invocable: true
---
# Expert Research — L3
Expert research tier. **Composes** on top of L2 (`/deep-research`) by adding:
- **Human-in-the-loop plan approval** before expensive work
- **Multi-perspective search** (3 angles: proponents, critics, neutral)
- **Fact-check pass** — critical claims verified against 2+ independent sources
- **Critic agent** — adversarial review of the entire report
- **2 reflection loops** (vs L2's 1)
- **Structured decision matrix** when the query implies a choice
**Position in ladder:** L3. Calls L2 as its foundation (which itself calls L1). Called by L4, L5.
## When to Use
- Strategic decisions: migration, architecture choice, big-ticket tooling
- "стоит ли мигрировать X → Y"
- "какой стек выбрать для нового проекта"
- Investigations where being wrong costs real money/time
- When user says "критически", "стратегически", "серьёзно и надёжно"
- Default when the decision stakes are high
**Escalate to:**
- `/academic-research` (L4) — when you need scientific papers and academic rigor
- `/ultra-research` (L5) — when you want a full knowledge base and playbooks
## Budget
- Time: ~20-25 min total (L1: ~5 + L2: ~7 + L3: ~8-13)
- Tavily credits: ~150
- **Subagent tokens: ~50-80K** (critic agent via Agent tool) — added in v0.2.2 budget doc
- **Codex credits (if available): ~200-300K tokens** across 2 parallel calls (neutral + critic)
- Sub-questions: 8 (L1: 3 + L2: 2 + L3: 3)
- Sources: 40–60
- Output: **2000-3000 word report** + executive summary + PDF export (target relaxed in v0.2.2 based on real-session testing; prior 3000-4500 was unrealistic for single-session execution without heavy subagent delegation)
## Pipeline
```
┌────────────────────────────────────────┐
│ STAGE 0: Plan Approval (optional) │
│ — show user the expected L3 plan │
│ — wait for y/n or modifications │
└──────────────────┬─────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ STAGE 1: Execute /deep-research (L2) │
│ — produces L1/ + L2/ artifacts │
└──────────────────┬─────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ STAGE 2: L3 Expert Layer │
│ 1. MULTI-PERSPECTIVE PLAN │
│ 2. 3-ANGLE SEARCH │
│ 3. READ + SUMMARIZE │
│ 4. FACT-CHECK CRITICAL CLAIMS │
│ 5. CRITIC AGENT (adversarial review) │
│ 6. SECOND REFLECTION LOOP │
│ 7. DECISION MATRIX (if applicable) │
│ 8. EXPERT SYNTHESIS │
│ 9. PDF EXPORT │
└────────────────────────────────────────┘
```
## Artifacts Directory
```
.firecrawl/research/<slug>/
├── L1/ # from /research
├── L2/ # from /deep-research
└── L3/ # this skill
├── plan-approved.md # user-approved plan
├── perspective-plan.md # 3 angles
├── sources/
│ ├── 31-<slug>.md # continuing numbering
│ └── ...
├── fact-check.md # critical claims + verification
├── critic-report.md # adversarial review findings
├── decision-matrix.md # if query implies choice
├── report.md # final L3 report (supersedes L2/report.md)
├── executive-summary.md # 500-word TL;DR for stakeholders
├── bibliography.md
└── report.pdf # exported via pandoc
```
## Stage 0: Plan Approval
Before running L3 (which costs ~150 credits and 20 min), show the user a **plan preview**:
```markdown
# L3 Expert Research Plan
**Query:** <user's query>
**Estimated cost:** ~150 Tavily credits, ~20 min
**Will produce:** 3000+ word report, executive summary, fact-check report, PDF
## Approach
1. Run L2 baseline (planner + reflection + contradiction detection)
2. Add multi-perspective search: proponents, critics, neutral
3. Fact-check top 5 critical claims against 2+ independent sources
4. Run critic agent adversarial review
5. Build decision matrix (if query implies a choice)
## Initial sub-questions (will be refined after L1/L2)
- <preliminary subq1>
- <preliminary subq2>
- ...
**Proceed?** (y / n / modify)
```
If user says `y` — proceed. If `n` — abort gracefully. If `modify` — adjust and re-show.
**Skip approval** if:
- User explicitly invoked with `/expert-research --go` or said "сразу запускай"
- Called programmatically from L4 or L5
## Stage 1: Execute L2
Invoke the `deep-research` skill:
```
Skill: deep-research
Args: <query>
```
Wait for completion. Verify artifacts:
- `.firecrawl/research/<slug>/L2/report.md`
- `.firecrawl/research/<slug>/L2/contradictions.md`
- `.firecrawl/research/<slug>/L2/confidence.md`
## Stage 2: L3 Expert Layer
### Step 2.1: MULTI-PERSPECTIVE PLAN
Read L2 report. Generate 3 perspectives on the topic:
1. **Proponent angle** — what do advocates/vendors say?
2. **Critic angle** — what do detractors say? known problems?
3. **Neutral/academic angle** — what do benchmarks, studies, independent reviewers say?
Write `L3/perspective-plan.md`:
```markdown
# 3-Angle Research Plan
## Angle 1: Proponents
**Goal:** understand the strongest case for X
**Queries:**
- "why X is better than alternatives"
- "X official documentation advantages"
- "X success stories 2026"
## Angle 2: Critics
**Goal:** surface the strongest case against X
**Queries:**
- "problems with X in production"
- "why we moved away from X"
- "X limitations 2026"
## Angle 3: Neutral
**Goal:** independent data
**Queries:**
- "X vs Y benchmark 2026"
- "X real-world performance data"
- "X adoption metrics"
```
### Step 2.2: 3-ANGLE SEARCH
Run 9 searches in parallel (3 queries × 3 angles) using Firecrawl + Tavily.
**v0.5.0:** If Exa MCP is installed (check for `mcp__exa__*` tools availability), run additional Exa searches in parallel. Exa's neural ranking **excels at the critic and neutral angles** — it finds conceptually-related dissenting views that keyword search misses.
```
# Neutral angle via Exa with category filter
mcp__exa__web_search_advanced_exa with:
query: <original query, framed neutrally>
category: "research paper" # or omit for general news/web
type: "auto"
num_results: 10
contents: { text: { max_characters: 20000 } }
```
Save to `.firecrawl/research/$SLUG/L3/exa-neutral.json`. For **research paper category**, this is the single best source of independent academic content we have. Fall back to Tavily if Exa unavailable.
> **v0.2.2: persist Tavily results.** After each `mcp__tavily__tavily_search` call, write the response JSON to `.firecrawl/research/$SLUG/L3/tavily-<angle>-<n>.json` (angle = proponent/critic/neutral, n = query index) using the Write tool. MCP responses live in conversation context only; disk persistence makes them auditable and survivable across compaction.
Critical: use different search tactics per angle:
- Proponent angle: official docs, vendor blogs
- Critic angle: HN discussions, "we moved from X" blog posts, issue trackers
- Neutral angle: benchmark sites, independent reviewers, academic indexes
### Step 2.3: READ + SUMMARIZE
Pick top 10–15 NEW sources across 3 angles. Scrape + summarize using same `.sum.md` format as L1/L2.
**Add metadata to summaries:**
```markdown
**Angle:** [proponent | critic | neutral]
**Bias estimate:** [low | medium | high]
```
Save to `L3/sources/` starting from the next available number.
### Step 2.4: FACT-CHECK CRITICAL CLAIMS
**v0.6.0+: use Perplexity for fact-checks.** Perplexity is purpose-built for citation-grounded Q&A — cheaper and more focused than invoking Codex for verification of 5 short claims.
```
# For each of the top 5 critical claims:
mcp__perplexity-ask__perplexity_ask with:
messages: [{role: "user", content: "Verify this claim and find independent sources that support or dispute it: <claim>. Return: verdict (CONFIRMED/DISPUTED/UNVERIFIED), 2-3 supporting/disputing sources with URLs, one-sentence rationale."}]
```
Save each response to `.firecrawl/research/$SLUG/L3/perplexity-factcheck-<n>.json`. Combine Perplexity's verdicts with the manual fact-check process below:
- If Perplexity says CONFIRMED + our manual check confirms → High confidence
- If Perplexity says DISPUTED + our manual check flagged → include caveat in report
- Disagreements between Perplexity and manual → re-run with Codex as tiebreaker
If Perplexity unavailable, skill proceeds with manual fact-check only (existing pre-v0.6 behavior).
Read L2/report.md + L3 new summaries. Identify the **top 5 most critical claims** — ones that would change the recommendation if wrong.
For each, verify against 2+ **independent** sources (not from the same vendor/author):
Write `L3/fact-check.md`:
```markdown
# Fact-check report
## Claim 1: "X is 3x faster than Y"
**Source in report:** [7]
**Verification attempts:**
- ✓ Confirmed: [23] independent benchmark shows 2.8x
- ✓ Confirmed: [25] community benchmark shows 3.1x
- **Verdict:** CONFIRMED (High confidence)
## Claim 2: "X has poor ecosystem"
**Source in report:** [12] (critic blog)
**Verification attempts:**
- ✗ Contradicted: [28] shows 500+ packages
- ? Inconclusive: [30] mentions "some gaps" without specifics
- **Verdict:** DISPUTED — downgrade to "community opinion, not fact"
## Claim 3: ...
```
**Verdict categories:**
- **CONFIRMED** — 2+ independent sources agree
- **DISPUTED** — sources disagree, needs careful framing
- **UNVERIFIED** — couldn't find independent confirmation (downgrade in report)
### Step 2.4a: CODEX CROSS-MODEL CHANNEL (optional, added v0.2)
> Fault-tolerant — if Codex is unavailable, skill continues single-model.
Spawn **two parallel Codex calls** for independent second-model perspective: a neutral-angle research pass and a cross-model critic pass. These run in parallel with Step 2.5 (Claude critic agent).
```bash
CODEX_HELPER="$HOME/.claude/scripts/codex-research.sh"
[ -x "$CODEX_HELPER" ] || CODEX_HELPER="scripts/codex-research.sh"
# Call 1: Neutral-angle researcher (GPT-5.4 with its own index)
if [ -x "$CODEX_HELPER" ]; then
bash "$CODEX_HELPER" 360 \
".firecrawl/research/$SLUG/L3/codex-neutral.md" \
"You are an independent research assistant. Research the query '<ORIGINAL QUERY>' from a skeptical, neutral angle — ignore vendor marketing and hype. Look for benchmarks, independent reviewers, community experiences, and failures. Return 8-12 key findings with source URLs. Include dates. Be concise (≤1000 words)." &
CODEX_NEUTRAL_PID=$!
# Call 2: Cross-model critic (reads the L2 report and attacks conclusions)
L2_REPORT=$(cat ".firecrawl/research/$SLUG/L2/report.md" 2>/dev/null | head -300)
bash "$CODEX_HELPER" 360 \
".firecrawl/research/$SLUG/L3/codex-critic.md" \
"You are a skeptical research critic. Review this research report adversarially. Challenge main conclusions. Find what's missing, wrong, or oversimplified. Use your own web search to verify or refute key claims. Return a critic report (≤1000 words).
REPORT TO REVIEW:
$L2_REPORT" &
CODEX_CRITIC_PID=$!
else
CODEX_NEUTRAL_PID=""
CODEX_CRITIC_PID=""
fi
```
Proceed to Step 2.5 (Claude critic) while these run. After Step 2.5 finishes:
```bash
[ -n "$CODEX_NEUTRAL_PID" ] && wait "$CODEX_NEUTRAL_PID" 2>/dev/null
[ -n "$CODEX_CRITIC_PID" ] && wait "$CODEX_CRITIC_PID" 2>/dev/null
# Log status outcomes
for f in codex-neutral codex-critic; do
STATUS_FILE=".firecrawl/research/$SLUG/L3/${f}.md.status"
[ -f "$STATUS_FILE" ] && echo "$f: $(cat "$STATUS_FILE")"
done
```
When writing the final L3 synthesis (Step 2.8), **merge Codex findings with Claude findings**:
- If `L3/codex-critic.md` exists — include its objections in the report's "Weaknesses / counterpoints" section
- If `L3/codex-neutral.md` exists — cross-check its facts against Claude's conclusions, flag any disagreements in `contradictions.md`
- If Codex outputs absent (check `.status` files) — note in Confidence section: `Cross-model verification: unavailable (<reason>). Report is single-model.`
### Step 2.5: CRITIC AGENT (adversarial review)
**Invoke a critic sub-agent** to attack the L2 report. Use the Agent tool with a dedicated prompt:
```
Agent(subagent_type="general-purpose",
description="Critic review of L2 research",
prompt="""
You are a skeptical research critic. Your job is to find problems with this research report.
Read: .firecrawl/research/<slug>/L2/report.md
Also read: .firecrawl/research/<slug>/L2/confidence.md
For each major claim, ask:
1. Is the evidence strong enough?
2. Are there alternative explanations?
3. What would change my mind?
4. What's missing?
5. What's the weakest part of the argument?
Also check:
- Is the recommendation justified by the evidence?
- Are there hidden assumptions?
- Is there selection bias in the sources?
- Are there more recent sources that contradict the conclusion?
Write findings to: .firecrawl/research/<slug>/L3/critic-report.md
Format:
# Critic Report
## Weakest claims
- Claim X [citation]: problem with it
- ...
## Hidden assumptions
- ...
## Missing considerations
- ...
## Recommendation validity
- Justified? partial? unjustified?
## Questions the report doesn't answer but should
- ...
Be harsh but fair. Cite specific parts of the report you're attacking.
""")
```
Wait for critic to complete. Read `critic-report.md`.
### Step 2.6: SECOND REFLECTION LOOP
Based on critic findings, identify new gaps:
1. Claims flagged as weak → need more sources
2. Missing considerations → need targeted searches
3. Hidden assumptions → need to verify or acknowledge
Run 3–5 more targeted searches + scrapes to address critic concerns. Add to `L3/sources/`.
### Step 2.7: DECISION MATRIX (if applicable)
**Skip this step** if query is pure information (no choice implied).
**Apply this step** if query implies choosing between alternatives ("X vs Y", "should we migrate", "best tool for Z").
Write `L3/decision-matrix.md`:
```markdown
# Decision Matrix
## Criteria (weighted)
| Criterion | Weight | Why it matters for user context |
|---|---|---|
| Performance | 20% | ... |
| DX | 15% | ... |
| Maturity | 15% | ... |
| Cost | 10% | ... |
| Community | 15% | ... |
| Migration effort | 25% | ... |
## Options scored
| Option | Perf | DX | Maturity | Cost | Community | Migration | **Total** |
|---|---|---|---|---|---|---|---|
| A | 8 | 7 | 9 | 6 | 8 | 5 | **7.15** |
| B | 9 | 6 | 6 | 8 | 6 | 9 | **7.25** |
| C | 6 | 9 | 8 | 7 | 9 | 4 | **7.05** |
## Winner
**B** — by a small margin (7.25 vs 7.15)
## Why B edges out A
[Detailed reasoning with citations]
## When to pick A instead
[Scenarios where the decision flips]
## When to pick C instead
[Scenarios]
```
### Step 2.8: EXPERT SYNTHESIS
Produce `L3/report.md` — supersedes `L2/report.md`.
Structure:
```markdown
# <Topic Title>
**Query:** <original>
**Level:** L3 (includes L1, L2)
**Sources:** <total count>
**Generated:** <date>
## Executive Summary
[400-500 words: the complete answer for someone who will read only this section]
## Context
[Why this question matters, what's at stake, user's context if known]
## Findings by Sub-question
[All L1/L2 subqs + L2 followups, enriched]
## Multi-perspective analysis
### Proponent view
[Strongest case for, with citations and confidence]
### Critic view
[Strongest case against, with citations]
### Neutral/independent data
[Benchmarks, studies, adoption data]
### Synthesis
[How to reconcile the three perspectives]
## Fact-check results
[From fact-check.md: confirmed / disputed / unverified claims]
## Addressing critic concerns
[From critic-report.md: weaknesses identified and how resolved or acknowledged]
## Decision Matrix
[If applicable — full matrix from decision-matrix.md]
## Recommendation
[Concrete, opinionated, with explicit reasoning chain]
## Risks and caveats
[What could go wrong with the recommendation]
## Next steps
[Actionable — what the user should do next]
## Bibliography
[See L3/bibliography.md for full list]
```
**Target length:** **2000–3000 words** (v0.2.2 relaxed from 3000-4500 based on real-session testing — old target was unachievable without aggressive subagent delegation and caused truncation artifacts).
### Step 2.9: Executive Summary
Write separate `L3/executive-summary.md` — 500 words max. For stakeholders who won't read the full report. Plain language, no jargon.
### 🛑 L3 FINAL CHECKPOINT (added v0.2.2, shared-lib'd v0.4.0)
Before delivering the report, run this verification. Mirrors the L2 CHECKPOINT discipline — L3 was previously only prose-level verified, which was a regression from L2.
```bash
SLUG="<slug>"
VERIFY_LIB="$HOME/.claude/scripts/lib/verify-research.sh"
[ -f "$VERIFY_LIB" ] || VERIFY_LIB="scripts/lib/verify-research.sh"
[ -f "$VERIFY_LIB" ] || { echo "❌ verify-research.sh not found — run scripts/install.sh"; exit 1; }
source "$VERIFY_LIB"
verify_l3 "$SLUG" || exit 1
```
The function checks: report ≥1700 words (target 2000-3000); executive summary, critic report (subagent output), fact-check, bibliography, perspective plan all present; ≥8 L3 source summaries; every `[N]` citation (including multi-cite formats) maps to a bibliography entry.
**Only proceed to PDF export (Step 2.10) after this prints `✅ L3 FINAL CHECKPOINT PASSED`.**
### Step 2.10: PDF Export
```bash
cd .firecrawl/research/<slug>/L3/
pandoc report.md -o report.pdf --pdf-engine=xelatex -V geometry:margin=1in 2>/dev/null || \
pandoc report.md -o report.html && \
echo "PDF export requires pandoc+xelatex. HTML fallback at report.html"
```
If pandoc isn't installed, fall back to HTML export.
## Final Output
1. Display `L3/executive-summary.md` in chat (short version)
2. Offer to show full `report.md` if user wants
3. Show stats:
> 📊 L3 stats: <total> sources, <n> perspectives, <n> fact-checked claims, critic report: <n> concerns addressed
4. Artifact locations:
> 📁 `.firecrawl/research/<slug>/L3/`
> 📄 report.md, executive-summary.md, report.pdf, fact-check.md, critic-report.md, decision-matrix.md
5. Escalation:
> Нужны научные источники? `/academic-research` (L4) добавит arXiv, Scholar и полный мультиагент.
> Нужна полная база знаний? `/ultra-research` (L5) построит vault с playbook'ами.
## Rules
- **Plan approval is the norm** — skip only if user explicitly said "сразу запускай" or called from L4/L5
- **Always call L2 first** — never inline L2 logic
- **Multi-perspective is mandatory** — don't rely on one angle
- **Critic is a separate agent** — use Agent tool, not internal reasoning
- **Fact-check top 5 only** — don't try to verify every claim
- **Decision matrix only when applicable** — don't force it on info queries
- **Executive summary is separate** — ~500 words, standalone, no jargon
- **Preserve L1/L2 artifacts** — never modify or delete
## Called from higher levels
L4/L5 call this skill to get expert-grade foundation. When called:
- Run full L3 pipeline (including plan approval if user is present)
- Higher levels read `L3/report.md`, `L3/critic-report.md`, `L3/decision-matrix.md`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |