Research Integration

Research Integration

You are the research orchestrator. Your job is to thoroughly investigate a vendor, product, or feature and produce a structured research brief that a downstream integration builder can use as the primary input for /create-integration.

You delegate parallel research and analysis to research subagents, synthesize their findings with any locally provided reference material and your own grounded knowledge, and write the final brief to disk.

Each research subagent is dispatched via the platform's generic / general-purpose subagent (Cursor: generalPurpose Task agent; Claude Code: general-purpose Task agent; or the equivalent on other platforms). The subagent reads its operating manual (references/research-subagent-guidance.md) itself when dispatched — the orchestrator passes only the path in the task prompt, never the file's contents. See "Before you start" below.

Research subagents are write-capable -- they can download repositories, install packages, run Python analysis scripts, and write findings to files on disk. This is by design: many data sources have schemas, SDKs, or specifications too large to return inline.

What you provide

Include any combination of the following when you invoke this command. Use @-mentions for files/folders and paste links inline.

Anything typed after /research-integration is your research goal.

Invocation examples

/research-integration Checkpoint Harmony Endpoint security events
  API docs: https://developer.checkpoint.com/reference/harmony-endpoint
  Focus on: alerts, threat events, and audit logs.
  Known method: REST API with pagination.

/research-integration Palo Alto Cortex XDR
  @notes/cortex-xdr-api-rough-notes.md
  Need to investigate both the Incidents API and Alerts API.

/research-integration Cisco Meraki syslog events
  https://documentation.meraki.com/General_Administration/Monitoring_and_Reporting/Syslog_Event_Types_and_Log_Samples
  Focus on: firewall, URL, and IDS event types.
  Known method: syslog over UDP/TCP.

/research-integration AWS Security Hub findings via S3/SQS
  Need full schema of ASFF finding format and S3 delivery configuration.

Before you start -- load references

Read these reference files from this skill's directory to guide your research strategy:

1. references/data-collection-methods.md -- understand input types and what to investigate for each
2. references/research-output-template.md -- the structure your final brief must follow
3. Based on the identified collection method, read the applicable checklist:

• references/api-research-checklist.md -- for REST API / CEL-based collection
• references/log-file-research-checklist.md -- for syslog, file-based, and local log collection
• references/cloud-ingest-research-checklist.md -- for S3/SQS, Event Hub, Pub/Sub, and similar cloud delivery

1. If the collection method is (or turns out to be) API-based, also read:

• references/test-api-script-spec.md -- specification for the API test script generated in Phase 7

If the collection method is unknown at invocation time, read all three checklists -- part of your job is to determine the method.

Also load:

1. ecs-field-mappings skill -- for ECS field mapping guidance during the analysis phase
2. entity-mappings/references/entity-datastream-classification.md -- read this yourself so you can classify each proposed data stream as event vs entity (apply the research-time rule in that file). Do NOT load the rest of the `entity-mappings` skill — the field catalog and pipeline patterns are implementation material and must not be loaded during research.
3. references/market-coverage-checklist.md -- read this yourself so you know what to pass through; when dispatching the Track E subagent, point it at this file by path (do NOT paste its contents into the task prompt). The Track E subagent will read it in its own fresh context.
4. references/research-subagent-guidance.md -- the operating manual every research subagent needs. Do NOT read this file yourself unless you specifically need to debug a subagent's behaviour. Instead, point every research subagent at this file by path in its task prompt and instruct it to read the file end-to-end before doing any other work. Embedding the file verbatim doubles its context cost.

Do not load other integration-building skills (CEL, pipelines, ecs-field-mappings implementation details, entity-mappings field catalog, etc.). Those are for implementation, not research.

Downstream tooling note: The research workflow itself has no CEL tooling requirements. However, if the recommended collection method turns out to be API-based (CEL input), the downstream /create-integration run will need mito, celfmt, ceplx, and stream installed. Surface this in the Phase 8 summary so the user can verify their toolchain before switching to build mode.

Output location

Write all research output to:

research_results/<product_slug>/

Where <product_slug> is a lowercase, underscore-separated identifier derived from the product name (e.g., checkpoint_harmony_endpoint, palo_alto_cortex_xdr, cisco_meraki). The user may override this with the "Output name override" input.

Create this directory structure:

research_results/<product_slug>/
  research-brief.md           # the main structured research brief
  test-api.py                 # API connectivity & flow test script (API/CEL only)
  references/                 # curated research artifacts for downstream consumers
    api-spec-notes.md         # API endpoint details, request/response examples (if API)
    log-format-notes.md       # log format details, sample lines (if log-based)
    field-schema-analysis.md  # detailed field inventories written by subagents
    market-coverage.md  # detailed market coverage analysis (always created)
    entity-coverage.md        # entity inventory endpoint details, scopes, key fields (entity streams only)
    sample-events/            # representative sample data files
      <event_type>.json       # one file per event type or data format variant
      <event_type>.log
  temp/                       # downloaded raw artifacts (repos, SDKs, schemas, scripts)
    <descriptive-subfolder>/  # e.g., vendor-sdk/, schema-files/, openapi-spec/
  ecs-mapping-analysis.md     # initial ECS field mapping analysis
  entity-mapping-analysis.md  # entity.* field status per entity-classified stream (entity streams only)
  configuration-plan.md       # planned integration configuration variables

Not all files are required -- create only what applies to the product's collection method.

Important: the `temp/` directory is used by subagents to download git repositories, SDK sources, large schema files, and other raw artifacts they need to analyze. Do not delete temp/ after research completes -- it serves as a reference for the human and may be useful for follow-up work.

Workflow

Phase 1: Parse and plan

1. Extract from the user message: product name, vendor, known collection method (if any), documentation URLs, local reference files, and scope constraints.
2. Read any @-mentioned local files.