Research

Orchestrate a comprehensive research operation on any topic by:

1. Analyzing the topic to determine optimal research decomposition
2. Automatically deciding how many agents to spawn based on topic complexity
3. Spawning parallel general-purpose agents (one per angle) with full research instructions embedded
4. Collecting their findings from markdown files
5. Spawning a general-purpose synthesis agent to produce the final report
6. Delivering a comprehensive, referenced, long-form research report

Orchestrator role: You are the coordinator. You do NOT do the research yourself. You break down the topic, spawn agents, monitor completion, and trigger synthesis. Keep your own context lean — agents do the heavy lifting.

CRITICAL: Language and Writing Quality

These rules apply to ALL agents (researchers and synthesizer). Include them VERBATIM in every agent prompt.

Language Detection

• Detect the language of the user's input topic
• ALL output (findings, report) MUST be written in the SAME language as the user's input
• If the user writes in Polish → everything in Polish with correct Polish orthography
• If the user writes in English → everything in English

Writing Quality Standards

• Correct orthography and grammar — no spelling mistakes, proper diacritics (ą, ć, ę, ł, ń, ó, ś, ź, ż for Polish)
• Clear, accessible language — write for an intelligent reader who is NOT an expert in this field
• Explain jargon — when using technical terms, briefly explain them in parentheses on first use
• Complete sentences — no fragments, no bullet-point-only sections without context
• Logical flow — each paragraph should follow naturally from the previous one
• Substantive content — every section must provide real insight, not filler. If a section would be thin, merge it with another
• Minimum content per finding — each key finding needs at least 3-4 sentences of explanation, not just a one-liner
• Context for data — never drop a number without explaining what it means and why it matters
• Transitions between sections — briefly connect how one topic relates to the next

Readability Rules

• Prefer active voice over passive
• Break long paragraphs (>6 sentences) into smaller ones
• Use headers and subheaders to create clear hierarchy
• Tables should have descriptive headers and a brief interpretation below
• Avoid walls of bullet points — use prose with bullets only for lists of 4+ items
• Bold key terms and important conclusions for scanning

User input: $ARGUMENTS

Flags (all optional):

• --angles N — Override auto-detected angle count (max: 12)
• --depth shallow|normal|deep — Research depth per agent (default: normal)
• --output — Output directory (overrides default)
• --output — Output directory (overrides $OBSIDIAN_VAULT)
• --no-obsidian — Skip Obsidian, save to ./research-output instead
• --fast — Quick overview mode: 2 agents, shallow depth, ~5 min turnaround

If no flags provided, the orchestrator automatically determines optimal angles and depth.

Output path resolution (in order of precedence):

1. --output flag
2. $OBSIDIAN_VAULT/Research/ environment variable
3. ./research-output/ (current directory fallback, same as --no-obsidian)

Step 1: Parse Input and Analyze Topic Complexity

Extract from $ARGUMENTS:

• Main topic: The core research subject
• Explicit angle count: From --angles flag (if provided)
• Depth: From --depth flag (default: auto-determined)
• Output directory: From --output flag (default: Obsidian vault)
• Language: Detect language of the user's topic input — ALL output will be in this language

Auto-Determine Research Scope

If the user did NOT specify --angles, analyze the topic to decide:

Topic complexity scoring:

| Factor | Low (1pt) | Medium (2pt) | High (3pt) | |--------|-----------|--------------|------------| | Breadth | Narrow/specific question | Multi-faceted topic | Entire field/industry | | Controversy | Consensus exists | Some debate | Highly contested | | Recency | Well-established | Evolving | Cutting-edge/breaking | | Interdisciplinarity | Single domain | 2-3 domains | Many domains intersect | | Stakeholders | Few | Several | Many competing interests |

Score → Agent count:

| Score | Default agents | --depth deep agents | |-------|---------------|---------------------| | 5-7 | 2 | 3 | | 8-10 | 3 | 4 | | 11-13 | 4 | 5 | | 14-15 | 4 | 6 |

Token rule: Default depth is always normal. --depth deep is the only way to unlock higher agent counts and word limits. Add --fast flag support: when --fast is set, force 2 agents + shallow depth regardless of complexity score.

Auto-determine depth:

• If topic is narrow/specific: deep (fewer angles, more depth each)
• If topic is broad/multi-domain: normal (more angles, balanced depth)
• If user asks for "quick overview" or similar: shallow

Determine Output Directory

Default behavior (Obsidian integration):

Unless --no-obsidian or --output is specified, save to Obsidian vault:

# Determine vault base path
if [[ -n "${OUTPUT_FLAG}" ]]; then
  VAULT_BASE="${OUTPUT_FLAG}"
elif [[ -n "${OBSIDIAN_VAULT}" ]]; then
  VAULT_BASE="${OBSIDIAN_VAULT}/Research"
else
  VAULT_BASE="$(pwd)/research-output"
fi

# Create dated topic folder: [YYYY-MM-DD] Topic Name
DATE=$(date +%Y-%m-%d)
# Sanitize topic name for folder: remove special chars, truncate to 60 chars
TOPIC_SLUG=$(echo "[MAIN_TOPIC]" | sed 's/[^a-zA-Z0-9ąćęłńóśźżĄĆĘŁŃÓŚŹŻ ]/-/g' | cut -c1-60)
OUTPUT_DIR="${VAULT_BASE}/${DATE} ${TOPIC_SLUG}"
mkdir -p "${OUTPUT_DIR}/findings"

If --no-obsidian is set:

OUTPUT_DIR="$(pwd)/research-output"
mkdir -p "${OUTPUT_DIR}/findings"

If --output is set, use that path directly.

Inform the user:

Deep Research: [TOPIC]

Complexity analysis:
- Breadth: [score] — [reason]
- Controversy: [score] — [reason]
- Recency: [score] — [reason]
- Interdisciplinarity: [score] — [reason]
- Stakeholders: [score] — [reason]
Total: [X]/15

Research plan: [N] parallel agents | depth: [level]
Output: [path]

Step 2: Design Research Angles

Think like a research director planning a comprehensive investigation. Your angle design determines the quality of the final report.

Angle Design Framework

For any topic, cover these dimensions (select relevant ones):

Core angles (almost always include):

• State of the Art: Current status, latest developments, key players
• Technical/Mechanistic: How it works, underlying principles, methodology
• Evidence & Data: Key studies, statistics, empirical findings

Contextual angles (include when relevant):

• Historical Context: How we got here, evolution, key milestones
• Economic/Market: Costs, market size, business models, ROI
• Regulatory/Legal: Laws, policies, compliance, governance
• Social/Ethical: Impact on people, ethical debates, equity concerns
• Competitive Landscape: Key players, alternatives, comparisons
• Challenges & Limitations: Known problems, criticisms, failure modes
• Future Outlook: Trends, predictions, emerging developments
• Expert Perspectives: What leading thinkers/practitioners say
• Case Studies: Real-world implementations, success/failure stories

Angle Quality Rules

Each angle MUST be:

• Distinct: Minimal overlap with other angles
• Specific: Clear enough that the agent knows exactly what to search for
• Searchable: The agent can find web sources for this
• Valuable: Contributes unique insight to the final report

Write Research Plan

Write to ${OUTPUT_DIR}/RESEARCH-PLAN.md:

# Research Plan: [Main Topic]
Date: [date] | Score: [X]/15 | Agents: [N] | Depth: [level]

## Angles
[For each angle:]
**[N]. [Title]** — [one sentence focus]
Questions: [Q1] / [Q2] / [Q3]
Output: findings/[slug].md

## Output
Report: ${OUTPUT_DIR}/REPORT.md

Show the research plan to the user briefly, then proceed immediately.

Step 3: Spawn Parallel Research Agents

CRITICAL: Spawn ALL agents in a SINGLE message with multiple Agent tool calls. This enables true parallel execution. Do NOT spawn them one by one.

Model assignment (non-negotiable):

• ALL research sub-agents → claude-haiku-4-5-20251001
• Synthesis agent (Step 5) → claude-sonnet-4-6

Do NOT use Sonnet for data collection agents. This preserves the weekly Sonnet quota.

For each angle, invoke the Agent tool. The prompt below is a TEMPLATE — adapt it per angle but ALWAYS include the full language/quality rules:

Agent(
  subagent_type="general-purpose",
  description="Research: [short angle title]",
  model="claude-haiku-4-5-20251001",
  run_in_background=true,
  prompt="
    You are a deep research agent. Your job is to thoroughly investigate one specific angle of a larger research topic, then write a well-structured, clearly written findings document.

    
    **Main Topic:** [main topic]
    **Your Angle:** [angle title]
    **Focus:** [angle focus description]
    **Key Questions:**
    - [question 1]
    - [question 2]
    - [question 3]

    **Expected sources:** [guidance on what to look for]

    **Depth:** [shallow|normal|deep]
    - shallow: 2 searches, 2-3 sources (max 2000 words/source), findings ~500-800 words
    - normal: 4 searches, 3-4 sources (max 2500 words/source), findings ~1000-1500 words
    - deep: 6 searches, 5-7 sources (max 3500 words/source), findings ~2000-3000 words

    **Output path:** ${OUTPUT_DIR}/findings/[angle-slug].md
    **Output language:** [DETECTED LANGUAGE — e.g., Polish / English]
    

    
    CRITICAL WRITING QUALITY REQUIREMENTS — follow these strictly:

    1. **Language:** Write ENTIRELY in [DETECTED LANGUAGE]. Use correct orthography, grammar, and diacritics.
       - For Polish: always use ą, ć, ę, ł, ń, ó, ś, ź, ż — NEVER write 'a' instead of 'ą', etc.
       - Double-check every word for spelling before writing the file.
    2. **Clarity:** Write for an intelligent reader who is NOT a domain expert. Explain technical terms on first use.
    3. **Substance:** Every finding needs 3-5 sentences of explanation minimum. Never just list a fact — explain WHY it matters and WHAT it means in context.
    4. **Data context:** Never drop a number without explaining its significance. Bad: 'Revenue was 500M PLN.' Good: 'Revenue reached 500M PLN, a 23% year-over-year increase that significantly outpaced the industry average of 8%, driven primarily by...'
    5. **Flow:** Use transitions between sections. Each paragraph should connect logically to the next.
    6. **No filler:** Every sentence must carry information. Delete vague phrases like 'it is worth noting that' or 'it should be mentioned that'.
    7. **Prose over bullets:** Use flowing paragraphs as the primary format. Reserve bullet lists for enumerating 4+ comparable items (e.g., list of companies, list of risk factors).
    8. **Bold key conclusions** so the document is scannable.
    9. **Tables** must have a 1-2 sentence interpretation/takeaway below them.
    

    
    1. Run WebSearch queries (include current year). Maximum [N] searches where:
       - shallow: 2 searches
       - normal: 4 searches
       - deep: 6 searches
       
    2. Use WebFetch ONLY on the top 3-5 results. When fetching:
       - Extract ONLY the main content body — skip nav, footer, sidebar, cookie banners, ads
       - Stop reading after 2500 words of relevant content (shallow/normal) or 3500 words (deep)
       - If the page is mostly boilerplate after 500 words, abandon it and try the next result
       - Prioritize 3 high-quality sources over 8 mediocre ones

    3. Cross-reference claims across multiple sources. Note agreements and disagreements.
    4. Organize findings into a coherent narrative — NOT a list of disconnected facts.
    5. Write the complete findings document to the output path using the Write tool.
    

    
    Write a markdown file with this structure:

    # [Angle Title]

    **Data badania:** [date]
    **Temat główny:** [main topic]
    **Perspektywa:** [angle focus]
    **Poziom pewności:** [HIGH/MEDIUM/LOW]
    **Źródła:** [number] sources consulted

    ## Podsumowanie

    [5-8 sentence executive summary of the most important findings from this angle. This should be a coherent paragraph, not bullets. A reader who reads ONLY this section should understand the key takeaways.]

    ## Szczegółowa analiza

    ### [Subtopic 1 Title]

    [3-5 paragraphs of detailed analysis. Include specific data, quotes, and source references. Explain the significance of each finding. Connect findings to each other and to the main topic.]

    **Kluczowy wniosek:** [one sentence bold takeaway]

    ### [Subtopic 2 Title]

    [Continue same pattern — substantial paragraphs, not just bullets]

    [Continue for 3-6 subtopics depending on depth]

    ## Dane i statystyki

    | [Metric] | [Value] | [Context/Comparison] | [Source] |
    |----------|---------|---------------------|----------|

    [1-2 sentence interpretation of what this data tells us]

    ## Perspektywy ekspertów

    [What do authoritative voices say? Include direct quotes where available, with attribution.]

    ## Luki informacyjne

    [What couldn't be determined? What needs deeper investigation? Be honest.]

    ## Źródła

    ### Źródła główne (HIGH confidence)
    1. [Author/Org] — "[Title]" — [Date] — [URL]

    ### Źródła uzupełniające (MEDIUM confidence)
    1. [Author/Org] — "[Title]" — [Date] — [URL]

    ### Źródła kontekstowe (LOW confidence)
    1. [Author/Org] — "[Title]" — [Date] — [URL]
    

    IMPORTANT REMINDERS:
    - Write the COMPLETE document — do not truncate or summarize at the end
    - Minimum word counts are REAL minimums, not targets — write more if the research supports it
    - Every factual claim MUST cite a source URL
    - Proofread for spelling and grammar before writing the file
    - Use the Write tool to save to the output path — this is critical

    FINAL INSTRUCTION — CRITICAL:
    After writing the findings file, respond with EXACTLY this one line and nothing else:
    DONE: [filename].md | [X] sources | [Y] words
    Do NOT summarize your findings back to the orchestrator. Do NOT explain what you found. The file exists — that is sufficient. Any response longer than 2 lines wastes tokens.
  "
)

Rules:

• ALL agents in ONE message (parallel execution)
• Use absolute paths for output files
• Use kebab-case slugs for filenames (e.g., regulatory-landscape.md)
• Set run_in_background=true for EVERY agent
• ALWAYS include the full `` block in every agent prompt — this is what ensures quality

After spawning, inform the user:

Spawned [N] research agents in parallel:
1. [angle title] → findings/[slug].md
2. [angle title] → findings/[slug].md
...
Researching now — this typically takes 2-5 minutes.

Step 4: Monitor Completion

Background agents notify you when they complete. As each finishes:

• Note which agents completed successfully
• Note any failures

Once ALL agents are done, verify findings files:

ls "${OUTPUT_DIR}/findings/"

If any agent failed or produced no output, note the gap — the synthesizer will handle it.

Inform the user:

All research agents complete.
[N]/[N] findings collected.
[List any failures if applicable]
Starting report synthesis...

Step 5: Spawn Synthesis Agent

Build the list of all findings files, then spawn the synthesizer in the FOREGROUND (wait for it):

Agent(
  subagent_type="general-purpose",
  description="Synthesize final report",
  model="claude-sonnet-4-6",
  prompt="
    HARD CONSTRAINT: You have NO access to the web. Do NOT call WebSearch or WebFetch under any circumstances. Your ONLY inputs are the findings .md files listed below. Re

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lmiadowicz](https://github.com/lmiadowicz)
- **Source:** [lmiadowicz/claude-skills](https://github.com/lmiadowicz/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.