monitoring

Investigation Monitoring

Manage persistent monitoring during and between Spotlight investigations. This skill defines the lifecycle for creating, checking, and ingesting monitoring results.

Conventions

• Case attribution: All scouts use the topic field set to spotlight:{project} (e.g., spotlight:chat-control-denmark)
• Scout naming: Human-readable, descriptive of the target (e.g., "EU Council Chat Control Page"). No prefix conventions.
• Auth: All API calls use env vars. Never hardcode keys.
• User gate: The orchestrator never creates scouts autonomously. All scout creation requires user approval.

---

The Monitoring Lifecycle

1. Recommend (Agents → findings.json)

During execution cycles, agents identify targets worth persistent monitoring. They record structured recommendations in monitoring_recommendations[] in data/findings.json. See references/recommendation-schema.md for the full schema.

Agents recommend when they observe:

• A page that updated during the investigation window
• A social account posting relevant content before press releases
• A news topic in a location that's underreported
• A government page that may publish updated documents

Agents do NOT create scouts. They only recommend.

2. Create (Orchestrator → coJournalist API)

Between investigation cycles, the orchestrator:

1. Reads monitoring_recommendations[] from data/findings.json
2. Presents recommendations to the user, ordered by priority
3. For each approved recommendation, creates a scout via the appropriate source API
4. Logs created scouts to data/monitoring.json

See references/cojournalist-api.md for API patterns.

3. Check (Orchestrator → preflight)

During preflight of subsequent /spotlight runs, the orchestrator:

1. Reads data/monitoring.json to find existing scouts for this case
2. Queries each monitoring source for new results (filtered by topic)
3. Presents a monitoring briefing to the user before the next cycle

Format:

"Monitoring check — your Page Scout on [target] has returned N new results since your last cycle:

• [date] Summary of result
• [date] Summary of result

These may be relevant to your investigation. Want to review before starting the next cycle?"

4. Ingest (Orchestrator → investigation context)

If the user wants to use monitoring results, the orchestrator folds relevant information units into the investigation context for the next cycle. The investigator receives them as additional context in the spawn prompt.

---

Monitoring Sources

See references/source-catalog.md for the full registry of monitoring sources and their capabilities.

Each source has:

• Scout types it supports
• Whether agents can recommend targets for it
• Whether it supports preflight checks
• Required env var for access

---

Data Files

data/monitoring.json

Case-level monitoring state. Created by the orchestrator when the first scout is approved.

{
  "topic": "spotlight:{project}",
  "scouts": [
    {
      "name": "Scout display name",
      "scout_type": "web|pulse|social|civic",
      "topic": "spotlight:{project}",
      "created_at": "ISO 8601",
      "source_recommendation": "M1",
      "source_cycle": 1
    }
  ],
  "checks": [
    {
      "checked_at": "ISO 8601",
      "cycle": 2,
      "units": [
        {
          "title": "Human-readable summary",
          "source_url": "https://...",
          "scout_name": "Scout display name",
          "created_at": "ISO 8601"
        }
      ]
    }
  ]
}

---

Reference Files

File	Contents
references/cojournalist-api.md	coJournalist V1 API curl patterns for scout CRUD and unit retrieval
references/source-catalog.md	Registry of all monitoring sources with capabilities and env vars
references/recommendation-schema.md	Schema for monitoring_recommendations[] in findings.json