deep-research

name

deep-research

description

Conduct enterprise-grade research with multi-source synthesis, citation tracking, and verification via an 8-phase pipeline (Scope, Plan, Retrieve, Triangulate, Synthesize, Critique, Refine, Package). Use when you need comprehensive analysis requiring 10+ sources, verified claims, or comparison of approaches. Triggers include "deep research", "comprehensive analysis", "research report", "compare X vs Y", or "analyze trends". Do NOT use for simple lookups, debugging, or questions answerable with 1-2 searches.

Deep Research

Core System Instructions

Purpose: Deliver citation-backed, verified research reports through an 8-phase pipeline (Scope → Plan → Retrieve → Triangulate → Synthesize → Critique → Refine → Package) with source-credibility scoring and progressive context management.

Philosophy: DEEP Research, Not Surface Summaries

This is a DEEP research skill — not a quick summary tool. Every technical concept must be explained thoroughly enough that an unfamiliar reader can understand it.

Bad (surface-level): "The model uses DSA for efficiency."

Good (deep research):

"The model introduces DeepSeek Sparse Attention (DSA), a novel attention mechanism that reduces computational complexity. Traditional attention computes relationships between every pair of tokens, scaling quadratically O(n²) with sequence length. DSA instead uses a two-stage approach: first, a lightweight 'lightning indexer' scores all tokens quickly using FP8 matrix multiplies; second, only the top-k most relevant tokens (typically 2,048) are selected for full attention computation. This reduces complexity to O(Lk) where k << L. The technique was introduced in DeepSeek-V3.2 (December 2025) and draws on prior work in sparse attention from Longformer [1] and BigBird [2], but achieves content-adaptive sparsity rather than fixed patterns."

Tooling (pi-native — IMPORTANT)

pi has no built-in WebSearch or WebFetch. All web access goes through these stdlib Python helpers in this skill's scripts/ dir (invoke via bash):

Need	Command
Web search	python3 ~/.pi/agent/skills/deep-research/scripts/web_search.py "<query>" [N] [--site domain]
arXiv search (PREFERRED for papers)	python3 ~/.pi/agent/skills/deep-research/scripts/arxiv_search.py "<query>" [N]
Fetch a URL → local text file	python3 ~/.pi/agent/skills/deep-research/scripts/web_fetch.py "<url>" [outfile.txt]
Save facts to disk (context hygiene)	python3 ~/.pi/agent/skills/deep-research/scripts/research_state.py save --key K --content "..." --sources N --tags a,b
Record a citation as discovered	python3 ~/.pi/agent/skills/deep-research/scripts/citation_store.py add --url U --title "..." --tier 1
Validate a report	python3 ~/.pi/agent/skills/deep-research/scripts/validate_report.py --report path.md

Pattern for every fetch: web_fetch.py <url> <outfile> → read <outfile> → extract key facts → save to research_state.py → add the source to citation_store.py → move on. Do NOT keep raw fetched content in conversation context; extract facts and save them to disk.

Public search endpoints sometimes serve CAPTCHA/anomaly pages to bots. When web_search.py returns no results, fall back to arxiv_search.py (papers) and web_fetch.py on known/candidate URLs (HuggingFace, GitHub, company blogs).

---

Decision Tree (Execute First)

Request Analysis
├─ Simple lookup? → STOP: use web_search.py, not this skill
├─ Debugging? → STOP: use standard tools, not this skill
└─ Complex analysis needed? → CONTINUE

Mode Selection
├─ Initial exploration? → quick (3 phases, 2-5 min)
├─ Standard research?   → standard (6 phases, 5-10 min) [DEFAULT]
├─ Critical decision?  → deep (8 phases, 10-20 min)
└─ Comprehensive review? → ultradeep (8+ phases, 20-45 min)

Validation Gate
├─ python scripts/validate_report.py --report [path]
├─ Pass? → Deliver
└─ Fail? → Fix (max 2 attempts) → Still fails? → Escalate

---

Source Tier Hierarchy (CRITICAL)

Tier 1: Primary Sources (HIGHEST PRIORITY)

• ArXiv technical reports by the authors (GOLD STANDARD — use the /html/ endpoint via web_fetch.py)
• Official technical reports/papers (even if not on arXiv)
• Official model cards on HuggingFace (huggingface.co/{org}/{model})
• config.json and other model configuration files
• Official GitHub repositories from the model authors
• Official documentation (API docs, release notes)
• Framework-specific docs (vLLM, SGLang, Transformers)

Tier 2: Verified Secondary Sources

• Official blog posts from the releasing organization
• Framework integration announcements (vLLM blog, SGLang docs)
• Benchmark submissions with verifiable methodology

Tier 3: Third-Party Analysis

• Independent benchmark sites (Artificial Analysis, LMSYS)
• Technical analysis articles from reputable sources
• Academic papers citing the model

Tier 4: General Coverage (USE SPARINGLY)

• News articles, social media, community discussions

Verification Rule: Claims from Tier 3-4 sources MUST be verified against Tier 1-2 sources before inclusion in the report.

---

ArXiv Paper Reading (CRITICAL)

ALWAYS use the /html/ endpoint for arXiv papers, NOT /abs/ or /pdf/.

# GOOD — full HTML, structured, parseable
python3 ~/.pi/agent/skills/deep-research/scripts/web_fetch.py "https://arxiv.org/html/2412.19437" paper.txt
# then: read paper.txt  and extract sections

# BAD — abstract only:  https://arxiv.org/abs/2412.19437
# BAD — PDF, hard to parse: https://arxiv.org/pdf/2412.19437.pdf

Use arxiv_search.py to confirm an ID exists and to discover papers by query:

python3 ~/.pi/agent/skills/deep-research/scripts/arxiv_search.py "DeepSeek-V3 technical report" 5
python3 ~/.pi/agent/skills/deep-research/scripts/arxiv_search.py --id 2412.19437

---

Acronym & Concept Explanation Standards

EVERY technical acronym or concept must be explained on first mention.

Template: **{Full Name} ({ACRONYM})** — {one-sentence explanation}. {Origin/citation if known}

First Mention	Expanded Form
MoE	Mixture-of-Experts (MoE) — an architecture where input tokens are routed to a subset of "expert" sub-networks rather than the full model. Popularized by Shazeer et al. (2017) [1].
MLA	Multi-head Latent Attention (MLA) — a KV-cache compression technique that projects keys/values into a low-rank latent space. Introduced in DeepSeek-V2 (2024) [2].
DSA	DeepSeek Sparse Attention (DSA) — a two-stage sparse attention mechanism using a "lightning indexer" to select top-k relevant tokens, reducing O(L²) to O(Lk). Introduced in DeepSeek-V3.2 (2025) [3].
RoPE	Rotary Position Embedding (RoPE) — a position encoding that applies rotation matrices to encode relative positions directly in attention. Su et al. (2021) [4].
YaRN	Yet another RoPE extensioN (YaRN) — modifies RoPE frequencies to support longer sequences. Peng et al. (2023) [5].
FP8	8-bit Floating Point (FP8) — a reduced-precision format (e4m3/e5m2) enabling faster computation and lower memory with minimal accuracy loss.
GQA	Grouped Query Attention (GQA) — multiple query heads share a single key-value head. Ainslie et al. (2023) [6].

Rule: If you use an acronym, you MUST have explained it earlier OR explain it on first use. No exceptions.

---

Deep Novelty Explanation Template

For each genuinely NOVEL feature:

### [Feature Name] — GENUINELY NOVEL

**The Problem It Solves:** [1-2 paragraphs: what limitation does this address? why did prior approaches fall short?]
**How It Works (Technical Mechanism):** [2-3 paragraphs: step-by-step, with specific numbers/parameters/complexity]
**Prior Art & Differentiation:** [1-2 paragraphs: what it builds on and how it differs]
- Prior approach 1: [Name] — [limitation]
- This approach: [how it improves]
**Tradeoffs & Limitations:** [1 paragraph: costs / when NOT to use it]
**Verification Status:**
- [ ] Verified in config.json
- [ ] Verified in technical report
- [ ] Verified by independent benchmarks

---

Workflow (Clarify → Plan → Act → Verify → Report)

AUTONOMY PRINCIPLE: Operate independently. Infer assumptions from the query. Only stop for critical errors or incomprehensible queries. When in doubt, PROCEED with standard mode.

2. Plan

Mode selection: quick (2-5 min), standard (5-10 min, default), deep (10-20 min), ultradeep (20-45 min). Briefly announce mode + est. sources, then proceed without waiting for approval.

3. Act (Phase Execution)

All modes: Phase 1 SCOPE, Phase 3 RETRIEVE, Phase 8 PACKAGE. Standard+: Phase 2 PLAN, Phase 4 TRIANGULATE, Phase 4.5 OUTLINE REFINEMENT, Phase 5 SYNTHESIZE. Deep/UltraDeep: Phase 6 CRITIQUE, Phase 7 REFINE. See methodology for full 8-phase detail.

Progressive context loading: load methodology and template sections on-demand only.

Anti-Hallucination Protocol (CRITICAL):

• Source grounding: every factual claim MUST cite a specific source immediately [N]
• Clear boundaries: distinguish FACTS (from sources) from SYNTHESIS (your analysis)
• Explicit markers: use "According to [1]…" or "[1] reports…" for source-grounded statements
• No speculation without labeling: mark inferences as "This suggests…" not "Research shows…"
• When uncertain: say "No sources found for X" rather than inventing a citation

Parallel Execution (Phase 3 RETRIEVE):

1. Decompose the query into 5-10 independent search angles.
2. Launch ALL searches in one batch (multiple bash calls in one turn):

   python3 ~/.pi/agent/skills/deep-research/scripts/web_search.py "<angle 1>" 8 &
   python3 ~/.pi/agent/skills/deep-research/scripts/web_search.py "<angle 2>" 8 &
   python3 ~/.pi/agent/skills/deep-research/scripts/arxiv_search.py "<paper query>" 5 &
   wait
   

3. For independent deep-dives, spawn 3-5 parallel subagents with the subagent tool (read the pi-subagents skill for usage). Example fanout: one subagent per source cluster (academic papers, framework docs, benchmarks, repos). Each returns extracted facts you save to research_state.py.

❌ WRONG: search #1 → wait → search #2 → wait → … ✅ RIGHT: all searches + subagents launched in one turn.

Context hygiene (CRITICAL — prevents context bloat):

python3 ~/.pi/agent/skills/deep-research/scripts/research_state.py init --session "<slug>" --question "<question>"
python3 ~/.pi/agent/skills/deep-research/scripts/citation_store.py init --session "<slug>"
# after each useful fetch:
python3 ~/.pi/agent/skills/deep-research/scripts/citation_store.py add --session "<slug>" --url "..." --title "..." --tier 1
python3 ~/.pi/agent/skills/deep-research/scripts/research_state.py save --session "<slug>" --key "architecture" --content "key facts…" --sources 1 --tags arch

Pattern: web_fetch returns 5000 words → extract 10 key facts → save to research_state.py → context freed. Do NOT keep raw fetched content in conversation. Target <25K tokens of context.

4. Verify (Always Execute)

# Step 1: citation verification (catches fabricated sources)
python3 ~/.pi/agent/skills/deep-research/scripts/verify_citations.py --report [path]
# Step 2: structure & quality validation (8 checks)
python3 ~/.pi/agent/skills/deep-research/scripts/validate_report.py --report [path]

validate_report.py checks: executive summary length, required sections, citation format, bibliography matches citations, no placeholder text, word count, minimum 10 sources, no broken internal links. If it fails: auto-fix attempt 1 → manual review attempt 2 → after 2 failures STOP and report.

5. Report

Generate a COMPREHENSIVE markdown report following template.

File organization: create a dedicated folder for the topic, e.g. ./{topic}_research_{YYYYMMDD}/ (or, for HF model research, the orchestrator overrides this to ./{org}/{model}/). Save the markdown there.

Length: quick 2,000+ words; standard 4,000+; deep 6,000+; ultradeep 10,000+ (no hard upper limit). Achieve unlimited length via progressive file assembly — write each section to file immediately with write/edit (one section per call), rather than buffering the whole report in one output.

For very long reports (>~18K words): write the first batch of sections to file, save a continuation state, then spawn a continuation subagent (via the subagent tool) that reads the state + last sections and appends the next batch. Chain until complete. This keeps each generation manageable.

Writing standards: narrative-driven prose; precision (exact numbers in sentences, not isolated bullets); economy (no fluff); high signal-to-noise. Use bullets sparingly (only for distinct lists). Each major section ≥3 prose paragraphs.

Source attribution (prevents fabrication):

• Immediate citation: every factual claim followed by [N] in the same sentence
• Quote sources directly: "According to [1]…" / "[1] reports…"
• ✅ "Mortality decreased 23% (p<0.01) [1]." ❌ "Studies show mortality improved."
• Label speculation: "This suggests…" (analysis) not "The mechanism is…" (fact)
• Admit uncertainty: "No sources found for X" — never fabricate a citation

Deliver: (1) executive summary inline, (2) folder path, (3) source-count summary, (4) next steps if relevant.

---

Output Contract

Format: comprehensive markdown following template.

Required sections: Executive Summary (50-250 words), Glossary of Terms (required — every acronym/concept, min 10 for technical reports), Introduction, Main Analysis (4-8 findings, each 300-500 words with [N] citations), What's Novel (for releases — use the Deep Novelty Template), Synthesis & Insights (500-1000 words), Limitations & Caveats, Recommendations, Bibliography (required), Methodology Appendix.

Bibliography (ZERO TOLERANCE — report is unusable without it):

• MUST include EVERY [N] cited in the body (if [1]-[50], write all 50 entries)
• Format: [N] Author/Org (Year). "Title". Publication. URL (Retrieved: Date)
• ❌ NO placeholders: never "[8-75] Additional citations", "…continue…", "etc."
• ❌ NO ranges: write [3], [4], [5] individually, not "[3-50]"
• ⚠️ Validation FAILS if the bibliography has placeholders or missing citations

Strictly prohibited: placeholder text (TBD/TODO), uncited major claims, broken links, missing sections, short summaries instead of analysis, vague statements without evidence.

Quality gates: min 2,000 words (standard); avg credibility >60/100; 3+ sources per major claim; clear fact-vs-analysis distinction.

---

Error Handling & Stop Rules

Stop immediately if: 2 validation failures on the same error; <5 sources after exhaustive search (report limitation, request direction); user changes scope.

Graceful degradation: 5-10 sources → note in limitations, proceed with extra verification; time constraint → package partial results, document gaps.

---

Scripts (offline, Python stdlib only)

Location: ./scripts/ (this skill dir).

• research_engine.py — orchestration engine
• validate_report.py — quality validation (8 checks)
• verify_citations.py — citation verification (DOI/title matching)
• citation_manager.py — citation tracking
• source_evaluator.py — credibility scoring (0-100)
• md_to_html.py — markdown → McKinsey-style HTML
• verify_html.py — HTML verification
• web_search.py — Bing/DDG web search (no API key) (pi-native)
• arxiv_search.py — arXiv API search (no API key) (pi-native)
• web_fetch.py — fetch URL → text file (HTML→text) (pi-native)
• html_to_text.py — stdlib HTML→text (pi-native)
• research_state.py — context-hygiene fact store (pi-native)
• citation_store.py — context-hygiene citation store (pi-native)

No external dependencies required for any script.

Progressive References (Load On-Demand)

• Complete Methodology — 8-phase details
• Report Template — output structure
• McKinsey HTML Template — for HTML export