geo-research

PHASE 0: QUERY REFINEMENT (Interactive)
├── 0.1 Parse geopolitical query
├── 0.2 Identify primary analysis type (conflict/sanctions/actors/narrative)
├── 0.3 Generate DRAFT research brief
├── 0.4 Present brief to user via AskUserQuestion
│   ├── "Is this the right analysis type?"
│   ├── "Are these dimensions correct?"
│   ├── "What temporal scope?"
│   └── "Any specific actors to focus on?"
├── 0.5 Refine brief based on feedback
└── 0.6 Confirm and proceed

PHASE 1: INITIALIZATION
├── 1.1 Finalize research brief with:
│   ├── Primary analysis type
│   ├── Geographic scope
│   ├── Temporal scope
│   ├── Key actors to track
│   └── Specific questions to answer
├── 1.2 Select specialist agents for deployment
└── 1.3 Generate initial speculative assessment

PHASE 2: DIFFUSION LOOP (max 3 iterations)
├── 2.1 SPAWN SPECIALIST WORKERS
│   ├── Deploy 2-4 specialist agents in PARALLEL
│   ├── Each agent receives focused brief + GDELT tool access
│   └── Wait for all to complete
│
├── 2.2 SYNTHESIZE
│   ├── Merge findings by dimension
│   ├── Cross-reference GDELT data with web sources
│   ├── Resolve contradictions (note if unresolvable)
│   └── Structure with proper citations
│
├── 2.3 GAP DETECTION
│   ├── Launch gap-detector-geo with: query, brief, draft
│   ├── Evaluate across weighted dimensions:
│   │   ├── Core (3x): Temporal, Actor, Data Source
│   │   ├── Supporting (2x): Quantification, Geographic, Perspective
│   │   └── Contextual (1x): Precedents, Expert Sources, Timeline
│   └── Decision: CONTINUE (gaps found) or COMPLETE
│
└── 2.4 ITERATE or EXIT
    ├── If CONTINUE: spawn workers for specific gaps
    └── If COMPLETE: proceed to final report

PHASE 3: FINAL REPORT
├── 3.1 Structure findings by analysis type
├── 3.2 Include all quantitative GDELT data
├── 3.3 Compile sources (GDELT queries + URLs)
└── 3.4 Add executive summary and confidence assessment

## Query Classification

**Your Query:** [Original query]

**Detected Type:** [Conflict / Sanctions / Actor / Narrative / Multi-Dimensional]

**Reasoning:** [Why this classification]

**Proposed Focus:**
- Geographic scope: [Countries/regions]
- Temporal scope: [Time period]
- Key actors: [Primary actors to track]

## Draft Research Brief

**Query:** [User's question]
**Analysis Type:** [Primary type]

**Core Dimensions:**
1. [Dimension 1] - [Why it matters for this analysis]
2. [Dimension 2] - [Why it matters]
3. [Dimension 3] - [Why it matters]

**Key Questions:**
- [Question 1] (Core)
- [Question 2] (Core)
- [Question 3] (Supporting)

**Specialist Agents to Deploy:**
1. [Agent 1] for [Focus area]
2. [Agent 2] for [Focus area]
3. [Agent 3] for [Focus area]

AskUserQuestion(
  questions: [
    {
      header: "Analysis Type",
      question: "Is this the right type of analysis for your question?",
      options: [
        { label: "Yes, proceed", description: "This analysis type fits my needs" },
        { label: "Focus on conflict", description: "I want conflict/escalation analysis" },
        { label: "Focus on sanctions", description: "I want economic sanctions analysis" },
        { label: "Focus on relationships", description: "I want actor network mapping" },
        { label: "Focus on coverage", description: "I want media/sentiment analysis" }
      ],
      multiSelect: false
    },
    {
      header: "Temporal Scope",
      question: "What time period should I focus on?",
      options: [
        { label: "Recent (30 days)", description: "Current developments and immediate context" },
        { label: "Medium (90 days)", description: "Recent quarter with trend context" },
        { label: "Extended (1 year)", description: "Full year for pattern analysis" },
        { label: "Historical (2+ years)", description: "Deep historical analysis" }
      ],
      multiSelect: false
    },
    {
      header: "Depth",
      question: "What level of depth do you need?",
      options: [
        { label: "Quick overview", description: "Key facts, 1 iteration, ~3 min" },
        { label: "Standard (Recommended)", description: "Thorough coverage, 2-3 iterations, ~7 min" },
        { label: "Exhaustive", description: "Maximum depth, all angles, ~12 min" }
      ],
      multiSelect: false
    }
  ]
)

Task(
  subagent_type: "geopolitical-research:conflict-analyst",
  prompt: "Analyze conflict dynamics for: [TOPIC]

Context: [Research brief excerpt]

Focus on:
- Active conflicts and CAMEO event patterns
- Goldstein scale trends (escalation/de-escalation)
- Key belligerents and their recent actions
- Third-party actor involvement

Use GDELT MCP tools: gdelt_events, gdelt_actors, gdelt_gkg
Return structured findings with GDELT data citations.",
  description: "Conflict analysis: [topic]"
)

Task(
  subagent_type: "geopolitical-research:sanctions-researcher",
  prompt: "Research sanctions for: [TOPIC]

Context: [Research brief excerpt]

Focus on:
- Active sanctions regimes and recent designations
- Economic impact indicators
- Enforcement actions and violations
- Evasion patterns detected

Use GDELT MCP tools: gdelt_gkg, gdelt_doc, gdelt_trends
Cross-reference with official sources (OFAC, EU).
Return findings with quantitative data.",
  description: "Sanctions research: [topic]"
)

Task(
  subagent_type: "geopolitical-research:actor-mapper",
  prompt: "Map actor relationships for: [TOPIC]

Context: [Research brief excerpt]

Focus on:
- Key actors and their types (state, non-state, IGO, etc.)
- Bilateral relationship patterns (Goldstein averages)
- Alliance structures and coalitions
- Relationship trends over time

Use GDELT MCP tools: gdelt_events, gdelt_actors
Return network analysis with relationship metrics.",
  description: "Actor mapping: [topic]"
)

Task(
  subagent_type: "geopolitical-research:sentiment-tracker",
  prompt: "Analyze media sentiment for: [TOPIC]

Context: [Research brief excerpt]

Focus on:
- Overall tone and polarity
- Sentiment by source country/region
- Narrative themes detected
- Media coverage disparities

Use GDELT MCP tools: gdelt_gkg, gdelt_doc
Return quantified sentiment analysis.",
  description: "Sentiment analysis: [topic]"
)

Task(
  subagent_type: "geopolitical-research:trend-analyst",
  prompt: "Analyze coverage trends for: [TOPIC]

Context: [Research brief excerpt]

Focus on:
- Coverage volume timeline
- Key inflection points
- Historical pattern comparison
- Early warning indicators

Use GDELT MCP tools: gdelt_trends, gdelt_events
Return trend analysis with forecasting.",
  description: "Trend analysis: [topic]"
)

## Research Draft: [Topic] (Iteration N)

### Executive Summary
[Key findings in 2-3 sentences]

### [Section by Analysis Type]

#### [Dimension 1]
[Synthesized content with GDELT data]

**GDELT Data:**
- Events: [Summary of event query results]
- Tone: [Sentiment metrics]
- Actors: [Relationship data]

**Sources:**
- [1] GDELT Events Query: [parameters]
- [2] [URL from worker]

[Repeat for each dimension]

### Current Gaps
[Note obvious gaps before formal detection]

Task(
  subagent_type: "geopolitical-research:gap-detector-geo",
  prompt: "Evaluate geopolitical research coverage:

ORIGINAL QUERY:
[Query]

RESEARCH BRIEF:
[Brief]

CURRENT FINDINGS:
[Draft]

ITERATION: [N]

Assess coverage across:
- Core dimensions (3x weight): Temporal, Actor, Data Source
- Supporting dimensions (2x weight): Quantification, Geographic, Perspective
- Contextual dimensions (1x weight): Precedents, Expert Sources, Timeline

Provide weighted coverage score and specific gaps for follow-up.",
  description: "Evaluate geopolitical coverage"
)

# Geopolitical Research Report: [Title]

**Analysis Type:** Conflict Analysis
**Date:** [Timestamp]
**Coverage Score:** [X%]
**Confidence Level:** [High/Medium/Low]

---

## Executive Summary

[3-5 bullet points of key findings]

---

## Conflict Overview

### Active Conflicts

| Conflict | CAMEO Codes | Avg Goldstein | Trend | Intensity |
|----------|-------------|---------------|-------|-----------|
| [Name] | [Codes] | [Score] | [Direction] | [Level] |

### Key Actors

**Belligerents:**
[Actor profiles with CAMEO codes and recent actions]

**Third-Party Actors:**
[Mediators, suppliers, allies with their roles]

---

## Escalation/De-escalation Assessment

**Indicators Observed:**
- [Indicator 1]: [Status]
- [Indicator 2]: [Status]

**Current Trajectory:** [Assessment]

---

## Key Events Timeline

| Date | Event | Actors | CAMEO | Goldstein | Source |
|------|-------|--------|-------|-----------|--------|
| [Date] | [Description] | [Actors] | [Code] | [Score] | [Source] |

---

## Quantitative Metrics

**GDELT Event Statistics:**
- Total events analyzed: [N]
- Date range: [Range]
- Goldstein scale distribution: [Stats]
- Quad class breakdown: [Stats]

---

## Analysis and Implications

[Cross-cutting insights, patterns, risks]

---

## Confidence Assessment

- **Data Quality:** [Assessment]
- **Coverage Completeness:** [Assessment]
- **Analytical Confidence:** [Assessment]

---

## Sources

**GDELT Queries:**
1. [Query description and parameters]
2. [Query description and parameters]

**News/Expert Sources:**
1. [Title](URL) - [What it contributed]
2. [Title](URL) - [What it contributed]

---
*Research conducted using GDELT geopolitical analysis with [N] specialist agents over [M] iterations.*

START: Parse user query
│
├── Contains: war, conflict, fighting, violence, military, attack,
│   escalation, ceasefire, troops, combat, weapons?
│   └── YES → CONFLICT ANALYSIS
│       ├── Primary: conflict-analyst
│       ├── Supporting: actor-mapper (for actor relationships)
│       └── GDELT focus: gdelt_events (CAMEO 14-20), gdelt_actors
│
├── Contains: sanctions, embargo, OFAC, trade restrictions, asset freeze,
│   designation, tariffs, export controls, enforcement?
│   └── YES → SANCTIONS RESEARCH
│       ├── Primary: sanctions-researcher
│       ├── Supporting: trend-analyst (for impact trends)
│       └── GDELT focus: gdelt_gkg (TAX_SANCTIONS), gdelt_doc
│
├── Contains: relationship, alliance, network, between X and Y,
│   bilateral, coalition, partnership, rivalry?
│   └── YES → ACTOR ANALYSIS
│       ├── Primary: actor-mapper
│       ├── Supporting: trend-analyst (for relationship trends)
│       └── GDELT focus: gdelt_actors, gdelt_events
│
├── Contains: media, coverage, sentiment, narrative, perception,
│   portrayal, tone, how is X reported, bias?
│   └── YES → NARRATIVE ANALYSIS
│       ├── Primary: sentiment-tracker
│       ├── Secondary: trend-analyst
│       └── GDELT focus: gdelt_gkg (tone), gdelt_trends
│
└── UNCLEAR or MULTI-DIMENSIONAL
    └── Ask user to clarify OR deploy multiple analysis types
        ├── Use AskUserQuestion to determine primary focus
        └── If truly multi-dimensional, run parallel workflows

AskUserQuestion(
  questions: [{
    header: "Clarify Focus",
    question: "You mentioned X. Should I...",
    options: [
      { label: "Add dedicated analysis", description: "Spawn specialist worker for X" },
      { label: "Include in current analysis", description: "Cover X within current scope" },
      { label: "Replace current focus", description: "Shift primary focus to X" }
    ],
    multiSelect: false
  }]
)