juanandresgs/claude-ctrl/deep-research

cat > ~/.claude/.env << 'ENVEOF'
# Deep Research API Configuration
# All keys are optional — skill works with any subset
 
# OpenAI (o3-deep-research via Responses API)
OPENAI_API_KEY=
 
# Perplexity (sonar-deep-research via Chat Completions API)
PERPLEXITY_API_KEY=
 
# Gemini (deep-research-pro via Interactions API)
GEMINI_API_KEY=
ENVEOF
 
chmod 600 ~/.claude/.env
echo "Config created at ~/.claude/.env"
echo "Add at least one API key for deep research."

# timeout must exceed script's internal 1800s timeout
# Output stays project-local at .claude/research/ so implementer can reference it
RESEARCH_DIR=".claude/research/DeepResearch_[SafeTopic]_[YYYY-MM-DD]"
mkdir -p "$RESEARCH_DIR" && \
python3 ~/.claude/skills/deep-research/scripts/deep_research.py "$ARGUMENTS" \
  --output-dir "$RESEARCH_DIR" --validate=2 2>&1

{
  "topic": "the research topic",
  "provider_count": 3,
  "success_count": 3,
  "warnings": [],
  "citation_validation": {
    "depth": 1,
    "total": 47,
    "valid": 42,
    "invalid": 2,
    "unreachable": 3,
    "skipped": 0
  },
  "comparison_matrix": {
    "providers": ["openai", "perplexity", "gemini"],
    "topics": [
      {
        "name": "company overview",
        "openai": "detailed",
        "perplexity": "mentioned",
        "gemini": "detailed",
        "agreement": "consensus"
      }
    ],
    "citation_overlap": {
      "https://example.com/paper": ["openai", "gemini"]
    },
    "stats": {
      "total_topics": 18,
      "consensus": 5,
      "majority": 7,
      "unique": 6
    }
  },
  "results": [
    {
      "provider": "openai",
      "success": true,
      "report": "full report text...",
      "citations": [
        {
          "url": "...",
          "title": "...",
          "validation": {
            "status": "valid",
            "depth": 1,
            "details": "HTTP 200"
          }
        }
      ],
      "model": "o3-deep-research-2025-06-26",
      "elapsed_seconds": 145.3,
      "error": null
    },
    ...
  ]
}

# Deep Research Report: [Topic]
 
## Provider Status
| Provider | Status | Time | Notes |
|----------|--------|------|-------|
| OpenAI | OK | 145s | |
| Perplexity | OK | 89s | |
| Gemini | FAILED | 600s | HTTPError: timed out after 600s |
 
*(Always include this table. Green path: all OK. Failure path: makes problems immediately visible.)*
 
## Executive Summary
[3-5 sentence overview of the key findings across all models]
 
## Individual Model Reports
 
### OpenAI (o3-deep-research) — [elapsed]s
[Condensed key findings from OpenAI's report — preserve the important facts,
remove redundant prose. 200-400 words.]
 
### Perplexity (sonar-deep-research) — [elapsed]s
[Condensed key findings from Perplexity's report. 200-400 words.]
 
### Gemini (deep-research-pro) — [elapsed]s
[Condensed key findings from Gemini's report. 200-400 words.]
 
## Comparative Assessment
 
Tag each finding with its agreement level:
-`[consensus]` — All providers agree
-`[majority]` — 2+ providers agree
-`[contested]` — Providers disagree
-`[unique-<provider>]` — Single provider finding (e.g., `[unique-openai]`)
 
### Points of Agreement
[`[consensus]` findings — claims made by all providers. Highest confidence.]
 
### Points of Majority Agreement
[`[majority]` findings — claims made by 2+ but not all providers.]
 
### Points of Disagreement
[`[contested]` findings — claims where providers contradict each other. Note which model says what.]
 
### Unique Insights
[`[unique-<provider>]` findings — single-provider findings. Interesting but lower confidence.]
 
### Confidence Assessment
| Finding | OpenAI | Perplexity | Gemini | Confidence |
|---------|--------|------------|--------|------------|
| [key claim 1] | ✓ | ✓ | ✓ | High |
| [key claim 2] | ✓ | ✓ | — | Medium |
| [key claim 3] | — | — | ✓ | Low |
 
### Source Quality Comparison
| Provider | Citations | Report Length | Depth |
|----------|-----------|-------------|-------|
| OpenAI | [n] sources | [n] words | [assessment] |
| Perplexity | [n] sources | [n] words | [assessment] |
| Gemini | [n] sources | [n] words | [assessment] |
 
## References
 
**CRITICAL: The report must be verifiable.** Include a numbered references section at the end using citations from all providers. Every factual claim in the report should be traceable to a source.
 
Build the references list by:
1.Collecting all citation URLs from the `citations` arrays in the JSON results
2.Deduplicating by URL (multiple providers may cite the same source)
3.Numbering them sequentially
4.Using inline reference numbers `[1]`, `[2]` etc. throughout the report body to link claims to sources
 
Format:
[1] Title or description — URL
[2] Title or description — URL
...
 
If a provider (like Gemini) returns no structured citations, note that its claims are unsourced and lower confidence. Prefer citing claims that have URLs backing them.

## Topic Coverage Matrix
 
| Topic | OpenAI | Perplexity | Gemini | Agreement |
|-------|--------|------------|--------|-----------|
| company overview | Detailed | Mentioned | Detailed | consensus |
| apt group connections | Detailed | Detailed | Absent | majority |
| post-leak developments | Absent | Detailed | Absent | unique-perplexity |
 
**Stats:** 18 topics — 5 consensus, 7 majority, 6 unique
 
### Shared Citations (cited by 2+ providers)
-https://example.com/paper — openai, gemini

cat > .claude/.skill-result.md << 'SKILLEOF'
## Deep Research Result: [Topic]
 
**Status:** [n]/3 providers succeeded | [list any failures]
**Time:** [total elapsed]s
**Output:** .claude/research/DeepResearch_[Topic]_[Date]/report.md
 
### Key Findings (highest confidence)
1. [Finding supported by 2+ providers]
2. [Finding supported by 2+ providers]
3. [Additional key finding]
 
### Needs Attention
- [Any provider failures or gaps worth noting]
SKILLEOF

---
Deep Research complete — [n]/3 providers succeeded.
WARNING: [provider names] failed — [brief error reasons] (only include this line if any failed)
- Total research time: [sum of elapsed]s
- Report saved to: .claude/research/DeepResearch_[Topic]_[Date]/report.md
 
Want me to dig deeper into any specific finding?