vincenthopf/my-claude-code/deep-research

Parallel Deep Research

Run deep research using the Parallel.ai Task API. Results are written directly to markdown files that can be used or referenced later.

Prerequisites

• PARALLEL_API_KEY must be available via either:
• Environment variable: export PARALLEL_API_KEY=your-key
• .env file in the skill directory (<skill-dir>/.env) containing PARALLEL_API_KEY=your-key
• Environment variable takes precedence over .env file

Usage

python3 <skill-dir>/scripts/research.py \
  --query "Your research question here" \
  --output ./research/<topic>.md \
  --processor pro \
  --no-basis  # optional: exclude Research Basis section

ALWAYS run research commands in the background so the user can continue working. Use run_in_background: true on the Bash tool call.

Workflow

1. User requests research on a topic
2. Refine the query using best practices (see Query Formulation section below)
3. Confirm all options with the user using AskUserQuestion tool before running. Ask in a single call:

• Query refinement: Show the expanded/refined query and let the user approve or edit
• Processor tier: Recommend appropriate tier (see Processor Tiers table)
• Fast mode: yes/no — appends -fast for 2-5x speed (may miss sources from last 2 days)
• Include Research Basis: yes (default) or no — includes citations, excerpts, confidence, and reasoning

1. Generate a descriptive filename from the topic (e.g., ai-chip-market-2025.md)
2. Run research.py in the background with confirmed options
3. Inform the user the task is running and where to find results
4. Do NOT read the output file unless the user explicitly asks — keep results out of context

Query Formulation Best Practices

The 4-Element Rule

For each query, specify:

1. Entity/Subject — What is being researched
2. Action/Objective — What information to gather (compare, analyze, list, evaluate)
3. Constraints — Timeframes, geography, source types, inclusion/exclusion criteria
4. Output Requirements — Desired sections, depth, citation needs

Specificity Guidelines

• Add 2-3 contextual keywords to narrow scope dramatically
• Declare the intended audience and purpose (e.g., "for technical decision-makers")
• Define ambiguous terms explicitly
• Specify what to include AND what to exclude
• Use time bounds ("2023-present", "last 12 months")

Query Structure Template

Research [TOPIC] for [AUDIENCE/PURPOSE].
 
Scope: [geography], [timeframe], [sector/domain]
Include: [source types, specific aspects to cover]
Exclude: [what to omit, source types to avoid]
Output: [sections needed, depth level, citation requirements]

Example Transformations

Prompt Patterns for Maximum Depth

Decomposition Pattern

Break complex topics into explicit sub-questions:

Research [MAIN TOPIC]. Address these sub-questions:
1. What is the current state of [aspect 1]?
2. What are the key players/stakeholders in [aspect 2]?
3. What evidence exists for [aspect 3]?
4. What are the gaps or contradictions in [aspect 4]?

Multi-Perspective Pattern

Force analysis from conflicting viewpoints:

Analyze [TOPIC] from multiple perspectives:
- Academic/research viewpoint
- Industry/practitioner viewpoint
- Regulatory/policy viewpoint
- Critic/skeptic viewpoint
Identify where these perspectives agree and conflict.

Comprehensive Coverage Pattern

Ensure exhaustive exploration:

Enumerate all facets of [TOPIC]:
- Key stakeholders and their interests
- Historical context and evolution
- Current state and recent developments
- Methods/approaches being used
- Challenges and limitations
- Future directions and predictions
- Related and adjacent topics

Planner-Executor Pattern

Request a research plan before execution:

Before researching [TOPIC]:
1. Outline the key sub-questions to investigate
2. Identify the types of sources needed
3. Note potential contradictions to watch for
4. Then execute the research plan systematically

Anti-Patterns to Avoid

Processor Tiers

Higher tiers (ultra2x, ultra4x, ultra8x) exist for extreme depth at higher cost.

Processor Selection Heuristics:

• Single-entity fact-finding → core or pro
• Comparative analysis (2-5 entities) → pro
• Market/landscape analysis → pro or ultra
• Comprehensive multi-stakeholder research → ultra

Output Format

The script writes a markdown file with:

• YAML frontmatter (query, processor, run_id, timestamps)
• Research findings organized by field
• Full citations with URLs, excerpts, reasoning, and confidence levels (unless --no-basis)

Exit Codes

Error Handling

If the script fails, check stderr output for the specific error. Common issues:

• Missing PARALLEL_API_KEY → remind user to set it
• 402 Payment Required → insufficient Parallel.ai balance
• 429 Rate Limited → wait and retry

Verification Reminder

Research outputs should be treated as first drafts. For critical use:

• Spot-check citations by visiting source URLs
• Verify that summaries accurately represent source content
• Check for recency — sources should match the specified timeframe
• Cross-reference key claims across multiple sources