Skill: zhihua-yang/deep-researcher-pro (version 1.0.1)

--- name: deep-researcher version: 1.0.1 description: Domain Research Report Generator — runs multi-angle deep research on any topic and produces a structured, decision-ready report with evidence-scored consensus, divergences, key numbers, failed paths, and decision readiness. 深度调研报告生成器，自动研究任意领域并输出结构化决策报告，包含共识、分歧、关键数字、失败路径和决策准备度分析。 author: zhihua-yang allowed-tools: - WebSearch - Read - Write - AskUserQuestion --- # SKILL: Deep Researcher v1 — Domain Research Report Generator # Trigger: Triggered automatically when user expresses research intent in natural language. # Also invokable explicitly with /deep-researcher [anything in natural language] # No flags or options — everything is inferred from the query semantically. # Token budget: ~900 *** ## STARTUP CHECK Before doing anything else, verify that a web search capability is available. **Step 1 — Probe for a working search tool** Attempt a minimal test search (e.g. "deep researcher test") using whatever search tool is available in the current environment: - Built-in platform search: `WebSearch` - MCP search tools: `serper__search`, `tavily__search`, `brave_search`, `exa__search`, `web_search`, `search`, or any tool whose name contains "search" If the search succeeds (returns any result, even empty): proceed normally. **Step 2 — If no working search tool is found** Do NOT attempt to run the research. Instead, notify the user: --- ⚠️ **Deep Researcher needs a web search tool to function, but none was found in this environment.** To fix this, configure one of the following search providers (pick any one): | Option | Setup | Free tier | Best for | |--------|-------|-----------|---------| | **Serper** ⭐ (recommended) | Get key at serper.dev → `SERPER_API_KEY=xxx` | 2,500 searches/month | General research — real Google results | | **Tavily** (research-optimized) | Get key at tavily.com → `TAVILY_API_KEY=xxx` | 1,000 searches/month | Deep research | | **Brave Search** | Get key at brave.com/search/api → `BRAVE_API_KEY=xxx` | 2,000 queries/month | Privacy-first | | **Gemini** (Google AI) | Get key at aistudio.google.com → `GEMINI_API_KEY=xxx` | 500 req/day, no card needed | No credit card | | **Kimi / Moonshot** | platform.moonshot.cn → `KIMI_API_KEY=xxx` | Paid, Alipay accepted | Alternative provider | Set the API key as an environment variable and restart your agent, then try again. --- **Step 3 — WebFetch-only fallback** If no search tool is available but the user has explicitly provided source files (e.g. "based on this document..."), proceed in file-only mode — skip the startup check and go directly to SEMANTIC INTENT ANALYSIS. *** ## ROLE Domain research analyst — deep research mode. Turn messy information into a structured research report with enforced source traceability. Do not produce a general summary. Produce a **decision-ready research report** — independently usable, no downstream routing required. *** ## HARD RULES - Every FACT must be falsifiable - Every claim must be decision-relevant - FAILED_PATHS must include why it failed - Every key section must distinguish evidence strength (see references/evidence-scoring.md) - If evidence is weak, say weak; do not smooth uncertainty - Unfillable sections → mark [UNKNOWN] and state what would resolve it - Output must be a ready-to-save .md file, nothing else - **Output language**: detect from the user's query language. - Query primarily in English (multiple English words) → English output - Query primarily in Chinese → Chinese output - Query in other languages → that language - Ambiguous (single technical term like "React" or "AWS" with no surrounding words) → default to Chinese Output language is independent of research language — all output sections are written in the output language regardless of what languages were used during research. - **Research language**: MUST use the official local language(s) of the domain's region for at least 2 of the 5 search angles. This is a hard rule, not a preference. See STEP 1 for region detection and STEP 2 for language enforcement. - **Source enforcement**: every key claim must be accompanied by a source URL or citation - **Anti-hallucination**: it is forbidden to present speculation as fact without source support - **Full-text before inference**: when search snippets are available but full text has not been fetched, do not infer complete content from snippets alone — fetch the full text first - **Numeric source tagging**: any specific number cited must have its source explicitly noted; forecasts/predictions must be marked [ESTIMATED]; vendor self-reported numbers must be marked [ESTIMATED] and start at LOW evidence level *** ## EXECUTION GOAL Your task is not: - to sound comprehensive - to collect as much as possible - to write a market overview Your task is: - to identify what is known - what is contested - what has already failed - what constraints cannot be negotiated - what unknown, if resolved, most changes the decision - to ensure every finding is traceable to its source *** ## SEMANTIC INTENT ANALYSIS Before doing anything, read the entire query and infer everything from meaning. Answer: **Q1 — How many distinct research subjects?** Count independently researchable entities the user wants information about. - "Southeast Asia e-commerce logistics" → 1 subject - "AWS and Alibaba Cloud" → 2 subjects - "Research AWS, Alibaba Cloud and Huawei Cloud" → 3 subjects - "Pros and cons of React" → 1 subject (pros/cons are aspects, not separate subjects) **Q2 — What is the primary intent?** - **research**: understand a domain or subject in depth ("research", "analyze", "what is the state of", "deep dive") - **compare**: evaluate options to make a choice ("which is better", "difference between", "how to choose", "vs") - **update**: refresh prior research with new information ("latest on", "what changed", "update my notes on") "Difference between A and B" is **compare**. "Research A and B" is **research** (parallel, not head-to-head). **Q3 — What region and language?** Detect the domain's region from the topic itself — no explicit instruction needed. Apply language rules from strategies/search-protocol.md. **Q4 — Are there existing files to work from?** If the user references files, documents, or notes (e.g. "based on this doc", "using my notes"), treat them as source material and skip web research. **Q5 — Where should the output go?** - If user mentions a path or filename, save there. - If user says "update" an existing report, read it first and add to it. - Otherwise, default to context/[domain].md. **Record all inferred decisions in RESEARCH_LOG**: `[HH:MM:SS] Intent analysis — subjects: N, intent: [research/compare/update], mode: [brief/compare/brief-multi/compare-multi], region: [X], output-lang: [L], source-files: [none/listed], output-path: [path] — Rationale: [one sentence]` *** ## MODE ROUTING | Subjects | Intent | Mode | |----------|--------|------| | 1 | research | **brief** — standard research report | | 1 | compare | **brief** — 1 subject; frame internal tension in CORE_TENSION | | 2 | research | **brief-multi** — shared report, each subject gets its own sub-sections | | 2 | compare | **compare** — head-to-head using comparison.md template | | 3+ | research | **brief-multi** — shared report, each subject gets its own sub-sections | | 3+ | compare | **compare-multi** — multi-column comparison matrix | | any | update | **update** — read existing file, add new findings | ### Mode: brief Standard research report. Uses template: templates/decision-brief.md Flow: SCOPE → COLLECT → SCORE → EXTRACT → OUTPUT ### Mode: compare (2 subjects, compare intent) Head-to-head analysis. Uses template: templates/comparison.md Collect evidence for each subject independently, then compare. Flow: SCOPE → COLLECT (A) → COLLECT (B) → SCORE → COMPARE → OUTPUT ### Mode: brief-multi (2+ subjects, research intent) Parallel research. Uses templates/decision-brief.md as base structure. Shared SCOPE and CONSTRAINTS. Each subject gets its own sub-sections within CONSENSUS, DIVERGENCES, KEY NUMBERS. Collect evidence for each subject independently. ### Mode: compare-multi (3+ subjects, compare intent) Multi-way comparison. Extend comparison.md with N columns in the matrix. Collect evidence for each subject independently, then compare across all. ### Mode: update (any, update intent) Read the referenced existing report first. Preserve sections that do not need updating. Add new findings; mark updated content with [Updated: date]. Do not remove historical context. Update DECISION_READINESS based on new information. **Path resolution for update mode**: - If user specifies an explicit path, use it. - If user references a domain name (e.g. "update my research on Vietnam e-commerce"), search context/ for a filename that matches (fuzzy match against domain name). If one match found, use it. If multiple matches found, list them and ask the user to confirm. If no file found, ask: "No existing report found for [domain]. Start a fresh research report instead?" ### Mode: file-only (user provided source files, no web research requested) When the user references existing files as source material: Treat those files as the ONLY source — do NOT run web searches. Cross-verify claims across files; flag contradictions. Annotate each claim with [source: filename]. Mark sections with insufficient evidence as [WEAK: recommend: ___]. In all multi-subject modes: apply per-subject region detection and language assignment independently. See search-protocol.md for per-subject language rules. *** ## EXECUTION STEPS ### STEP 1 — DEFINE SCOPE → Clarify what is inside this domain and what is outside → **Detect the domain region** (always inferred from topic — never requires explicit instruction): - If the topic inherently involves a specific country/region (e.g. "Japan SaaS market", "German logistics"), treat that as the region - If truly global with no regional focus, region = "global" and no local-language requirement applies → **Record the detected region** in the file header as `Region Focus` → **Determine research languages** based on detected region (see STEP 2 language enforcement) → For compare modes: define comparison dimensions and scope boundary ### STEP 2 — COLLECT EVIDENCE Follow strategies/search-protocol.md for search protocol. All modes use deep research protocol: 3-5 searches from different angles, top 3-5 full text fetches, cross-verify all claims, seek contradictory evidence. Priority order for source types: 1. authoritative reports / primary materials 2. practitioner sources 3. credible public internet 4. user/community signals **Search angles** (always use all 5): - Angle 1: Direct/factual — "What is [domain]? overview/status" - Angle 2: Critical/contrarian — "[domain] problems/challenges/risks" - Angle 3: Practitioner/insider — "[domain] experience/case study/best practice" - Angle 4: Forward-looking — "[domain] trends/future/predictions" - Angle 5: Cross-domain — "[domain] vs [related domain] comparison/alternative" **Language enforcement** (hard rule — applies to all modes): - When a region is detected in STEP 1 (not "global"), angles 1 and 2 MUST use the official local language. - Full language assignment rules, fallback inference (Steps A–D), multi-language/supranational regions, and multi-country region allocation are defined in **strategies/search-protocol.md → Search Language and Region**. - Do NOT default to English for a non-English region without following the fallback rules. - Record the actual search language for each angle in RESEARCH_LOG. **Cross-verification**: - Any claim used in CONSENSUS or DIVERGENCES must be verified from at least 2 independent sources - If only 1 source found, mark evidence as LOW and note "single source" - Seek contradictory evidence actively — do not stop at confirming sources - In compare modes: collect evidence for each subject independently using the same deep protocol **Scarce information handling**: - If all 5 search angles return fewer than 3 valid sources total, the domain is "information-scarce" - Mark the file's information confidence as LOW - In SCOPE, note: "Information-scarce domain — insufficient search results for high-confidence judgment" - Prioritize what few sources exist for CONSENSUS, move most claims to DIVERGENCES or [UNKNOWN] - In DECISION_READINESS, set confidence index ≤ 3 ### STEP 3 — SCORE EVIDENCE See references/evidence-scoring.md for detailed criteria. For each key claim, assign: - HIGH = repeated across strong or primary sources (2+ independent authoritative sources) - MEDIUM = plausible, partially supported, limited contradiction - LOW = anecdotal, emerging, weakly verified, or single source only ### STEP 4 — EXTRACT CONSENSUS Max 5 items. Only include facts that can affect a decision. Each item must have at least one source reference. ### STEP 5 — EXTRACT DIVERGENCES Max 5 items. For each divergence, preserve both sides with direct reasoning. Do not resolve disagreement unless evidence decisively closes it. Each side must reference its source. **Even when evidence appears one-sided, the minority position must be presented in DIVERGENCES.** Do not "balance" by upgrading weak minority evidence, but also do not suppress it. Asymmetric evidence quality is a valid finding — present it honestly. ### STEP 5.5 — OPTIONAL SECTIONS (include when relevant) These three sections are **not always required** — include them when the evidence and topic warrant it. Record in RESEARCH_LOG which optional sections were included and why. **A. LANDSCAPE** — Include when the domain involves a market, technology ecosystem, or competitive field. Synthesize the competitive/ecosystem structure from evidence already collected: - Key players: who are the main actors, what is their positioning - Market structure: fragmented / consolidated / duopoly / emerging - Notable recent moves: acquisitions, launches, exits, regulatory actions (with dates and sources) - Do NOT list players without evidence — if a player is mentioned but not researched, omit or mark [UNVERIFIED] **B. IMPLICATIONS** — Include when the domain has clear stakeholder impact (policy, market shift, technology change). For each relevant stakeholder group, state the direct consequence and one second-order effect: - Keep to 2-4 stakeholder groups maximum - Each implication must be traceable to a CONSENSUS or DIVERGENCES item - Avoid generic statements ("this will change everything") — be specific **C. SCENARIOS** — Include when the domain has high uncertainty or multiple plausible futures. Define 2-3 scenarios based on the key variable identified in CORE_TENSION: - Base case: most likely path given current trajectory - Upside / opportunity scenario: what would need to be true - Downside / risk scenario: what would need to be true - The key variable that drives divergence between scenarios (should map to an OPEN_QUESTION) ### STEP 6 — EXTRACT FAILED_PATHS What has already been tried and failed? Why did it fail? Under what conditions would it fail again? Cite sources for failure evidence. ### STEP 7 — IDENTIFY CORE_TENSION Compress the entire domain into one irreducible contradiction. One sentence only. One main-subject-predicate structure. Keep it tight — expansion belongs in other sections. Good: "Overseas warehouses deliver next-day but require heavy capital; direct cross-border shipping is cheap but too slow for live-commerce conversion." Bad: a multi-clause paragraph that explains the tension from three angles. (Over-expanded) ### STEP 8 — IDENTIFY CONSTRAINTS Separate: - hard constraints (physical, legal, irreversible) - soft constraints (economic, social, potentially changeable) - self-imposed constraints (assumptions, preferences, organizational) Do not mix them. ### STEP 9 — OPEN QUESTIONS List 2-3 questions whose answers would most change what to do next. ### STEP 10 — DECISION READINESS State: - biggest evidence gap - what can still be decided despite uncertainty - what must not be decided yet - **next concrete action** (1-2 specific steps the reader can take immediately) - decision confidence index (0-10) - time sensitivity (high / medium / low) - reversibility (reversible / partially reversible / irreversible) ### STEP 11 — COMPILE SOURCES Aggregate all sources referenced throughout the document. Each source entry: URL or citation | source type | access time | access status Source types: Authoritative Report | Practitioner | Public Web | Community Access status: ✅ Full text fetched | ⚠️ Snippet only (fetch failed) | ❌ Unreachable (403/404/paywall) This allows readers to assess which claims are based on full-text verification vs. snippets only. ### STEP 12 — COMPILE RESEARCH LOG Track the research process for reproducibility: - [HH:MM:SS] Intent analysis — all inferred decisions (see SEMANTIC INTENT ANALYSIS) - [HH:MM:SS] Optional sections included: [LANDSCAPE / IMPLICATIONS / SCENARIOS / none] — [rationale] - [HH:MM:SS] Search: "keyword" → N results - [HH:MM:SS] Full text fetch: URL → key finding / FAILED (reason) - [HH:MM:SS] Cross-verify: fact X → confirmed / disputed Use second-precision timestamps for reproducibility. *** ## TEMPLATE REFERENCE - brief / brief-multi: templates/decision-brief.md - compare / compare-multi: templates/comparison.md Load the appropriate template at output time. The template defines the output structure; all analysis logic, hard rules, and scoring criteria remain in this SKILL.md. **Section title localization (hard rule)**: The template uses English section titles as canonical identifiers. When generating the final output, translate ALL section titles, field labels, and structural keywords into the output language. Do NOT leave English titles in a non-English report. Use the following translation table. For languages not listed, translate naturally: | English (canonical) | 中文 | 日本語 | Español | Français | Deutsch | |---------------------|------|--------|---------|----------|---------| | Research Report | 研究报告 | 調査レポート | Informe de Investigación | Rapport de Recherche | Forschungsbericht | | Comparative Analysis | 对比分析 | 比較分析 | Análisis Comparativo | Analyse Comparative | Vergleichsanalyse | | SCOPE | 研究范围 | 調査範囲 | ALCANCE | PORTÉE | UMFANG | | Domain boundary | 领域边界 | 領域の境界 | Límite del dominio | Limite du domaine | Domänengrenze | | Out of scope | 不在范围内 | 対象外 | Fuera del alcance | Hors périmètre | Außerhalb des Rahmens | | CONSENSUS | 共识 | コンセンサス | CONSENSO | CONSENSUS | KONSENS | | DIVERGENCES | 分歧 | 見解の相違 | DIVERGENCIAS | DIVERGENCES | DIVERGENZEN | | Divergence N | 分歧 N | 見解の相違 N | Divergencia N | Divergence N | Divergenz N | | Supporting | 支持方 | 支持側 | A favor | Pour | Dafür | | Opposing | 反对方 | 反対側 | En contra | Contre | Dagegen | | Evidence strength | 证据强度 | 証拠の強度 | Solidez de la evidencia | Force des preuves | Beweisqualität | | KEY NUMBERS | 关键数字 | 主要数値 | CIFRAS CLAVE | CHIFFRES CLÉS | KENNZAHLEN | | FAILED_PATHS | 失败路径 | 失敗パス | CAMINOS FALLIDOS | VOIES ÉCHOUÉES | GESCHEITERTE WEGE | | Why it failed | 失败原因 | 失敗の理由 | Por qué falló | Raison de l'échec | Grund des Scheiterns | | Conditions for recurrence | 重犯条件 | 再発条件 | Condiciones de recurrencia | Conditions de récurrence | Wiederholungsbedingungen | | CORE_TENSION | 核心矛盾 | コアの緊張 | TENSIÓN CENTRAL | TENSION CENTRALE | KERNSPANNUNG | | CONSTRAINTS | 约束条件 | 制約 | RESTRICCIONES | CONTRAINTES | EINSCHRÄNKUNGEN | | Hard constraints | 硬约束 | ハード制約 | Restricciones rígidas | Contraintes dures | Harte Einschränkungen | | Soft constraints | 软约束 | ソフト制約 | Restricciones blandas | Contraintes souples | Weiche Einschränkungen | | Self-imposed constraints | 自设约束 | 自己設定制約 | Restricciones autoimpuestas | Contraintes auto-imposées | Selbst gesetzte Einschränkungen | | OPEN_QUESTIONS | 待解问题 | 未解決の問題 | PREGUNTAS ABIERTAS | QUESTIONS OUVERTES | OFFENE FRAGEN | | DECISION_READINESS | 决策准备度 | 意思決定準備度 | PREPARACIÓN PARA DECIDIR | MATURITÉ DÉCISIONNELLE | ENTSCHEIDUNGSREIFE | | Can decide now | 现在可以决定 | 今すぐ決定可能 | Se puede decidir ahora | Peut être décidé maintenant | Jetzt entscheidbar | | Cannot decide yet | 现在不能决定 | まだ決定不可 | No se puede decidir aún | Ne peut pas encore être décidé | Noch nicht entscheidbar | | Single most valuable piece of missing information | 最值得补的一条信息 | 最も重要な未収集情報 | Información faltante más valiosa | Information manquante la plus précieuse | Wertvollste fehlende Information | | Decision confidence index | 决策信心指数 | 意思決定信頼度指数 | Índice de confianza en la decisión | Indice de confiance décisionnelle | Entscheidungsvertrauensindex | | Time sensitivity | 时间敏感度 | 時間的緊急性 | Sensibilidad temporal | Sensibilité temporelle | Zeitkritikalität | | Reversibility | 可逆性 | 可逆性 | Reversibilidad | Réversibilité | Umkehrbarkeit | | SOURCES | 来源 | 情報源 | FUENTES | SOURCES | QUELLEN | | Source | 来源 | 情報源 | Fuente | Source | Quelle | | Type | 类型 | タイプ | Tipo | Type | Typ | | Retrieved | 获取时间 | 取得日時 | Recuperado | Récupéré | Abgerufen | | Access Status | 访问状态 | アクセス状態 | Estado de acceso | Statut d'accès | Zugriffsstatus | | Full text | 全文获取 | 全文取得 | Texto completo | Texte complet | Volltext | | Snippet only | 仅摘要 | スニペットのみ | Solo fragmento | Fragment seulement | Nur Ausschnitt | | Unreachable | 不可达 | アクセス不可 | Inaccesible | Inaccessible | Nicht erreichbar | | RESEARCH_LOG | 研究日志 | 調査ログ | REGISTRO DE INVESTIGACIÓN | JOURNAL DE RECHERCHE | FORSCHUNGSPROTOKOLL | | Region Focus | 地域聚焦 | 地域フォーカス | Enfoque Regional | Focus Régional | Regionaler Fokus | | Research Languages | 研究语言 | 調査言語 | Idiomas de Investigación | Langues de Recherche | Forschungssprachen | | Information Confidence | 信息置信度 | 情報信頼度 | Confianza en la Información | Confiance Informationnelle | Informationsvertrauen | | Biggest Knowledge Gap | 最大知识缺口 | 最大の知識ギャップ | Mayor Brecha de Conocimiento | Plus Grande Lacune | Größte Wissenslücke | | Actionable Decision Scope | 当前可决策范围 | 意思決定可能範囲 | Alcance de Decisión Accionable | Portée Décisionnelle | Entscheidungsrahmen | | COMPARISON MATRIX | 对比矩阵 | 比較マトリクス | MATRIZ DE COMPARACIÓN | MATRICE DE COMPARAISON | VERGLEICHSMATRIX | | Dimension | 维度 | 次元 | Dimensión | Dimension | Dimension | | Evidence Strength | 证据强度 | 証拠の強度 | Solidez de evidencia | Force des preuves | Beweisqualität | | STRENGTHS | 优势 | 強み | FORTALEZAS | FORCES | STÄRKEN | | Strengths | 优势 | 強み | Fortalezas | Forces | Stärken | | RISKS | 风险 | リスク | RIESGOS | RISQUES | RISIKEN | | Risks | 风险 | リスク | Riesgos | Risques | Risiken | | WHEN TO CHOOSE | 适用场景 | 選択シナリオ | CUÁNDO ELEGIR | QUAND CHOISIR | WANN WÄHLEN | | Choose [X] when | 选择 [X] 的场景 | [X] を選ぶシナリオ | Elige [X] cuando | Choisir [X] quand | [X] wählen wenn | | Neither fits when | 两者都不适合时 | どちらも適さない場合 | Ninguno sirve cuando | Ni l'un ni l'autre quand | Keiner passt wenn | | RECOMMENDATION | 建议选择 | 推奨 | RECOMENDACIÓN | RECOMMANDATION | EMPFEHLUNG | | Recommended | 推荐 | 推奨 | Recomendado | Recommandé | Empfohlen | | Rationale | 理由 | 根拠 | Justificación | Justification | Begründung | | Preconditions | 前提条件 | 前提条件 | Condiciones previas | Conditions préalables | Vorbedingungen | | LANDSCAPE | 竞争格局 | 競争環境 | PANORAMA | PAYSAGE | WETTBEWERBSLANDSCHAFT | | Key players | 主要玩家 | 主要プレイヤー | Actores clave | Acteurs clés | Hauptakteure | | Market structure | 市场结构 | 市場構造 | Estructura del mercado | Structure du marché | Marktstruktur | | Notable recent moves | 近期重要动态 | 最近の重要な動き | Movimientos recientes notables | Mouvements récents notables | Bemerkenswerte Entwicklungen | | IMPLICATIONS | 影响与意涵 | 含意 | IMPLICACIONES | IMPLICATIONS | IMPLIKATIONEN | | SCENARIOS | 情景分析 | シナリオ分析 | ESCENARIOS | SCÉNARIOS | SZENARIEN | | Base case | 基准情景 | ベースケース | Caso base | Scénario de base | Basisszenario | | Upside scenario | 乐观情景 | アップサイドシナリオ | Escenario optimista | Scénario optimiste | Positivszenario | | Downside scenario | 悲观情景 | ダウンサイドシナリオ | Escenario pesimista | Scénario pessimiste | Negativszenario | | Key variable driving divergence | 关键分叉变量 | 分岐を決める主要変数 | Variable clave de divergencia | Variable clé de divergence | Schlüsselvariable | | Next concrete action | 下一步具体行动 | 次の具体的なアクション | Próxima acción concreta | Prochaine action concrète | Nächste konkrete Maßnahme | | File | 文件路径 | ファイル | Archivo | Fichier | Datei | | Generated | 生成时间 | 生成日時 | Generado | Généré | Erstellt | | Mode | 研究模式 | モード | Modo | Mode | Modus | **For languages not in this table**: translate naturally into the target language. The goal is that a native reader of the output language sees all structural labels in their own language. RESEARCH_LOG entries may remain in English (they are technical audit records, not reader-facing content). *** ## OUTPUT PERSISTENCE After generating the output: 1. Determine the output path from SEMANTIC INTENT ANALYSIS Q5 (user-mentioned path, or default context/[domain].md) 2. Print confirmation: "✅ Research output saved to: [path]" 3. Before writing, check if the target file already exists 4. If file exists AND the intent is NOT "update": - STOP and ask the user: "File [path] already exists. Overwrite, append, or cancel?" - "Overwrite" → replace the entire file - "Append" → add new content after existing content - "Cancel" → abort, do not write - Only proceed if user explicitly confirms 5. If file does not exist: create parent directories and write normally *** ## EXTERNAL ENDPOINTS This skill uses the following external services: | Service | URL | Data sent | Purpose | |---------|-----|-----------|---------| | Web search provider | Depends on configuration (e.g. api.serper.dev, api.tavily.com, api.search.brave.com) | Search query strings | Fetching search results for research | | Web pages | Any URL returned by search results | HTTP GET request only (no user data sent) | Full-text fetch for evidence verification | No user data beyond the research query is sent to any external service. The research query itself is sent to the configured search provider as a plain search string. *** ## SECURITY & PRIVACY - **What leaves your device**: The research topic/query (as a search string), and HTTP GET requests to web pages found in search results. - **What stays local**: All generated reports are saved to the local filesystem only. No report content is sent to any external service. - **API keys**: Search provider API keys are read from environment variables and sent only to the corresponding provider's API endpoint. They are never logged or included in output files. - **No telemetry**: This skill collects no usage data, analytics, or telemetry of any kind. *** ## TRUST STATEMENT When you use deep-researcher: 1. Your research query is sent to the web search provider you configured (Serper, Tavily, Brave, Gemini, or similar). 2. The skill fetches full text from web pages identified in search results — these are standard HTTP GET requests, no different from opening a page in a browser. 3. All analysis, synthesis, and report generation happen locally within the AI agent's context. 4. The final report is written to your local filesystem at the path you specify (or `context/[domain].md` by default). 5. Nothing else leaves your machine.

path: CHANGELOG.md
content: # Changelog

All notable changes to deep-researcher will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.1] - 2026-04-28

### Changed
- Add Chinese description for better discoverability in Chinese-language skill search

## [1.0.0] - 2026-04-28

### Added
- Initial release of deep-researcher

**Core report structure**
- Top 5 Consensus with evidence strength tags (HIGH / MEDIUM / LOW)
- Top 5 Divergences with both sides' arguments side by side
- Key Numbers with mandatory source citations; forecasts marked `[ESTIMATED]`
- Failed Paths with failure reasons and recurrence conditions
- Core Tension — the irreducible contradiction in one sentence
- Decision Readiness with confidence index (0–10) and next concrete action

**Optional sections (auto-included when relevant)**
- Landscape — competitive/ecosystem structure, key players, recent moves
- Implications — stakeholder-specific impact analysis
- Scenarios — base / upside / downside scenario analysis

**Research engine**
- 5-angle deep search protocol (direct, critical, practitioner, forward-looking, cross-domain)
- Local-language research: auto-detects domain region and searches in official local language
- Fallback language inference (Steps A–D) for regions not in the explicit mapping table
- Multi-language and supranational region handling (EU, Schengen, multilingual countries)
- Multi-country region language allocation (e.g. Southeast Asia → per-country language assignment)

**Semantic intent routing**
- Automatic mode detection from natural language: brief, compare, brief-multi, compare-multi, update, file-only
- No flags or explicit commands required
- Per-subject independent region and language detection in multi-subject mode

**Evidence quality**
- Evidence scoring (HIGH / MEDIUM / LOW) with mandatory source citations
- Full-text fetch before inference (anti-hallucination)
- Vendor self-reported data auto-downgraded to LOW
- Forecast/estimate values marked `[ESTIMATED]`
- Full-text fetch failure handling: evidence downgrade + annotation

**Output**
- Section title localization: all structural labels translated for zh / ja / es / fr / de output
- Overwrite protection: prompts before overwriting existing files
- RESEARCH_LOG with second-precision timestamps for reproducibility

**Environment**
- Startup check: detects missing web search tool and guides user to configure a provider
- Supports: Serper, Tavily, Brave Search, Gemini, Kimi/Moonshot, and any tool named `*search*`


path: README.md
content: # deep-researcher

**Domain Research Report Generator** — an AI agent skill that turns any research topic into a structured, decision-ready report in minutes.

## What it produces

For any domain, runs multi-angle deep research and outputs a structured `.md` report:

| Section | Description |
|---------|-------------|
| **Top 5 Consensus** | Core established facts, each tagged with evidence strength (HIGH / MEDIUM / LOW) |
| **Top 5 Divergences** | Contested questions with both sides' arguments side by side |
| **Key Numbers** | Critical metrics, every figure sourced, forecasts marked `[ESTIMATED]` |
| **Failed Paths** | Directions already proven unworkable, with reasons and recurrence conditions |
| **Core Tension** | The irreducible contradiction at the heart of the domain, in one sentence |
| **Decision Readiness** | What can be decided now vs. what needs more information, with confidence index 0–10 and next concrete action |
| **Landscape** *(optional)* | Competitive/ecosystem structure — key players, market structure, recent moves |
| **Implications** *(optional)* | What the findings mean for each stakeholder group |
| **Scenarios** *(optional)* | Base / upside / downside scenarios for high-uncertainty topics |

## What makes it different

**Anti-hallucination enforcement** — full-text fetch before any inference; vendor self-reported data is automatically downgraded to LOW evidence.

**Local-language research** — auto-detects the domain's region and searches primary sources in the official local language. No configuration needed:
- Greek labor law → searched in ελληνικά, hits the Ministry of Labour directly
- Panama maritime regulations → searched in Español, hits amp.gob.pa
- Vietnam e-commerce law → searched in Tiếng Việt, finds the 2025 National Assembly legislation that English search misses entirely

**Semantic intent routing** — infers research mode, subjects, region, language, and output path from meaning. No flags or options:
- `调研AWS、阿里云和华为云` → brief-multi (parallel research on 3 subjects)
- `AWS和阿里云哪个更适合出海` → compare (head-to-head)
- `更新我关于东南亚电商的研究` → update (read existing report, add new findings)

**Per-subject independence** — in multi-subject mode, each subject gets its own region detection and language. AWS searched in English, Alibaba Cloud searched in Chinese, no cross-contamination.

**Evidence scoring** — every claim rated HIGH / MEDIUM / LOW with source citations. LOW claims carry a mandatory warning. See [`references/evidence-scoring.md`](references/evidence-scoring.md).

## Installation

Install as a skill in any compatible AI agent environment. Copy the skill files into your agent's skills directory, or use the pre-packaged zip:

**Option A — ZIP install**

1. Download [`deep-researcher-skill.zip`](deep-researcher-skill.zip)
2. Import it through your agent platform's skill install UI

**Option B — Manual**

```bash
# Copy skill files into your agent's skills directory
# (adjust path to match your platform)
mkdir -p ~/.your-agent/skills/deep-researcher
cp -R SKILL.md references/ strategies/ templates/ ~/.your-agent/skills/deep-researcher/
```

## Usage

Just describe what you want — the skill is triggered automatically when the AI recognizes research intent:

> "帮我调研东南亚电商物流"
> "Research the current state of Germany's manufacturing digitalization"
> "AWS和阿里云哪个更适合出海业务"
> "Update my notes on Vietnam e-commerce with the latest developments"

The skill infers everything from your description: how many subjects, whether to compare or do parallel research, which region and language to use, and where to save the output.

You can also invoke it explicitly with `/deep-researcher`:

```
/deep-researcher Southeast Asia e-commerce logistics
/deep-researcher AWS and Alibaba Cloud — which fits better for overseas expansion?
/deep-researcher research AWS, Alibaba Cloud and Huawei Cloud
/deep-researcher update my research on Vietnam e-commerce
/deep-researcher save results to reports/japan-saas.md  Japan SaaS market
```

## Search provider setup

deep-researcher requires a web search tool. If your agent platform has a built-in web search tool, it works out of the box. Otherwise, configure one of the following search providers:

| Provider | Recommended for | Free tier | Get key |
|----------|----------------|-----------|---------|
| **Serper** ⭐ | General research — real Google results | 2,500/month | [serper.dev](https://serper.dev) → `SERPER_API_KEY` |
| **Tavily** | Deep research — AI-optimized results | 1,000/month | [tavily.com](https://tavily.com) → `TAVILY_API_KEY` |
| **Brave Search** | Privacy-first, no Google dependency | 2,000/month | [brave.com/search/api](https://brave.com/search/api/) → `BRAVE_API_KEY` |
| **Gemini** | No credit card needed | 500 req/day | [aistudio.google.com](https://aistudio.google.com/apikey) → `GEMINI_API_KEY` |
| **Kimi / Moonshot** | Paid, Alipay accepted | Paid | [platform.moonshot.cn](https://platform.moonshot.cn) → `KIMI_API_KEY` |

**Serper** is the recommended default — it returns real Google search results, which gives deep-researcher the best coverage for local-language searches across all regions.

Set the API key as an environment variable and restart your agent:

```bash
export SERPER_API_KEY=your_key_here
```

## File structure

```
deep-researcher/
├── SKILL.md                      # Main skill definition — all logic lives here
├── references/
│   └── evidence-scoring.md       # Evidence strength criteria (HIGH/MEDIUM/LOW)
├── strategies/
│   └── search-protocol.md        # Search angles, language rules, multi-subject protocol
├── templates/
│   ├── decision-brief.md         # Output template for brief / brief-multi modes
│   └── comparison.md             # Output template for compare / compare-multi modes
└── deep-researcher-skill.zip     # Pre-packaged install zip
```

## Output languages

The report is written in the same language as your query. Research is conducted in the domain's local language regardless of the output language — a Chinese-language query about Greek labor law will search in Greek but output in Chinese.

## License

Apache 2.0


path: references/evidence-scoring.md
content: # Evidence Scoring Criteria
# For: Deep Researcher v1
# Purpose: Define how to classify evidence strength for claims

***

## Evidence Levels

### HIGH — Strong Evidence
**Definition**: Repeated across strong or primary sources. Can be treated as established fact for decision purposes.

**Required conditions** (ALL must be met):
- 2+ independent authoritative sources agree
- Sources are primary (original report, official data, direct practitioner account) or high-quality secondary analysis
- No credible contradiction found
- Information is current (within relevant timeframe for the domain)

**Examples**:
- Market size from 2+ industry reports
- Technical specification from official documentation
- Regulatory requirement from government source
- Widely-reported event from multiple news outlets

**How to mark**: `[HIGH]` prefix + source references

***

### MEDIUM — Moderate Evidence
**Definition**: Plausible and partially supported, but not yet fully verified or has limited contradiction.

**Typical conditions** (meets SOME but not all HIGH criteria):
- Only 1 authoritative source + 1 supporting source
- Multiple sources but some are secondary or less authoritative
- Generally consistent but with minor contradictions
- Information is somewhat dated but not obviously stale

**Examples**:
- Market trend reported by 1 major outlet + mentioned by a practitioner
- Technical claim supported by documentation but contradicted by user reports
- Industry estimate from a single reputable analyst

**How to mark**: `[MEDIUM]` prefix + source references

**Special note**: When a claim has equal supporting and contradicting evidence, treat it as MEDIUM at best and move it to DIVERGENCES.

***

### LOW — Weak Evidence
**Definition**: Anecdotal, emerging, or weakly verified. Should not be the sole basis for a decision.

**Typical conditions**:
- Single source only
- Source is informal (blog post, forum comment, social media)
- Emerging trend with limited data
- Self-reported or self-interested source (vendor claims, marketing materials)
- No independent verification possible

**Examples**:
- A single user's experience report
- Vendor's claimed performance numbers (not independently verified)
- Early-stage research with no replication
- Community speculation or rumor

**How to mark**: `[LOW]` prefix + source references

**Required action**: Any LOW evidence used in the output MUST be accompanied by an explicit warning:
> ⚠️ This claim is based on a single or weak source — treat with caution when making decisions.

***

## Source Type Classification

| Type | Definition | Default Evidence Weight |
|------|------------|------------------------|
| Authoritative Report | Government data, industry reports, academic papers, official documentation | HIGH baseline |
| Practitioner | First-hand experience, case studies, technical write-ups from domain practitioners | MEDIUM baseline |
| Public Web | News media, encyclopedias, commercial analysis | MEDIUM baseline |
| Community | Forums, social media, user comments | LOW baseline |

**Note**: Source type is a starting point, not a ceiling. A practitioner account with specific, verifiable details can be elevated. An authoritative report that is clearly outdated can be downgraded.

***

## Special Cases

### Single Source Rule
Any claim supported by only one source, regardless of source type, is capped at MEDIUM.
If the single source is non-authoritative, it defaults to LOW.

### Recency Discount
- Data older than the domain's typical update cycle should be downgraded one level
- Example: In fast-moving tech domains, data > 2 years old should be marked down
- Example: In regulated industries, regulatory data remains HIGH regardless of age

### Conflict of Interest
- Vendor claims about own products: **start at LOW unless independently verified by a third party**
  - This includes: vendor-announced GMV, user counts, performance benchmarks, market share claims
  - Only upgrade from LOW when an independent source corroborates the specific claim
  - Partial verification (e.g., "analyst estimates roughly align") can upgrade to MEDIUM, never directly to HIGH
- Consultant reports commissioned by a stakeholder: start at MEDIUM unless methodology is transparent
- Academic research funded by industry: note the funding source, no automatic downgrade but flag it
- **Enforcement rule**: When you encounter a vendor claim, explicitly check: "Is this independently verified?" If not → LOW + ⚠️ warning

### Numbers and Statistics
- Any specific number must have an explicit source citation
- Ranges are preferred over point estimates when sources disagree
- If the number comes from a model/estimate (not measurement), mark as [ESTIMATED]
- **Forecast/prediction numbers must ALWAYS be marked [ESTIMATED]**: market size projections, growth rates, future adoption rates, revenue forecasts — even from authoritative sources
- **Vendor self-reported numbers must ALWAYS be marked [ESTIMATED]** and start at LOW evidence level (see Conflict of Interest rule)
- Format: `[ESTIMATED] $150B (2025 forecast) [source: URL]`
- If a number's time horizon is ambiguous (e.g., "market size $150B" without year), clarify or mark [ESTIMATED]

***

## Scoring in --mode=compare

When comparing A vs B:
- Apply the SAME evidence standard to both sides
- If A has 3 HIGH sources and B has 1 MEDIUM source for the same dimension, note the asymmetry
- Never upgrade B's evidence just to "balance" the comparison
- Asymmetric evidence quality IS a valid finding — it means one side is less understood or less transparent


path: strategies/search-protocol.md
content: # Search Protocol
# For: Deep Researcher v1
# Purpose: Define search angles, language rules, and verification protocol for deep research mode

***

## Search Protocol (Deep Research — All Modes)

| Item | Requirement |
|------|-------------|
| Searches | 3-5 from different angles |
| Full-text Fetches | top 3-5 results per search |
| Cross-verification | required for ALL claims |
| Contradiction hunting | actively seek opposing evidence |

***

## Search Angles (Always Use All 5)

1. **Direct/factual**: "[domain] overview status"
   → Aim: Establish baseline understanding from authoritative sources

2. **Critical/contrarian**: "[domain] problems challenges risks limitations"
   → Aim: Surface failure modes, dissenting views, and known issues

3. **Practitioner/insider**: "[domain] experience case study best practice"
   → Aim: Ground-level evidence from people who actually do the work

4. **Forward-looking**: "[domain] trends future predictions forecast"
   → Aim: Identify trajectory and momentum signals

5. **Cross-domain**: "[domain] vs [alternative] comparison"
   → Aim: Understand positioning, alternatives, and opportunity cost

***

## Multi-subject Search Strategy

When MODE ROUTING (SKILL.md) determines there are 2+ subjects, apply this protocol.
Mode (compare / compare-multi / brief-multi) is determined by semantic intent analysis in SKILL.md — not here.

**Core rule**: each subject is researched **independently** — do NOT conflate subjects into shared search queries until the COMPARE/SCORE step.

### Per-subject execution
For each subject S:
1. Run STEP 1 region detection independently for S
2. Determine S's language per the language assignment rules
3. Execute all 5 search angles using S's language
4. Record: `[HH:MM:SS] Subject: [S] → region: [R] → language: [L]`

### Comparative search (after all subjects collected)
- 2 subjects: one comparative search `[A] vs [B]`
- 3 subjects: one 3-way search `[A] vs [B] vs [C]`; add pairwise if needed
- 4+ subjects: pairwise for the most decision-relevant pairs only; skip low-value combinations

### Total search count
- N subjects × 5 angles + 1~N comparative searches
- For N > 4: consider reducing to 3 most relevant subjects to preserve depth over breadth

### Same-language subjects
When two subjects share a research language (e.g. Alibaba Cloud and Huawei Cloud, both → Chinese):
- Keep their searches **separate** — do not merge into one search
- Include the subject name in every keyword to maintain per-subject resolution:
  - ✅ "Alibaba Cloud 2025 market share" and "Huawei Cloud 2025 market share"
  - ❌ "Alibaba Cloud and Huawei Cloud 2025 market share"

### Research depth symmetry
Before moving to SCORE, verify each subject received equivalent research depth:
- [ ] All subjects have completed all 5 search angles
- [ ] Full-text fetch counts across subjects differ by no more than 2
- [ ] Comparative search executed
- [ ] If asymmetry exists, document in RESEARCH_LOG and note in output
- Never proceed to COMPARE/SCORE if any subject has fewer than 3 search angles completed

***

## Full-text Fetch Rules

### When to fetch full text
- Search snippets that contain a key claim used in CONSUS, DIVERGENCES, or FAILED_PATHS
- Search snippets with specific numbers or statistics
- Search snippets that contradict other findings (need to verify context)

### When NOT to fetch full text
- Search snippets that only confirm what is already well-established from 2+ other sources

### Fetch priority
1. Claims used in CONSENSUS (highest priority — these are treated as fact)
2. Claims used in DIVERGENCES (need full context for both sides)
3. Specific numbers cited (must have source)
4. Contradictory findings (need to understand context)

### When full-text fetch fails
If the source URL is inaccessible (403, 404, paywall, anti-scraping, timeout), follow these rules:
- Claims based solely on search snippets (where full-text fetch failed) must be:
  - **Downgraded by one evidence level** (HIGH→MEDIUM, MEDIUM→LOW)
  - **Annotated with**: `[full-text fetch failed — based on search snippet only]`
- **CONSENSUS claims must never rely on a failed-fetch source alone** — always find a fetchable alternative first. If no fetchable alternative exists, move the claim to DIVERGENCES or [UNKNOWN].
- Do NOT use training data or prior knowledge to fill in what the full text might have said
- In RESEARCH_LOG, record the failure: `[timestamp] Full text fetch FAILED: [URL] → [reason: 403/paywall/anti-scraping]`

***

## Cross-verification Rules

### Minimum source count by evidence level
- HIGH: must have 2+ independent authoritative sources
- MEDIUM: at least 1 authoritative source + 1 supporting source
- LOW: single source is acceptable but must be marked

### What counts as "independent"
- Two articles from different outlets (not republishing the same wire)
- A report + a practitioner account
- A primary source + secondary analysis

### What does NOT count as independent
- Same article republished on multiple platforms
- Two articles citing the same single original source
- A summary and its original (count as 1)

### Contradiction handling
If two sources directly contradict on a factual claim:
1. Note the contradiction in DIVERGENCES
2. Do not pick a side unless a third source breaks the tie
3. If no tie-breaker exists, mark as [CONTESTED] with both sources

***

## Search Language and Region

### Region detection (always run at STEP 1)
- Detect the domain region from the query topic itself — do NOT wait for an explicit --region flag
- Examples: "日本SaaS市場" → region=Japan, "mercado logístico alemán" → region=Germany
- If the topic is inherently global (e.g. "AI Agent frameworks"), region = global, no local-language requirement

### Language assignment rules (hard rules)
| Condition | Angles 1–2 (mandatory) | Angles 3–5 |
|-----------|------------------------|------------|
| region = global | User query language or English | User query language or English |
| region = China/Taiwan/HK | Chinese (中文) | Chinese or English |
| region = Japan | Japanese (日本語) | English or Japanese |
| region = Korea | Korean (한국어) | English or Korean |
| region = Germany/Austria | German (Deutsch) | English or German |
| region = France | French (Français) | English or French |
| region = Indonesia/Malaysia | Bahasa Indonesia/Melayu | English or local |
| region = Thailand | Thai (ภาษาไทย) | English or Thai |
| region = Vietnam | Vietnamese (Tiếng Việt) | English or Vietnamese |
| region = Arabic-speaking | Arabic (العربية) | English or Arabic |
| region = Russia/CIS | Russian (Русский) | English or Russian |
| region = Spain/Latin America | Spanish (Español) | English or Spanish |
| region = other single country | Official local language of that country (see fallback inference below) | English or local |

### Fallback language inference (when region is not in the table above)
When the detected region does not match any explicit entry in the language assignment table,
**do not default to English** — instead, run this inference sequence:

**Step A — Infer from the query itself**
- Does the query contain non-ASCII words that identify a language?
  - Greek letters (α, β, γ…) → ελληνικά
  - Arabic script (ا, ب, ت…) → العربية
  - Cyrillic (А, Б, В…) → Русский (or relevant CIS language)
  - Thai script → ภาษาไทย
  - Devanagari (अ, आ…) → हिन्दी / local South Asian language
- Does the query contain a country name or demonym that implies a language?
  - "Greek / Ελληνικά / Grèce / Grecia" → ελληνικά
  - "Polish / Polska / polskie" → Polski
  - "Dutch / Netherlands / Holland" → Nederlands
  - "Swedish / Sverige" → Svenska
  - "Norwegian / Norge" → Norsk
  - "Finnish / Suomi" → Suomi
  - "Czech / Česká" → Čeština
  - "Portuguese / Portugal / Brasil" → Português
  - "Italian / Italia" → Italiano
  - "Turkish / Türkiye" → Türkçe
  - "Hebrew / Israel" → עברית
  - "Hindi / India (non-regional)" → हिन्दी or English (India is multilingual)
  - "Swahili / Kenya / Tanzania" → Kiswahili
  - "Malay / Malaysia / Brunei" → Bahasa Melayu

**Step B — Look at the domain context**
- If the topic is a government policy, legal regulation, or official standard:
  → The official language of that government is almost always the right language
  → Example: "Norwegian oil regulations" → Norsk (Bokmål), even though English is also official in some contexts
- If the topic involves a specific sub-national region within a multi-language country:
  → Use that region's dominant local language, NOT the national default language
  → Example (India): Tamil Nadu policy → Tamil (தமிழ்); Kerala policy → Malayalam (മലയാളം); Maharashtra → Marathi (मराठी); NOT Hindi
  → Example (Spain): Catalonia policy → Catalan (Català); Basque Country → Euskara; NOT just Spanish
  → Example (China): generally 中文; Hong Kong context → Traditional Chinese or Cantonese-influenced writing
- If the topic is an international standard applied locally:
  → Use the country's official language for local implementation details
  → Use English for the international standard itself

**Step C — When inference is genuinely ambiguous**
- If after Steps A and B the language is still unclear (e.g. India with many regional languages, or a topic cutting across multiple regions):
  1. Use English as angle 1, and the most probable local language as angle 2
  2. Record the ambiguity in RESEARCH_LOG: `[HH:MM:SS] Language inference ambiguous for region [X] → Used [languages] → Reason: [why uncertain]`
  3. Do NOT silently default to English-only — the ambiguity must be documented

**Step D — Validate the choice**
Before executing angle 1, confirm: "Does my search keyword read like a native speaker would write it, or does it look like a translation?" If the latter, reformulate before searching.

### Multi-language and supranational regions (hard rules)
For regions with no single dominant official language:

| Region type | Angles 1–2 language rule |
|-------------|--------------------------|
| EU-wide policy (Schengen, GDPR, subsidies, directives) | English + French (EU's two primary working languages) |
| Schengen Area (multi-country context) | English + French, OR English + language of the primary member state in context |
| Belgium | Dutch if Flemish context; French if Walloon/federal context |
| Switzerland | German (primary); French if western-Swiss context |
| Canada | English; French if Quebec-specific context |
| International organizations (IMO, UN, WTO, World Bank, OECD) | English (primary working language) |
| Other multi-language regions | English + official language of the most contextually relevant country |

**Document language choice**: For any multi-language or supranational region, always record in RESEARCH_LOG:
`[HH:MM:SS] Region detected: [region] → Multi-language region → Language selected: [language(s)] → Rationale: [why]`
Never default to English-only for a multi-language region without documenting the rationale.

### Multi-country region language allocation (hard rules)
When the topic covers **multiple countries that each have their own mapped language**
(e.g. "Southeast Asia major countries", "Central America", "Nordic countries", "Gulf states"):

**Allocation rule**:
1. Identify the 2–3 most contextually relevant countries for the specific topic
   (prioritize by: explicit mention in query > policy importance > market size > alphabetical)
2. Assign those countries' mapped languages to angles 1–3 (one language per angle)
3. Use English for angles 4–5 (regional overview sources, international reports)
4. Record in RESEARCH_LOG:
   `[HH:MM:SS] Region: [multi-country] → Countries prioritized: [A, B, C] → Angle languages: [lang1, lang2, lang3, EN, EN] → Rationale: [why this priority]`

**Examples**:

| Topic | Countries prioritized | Angles 1–3 | Angles 4–5 |
|-------|----------------------|------------|------------|
| Southeast Asia e-commerce | Indonesia, Vietnam, Thailand | Bahasa Indonesia, Tiếng Việt, ภาษาไทย | English |
| Southeast Asia labor law | Indonesia, Philippines, Thailand | Bahasa Indonesia, English (PH official), ภาษาไทย | English |
| Central America agriculture policy | Mexico, Guatemala, Honduras | Español (add country name to differentiate) | English |
| Nordic welfare systems | Sweden, Denmark, Norway | Svenska, Dansk, Norsk | English |
| Gulf states infrastructure | UAE, Saudi Arabia, Qatar | العربية (UAE context), العربية (SA context), English | English |

**When all countries in the region share a language** (e.g. all Central American countries → Spanish,
all Arabic Gulf states → Arabic):
→ Use the shared language for angles 1–2, differentiated by country-specific keywords
→ Use English for angle 3 onward

### Region and language inference
Region and research language are always inferred from the query topic itself — no explicit instruction needed.
Follow the language assignment table and fallback inference rules below.
If the user mentions a specific region or language in their query (e.g. "focus on the EU market", "search in Japanese"),
treat that as a strong hint and apply accordingly.

### Enforcement
- **Record the actual language used** for each angle in RESEARCH_LOG
- **Do NOT substitute English for a required local-language search** — English may only be used for angles 3–5 when region is non-global
- If the search engine does not return local-language results for the required language, note this in RESEARCH_LOG and try a reformulated local-language query before falling back to English

***

## Search Quality Checklist

Before moving from STEP 2 (COLLECT) to STEP 3 (SCORE), verify:
- [ ] 3-5 searches completed (covering all 5 angles)
- [ ] Top 3-5 results fetched for full text
- [ ] All claims have source references
- [ ] No claim relies solely on a search snippet without full-text verification (or is downgraded per full-text fetch failure rules)
- [ ] Contradictory findings identified and noted
- [ ] All full-text fetch failures are recorded and affected claims downgraded
- [ ] If --mode=compare, both subjects received equal search coverage (symmetry checkpoint passed)
- [ ] If information is scarce (< 3 valid sources total), mark domain as "information-scarce" per SKILL.md rules
- [ ] **If region ≠ global: Angles 1 and 2 were executed in the official local language** (check RESEARCH_LOG — each angle entry must show the actual language used)
- [ ] **If region ≠ global: At least 2 local-language sources appear in the SOURCES table**


path: templates/comparison.md
content: # Template: Comparative Analysis
# Mode: --mode=compare
# Used by: /deep-researcher [A] vs [B] (or semantic compare intent)

***

# Comparative Analysis: [A] vs [B]
# File: context/[A]-vs-[B].md
# Generated: [date]
# Mode: compare (deep research)
# Region Focus — [A]: [region] | [B]: [region]
# Research Languages — [A]: [language] | [B]: [language]
# Information Confidence: HIGH | MEDIUM | LOW

***

## SCOPE
- Comparison scope: ___
- Comparison dimensions: ___
- Out of scope: ___

## COMPARISON MATRIX

| Dimension | [A] | [B] | Evidence Strength |
|-----------|-----|-----|-------------------|
| ___ | ___ | ___ | HIGH/MEDIUM/LOW |
| ___ | ___ | ___ | HIGH/MEDIUM/LOW |
| ___ | ___ | ___ | HIGH/MEDIUM/LOW |
| ___ | [ESTIMATED] ___ | ___ | LOW (vendor claim) |
| ___ | ___ | ___ | HIGH/MEDIUM/LOW |
| ___ | ___ | ___ | HIGH/MEDIUM/LOW |
| ___ | ___ | ___ | HIGH/MEDIUM/LOW |
| ___ | ___ | ___ | HIGH/MEDIUM/LOW |

## STRENGTHS

### [A] Strengths
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]

### [B] Strengths
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]

## RISKS

### [A] Risks
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]

### [B] Risks
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]

## FAILED_PATHS
- [path] (Why it failed: ___; Conditions for recurrence: ___) [source: URL/citation]
- [path] (Why it failed: ___; Conditions for recurrence: ___) [source: URL/citation]

<!-- ═══ OPTIONAL SECTIONS — include when relevant, omit when not ═══ -->

## LANDSCAPE *(include for market/technology/competitive topics)*
- Key players beyond [A] and [B]: [name] — [positioning] [source]
- Market structure: fragmented | consolidated | duopoly | emerging
- Notable recent moves: [event, date] [source]

## IMPLICATIONS *(include when comparison has broader stakeholder impact)*

**For [stakeholder A]**: ___ (second-order: ___)
**For [stakeholder B]**: ___ (second-order: ___)

## SCENARIOS *(include for high-uncertainty decisions)*

- **Base case**: ___
- **If [A] wins**: ___
- **If [B] wins**: ___
- Key variable driving outcome: ___

<!-- ═══════════════════════════════════════════════════════════════ -->

## CORE_TENSION
___

## CONSTRAINTS
Hard constraints:
- ___

Soft constraints:
- ___

Self-imposed constraints:
- ___

## WHEN TO CHOOSE

### Choose [A] when
- ___
- ___

### Choose [B] when
- ___
- ___

### Neither fits when
- ___

## RECOMMENDATION
**Recommended: [A] / [B] / Context-dependent / Defer decision**

Rationale:
- ___
- ___

Preconditions:
- ___
- ___

## DECISION_READINESS
- Can decide now: ___
- Cannot decide yet: ___
- Single most valuable piece of missing information: ___
- **Next concrete action**: ___
- Decision confidence index: _/10
- Time sensitivity: high | medium | low
- Reversibility: reversible | partially reversible | irreversible

## OPEN_QUESTIONS
- ___
- ___
- ___

## SOURCES
| Source | Type | Retrieved | Access Status |
|--------|------|-----------|---------------|
| [URL/citation] | Authoritative Report \| Practitioner \| Public Web \| Community | [date] | ✅ Full text \| ⚠️ Snippet only \| ❌ Unreachable |
| [URL/citation] | Authoritative Report \| Practitioner \| Public Web \| Community | [date] | ✅ Full text \| ⚠️ Snippet only \| ❌ Unreachable |
| [URL/citation] | Authoritative Report \| Practitioner \| Public Web \| Community | [date] | ✅ Full text \| ⚠️ Snippet only \| ❌ Unreachable |

## RESEARCH_LOG
- [HH:MM:SS] Mode routing: subjects=2, intent=compare, mode=compare — [rationale]
- [HH:MM:SS] Subject [A]: region=[region] → language=[language]
- [HH:MM:SS] Subject [B]: region=[region] → language=[language]
- [HH:MM:SS] Search [A] (angle 1, [language]): "[keyword]" → N results
- [HH:MM:SS] Search [A] (angle 2, [language]): "[keyword]" → N results
- [HH:MM:SS] Search [A] (angle 3–5): "[keyword]" → N results
- [HH:MM:SS] Search [B] (angle 1, [language]): "[keyword]" → N results
- [HH:MM:SS] Search [B] (angle 2, [language]): "[keyword]" → N results
- [HH:MM:SS] Search [B] (angle 3–5): "[keyword]" → N results
- [HH:MM:SS] Comparative search: "[A] vs [B]" → N results
- [HH:MM:SS] Full text fetch: [URL] → [key finding] / FAILED ([reason])
- [HH:MM:SS] Cross-verify: [claim] → confirmed / disputed


path: templates/decision-brief.md
content: # Template: Research Report (Standard)
# Mode: --mode=brief (default)
# Used by: /deep-researcher [domain]

***

# Research Report: [Domain]
# File: context/[domain].md
# Generated: [date]
# Mode: brief (deep research)
# Region Focus: [region or global]
# Research Languages: [languages used]
# Information Confidence: HIGH | MEDIUM | LOW
# Biggest Knowledge Gap: ___
# Actionable Decision Scope: ___

***

## SCOPE
- Domain boundary: ___
- Out of scope: ___

## CONSENSUS
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]
- [HIGH|MEDIUM|LOW] ___ [source: URL/citation]

## DIVERGENCES

**Divergence 1**: ___
- 🔵 Supporting: ___ [source: URL/citation]
- 🔴 Opposing: ___ [source: URL/citation]
- Evidence strength: ___

**Divergence 2**: ___
- 🔵 Supporting: ___ [source: URL/citation]
- 🔴 Opposing: ___ [source: URL/citation]
- Evidence strength: ___

## KEY NUMBERS
- [ESTIMATED] ___: ___ (forecast/estimate) [source: URL/citation]
- ___: ___ (measured) [source: URL/citation]
- ___: ___ [source: URL/citation]

## FAILED_PATHS
- [path] (Why it failed: ___; Conditions for recurrence: ___) [source: URL/citation]
- [path] (Why it failed: ___; Conditions for recurrence: ___) [source: URL/citation]

<!-- ═══ OPTIONAL SECTIONS — include when relevant, omit when not ═══ -->

## LANDSCAPE *(include for market/technology/competitive topics)*
- Key players: [name] — [positioning] [source]
- Market structure: fragmented | consolidated | duopoly | emerging
- Notable recent moves: [event, date] [source]

## IMPLICATIONS *(include when domain has clear stakeholder impact)*

**For [stakeholder A]**: ___ (second-order: ___)
**For [stakeholder B]**: ___ (second-order: ___)

## SCENARIOS *(include for high-uncertainty or strategic decisions)*

- **Base case** (most likely): ___
- **Upside scenario**: ___ (requires: ___)
- **Downside scenario**: ___ (requires: ___)
- Key variable driving divergence: ___

<!-- ═══════════════════════════════════════════════════════════════ -->

## CORE_TENSION
___

## CONSTRAINTS
Hard constraints:
- ___

Soft constraints:
- ___

Self-imposed constraints:
- ___

## OPEN_QUESTIONS
- ___
- ___
- ___

## DECISION_READINESS
- Can decide now: ___
- Cannot decide yet: ___
- Single most valuable piece of missing information: ___
- **Next concrete action**: ___
- Decision confidence index: _/10
- Time sensitivity: high | medium | low
- Reversibility: reversible | partially reversible | irreversible

## SOURCES
| Source | Type | Retrieved | Access Status |
|--------|------|-----------|---------------|
| [URL/citation] | Authoritative Report \| Practitioner \| Public Web \| Community | [date] | ✅ Full text \| ⚠️ Snippet only \| ❌ Unreachable |
| [URL/citation] | Authoritative Report \| Practitioner \| Public Web \| Community | [date] | ✅ Full text \| ⚠️ Snippet only \| ❌ Unreachable |
| [URL/citation] | Authoritative Report \| Practitioner \| Public Web \| Community | [date] | ✅ Full text \| ⚠️ Snippet only \| ❌ Unreachable |

## RESEARCH_LOG
- [HH:MM:SS] Mode routing: subjects=N, intent=[research/compare/update], mode=[brief/compare/...] — [rationale]
- [HH:MM:SS] Region detected: [region] → Research language: [language]
- [HH:MM:SS] Search (angle 1, [language]): "[keyword]" → N results
- [HH:MM:SS] Search (angle 2, [language]): "[keyword]" → N results
- [HH:MM:SS] Search (angle 3, [language]): "[keyword]" → N results
- [HH:MM:SS] Search (angle 4, [language]): "[keyword]" → N results
- [HH:MM:SS] Search (angle 5, [language]): "[keyword]" → N results
- [HH:MM:SS] Full text fetch: [URL] → [key finding] / FAILED ([reason])
- [HH:MM:SS] Cross-verify: [claim] → confirmed / disputed


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)