@query-ai/digital-workers 1.0.0

package/skills/alert-investigation/SKILL.md

@@ -0,0 +1,838 @@
+---
+name: alert-investigation
+description: Use when investigating security alerts, triaging detection findings, or running the Incident Discovery workflow — master orchestrator that invokes specialized skills
+---
+
+# Alert Investigation
+
+## ABSOLUTE RULES — Read These First
+
+**1. NEVER use Bash, cat, python, jq, or any shell command to process data.** Not for MCP results. Not for saved files. Not for "just extracting a summary." NEVER. If results overflow to a file, your query was too broad — re-query with specific field selectors or tighter filters.
+
+**2. NEVER use `**` on broad queries.** The `**` wildcard returns entire OCSF events (millions of characters). Use specific field selectors: `detection_finding.message, detection_finding.severity_id, detection_finding.time, detection_finding.observables`. Use `**` only when scoped to a single host or single event type with a narrow filter.
+
+**3. ALWAYS validate before execute.** Every FSQL query goes through `Validate_FSQL_Query` before `Execute_FSQL_Query`. No exceptions.
+
+**4. ALWAYS pivot to telemetry.** For Standard and Deep tiers, you MUST query at least one telemetry event type (`process_activity`, `file_activity`, `network_activity`, `authentication`) in Gate 2. Detection findings are alerts, not evidence. If you reach Gate 3 having only queried `detection_finding`, you skipped the most important step. Go back.
+
+**5. ALWAYS save artifacts.** Write evidence files at every gate exit using the Write tool.
+
+**6. RESPECT THE QUERY BUDGET.** Every tier has a hard cap on `Execute_FSQL_Query` calls. When you hit the cap, stop gathering and work with what you have. Better to write a solid report on 12 queries than run 30 queries and take 26 minutes.
+
+| Tier | Execute Query Budget |
+|------|---------------------|
+| **Triage** | 5 max |
+| **Standard** | 15 max |
+| **Deep** | 25 max |
+
+If you approach the budget (2 queries remaining), stop enrichment and proceed to the next gate with your current evidence. Document "query budget reached — further enrichment deferred" in `queries.md`. The analyst can always say "go deeper" to upgrade the tier and unlock more queries.
+
+**7. LOG EVERY QUERY.** Every `Execute_FSQL_Query` call — whether it succeeds, fails, or returns empty — MUST be appended to `queries.md` with the query text, result count, and a 1-line summary. No undocumented queries. The audit trail is incomplete if even one query is missing.
+
+These rules are non-negotiable. If you find yourself reaching for cat, python, or `**` on a broad query, STOP and re-read this section.
+
+## Iron Law
+
+**EVERY INVESTIGATION FOLLOWS ITS TIER'S PROCESS. NO SKIPPING GATES WITHIN A TIER.**
+
+The process exists because shortcuts cause missed incidents. Tiers control scope — not rigor. Even Triage runs its gates properly.
+
+## Overview
+
+You are the master orchestrator for the Digital Workers Incident Discovery workflow. Before running gates, you select an **investigation tier** based on the analyst's prompt. The tier determines which gates run, how deep each gate goes, and what output is produced.
+
+## Step 0: Select Investigation Tier
+
+**Read the analyst's prompt and select a tier. Announce it and start immediately — do not wait for confirmation.**
+
+### Tier Definitions
+
+| Tier | Gates | Query Budget (hard cap) | Output | Time |
+|------|-------|------------------------|--------|------|
+| **Triage** | 1 → 2 (basic) | **5 max** | Inline summary table, no files | ~5 min |
+| **Standard** | 1 → 2 → 3 → 4 → 5 → 6 | **15 max** | Inline report + files (report.md, queries.md, iocs.md) | ~15 min |
+| **Deep** | 1 → 2 → 3 → 4 → 5 → 6 + specialists + senior review | **25 max** | Full report + files + review.md | ~25 min |
+
+### Tier Selection Rules
+
+**Parse the prompt for these signals:**
+
+| Signal | Tier | Examples |
+|--------|------|---------|
+| Questions, checks, scans — "any", "what's", "show me", "check for", "are there" | **Triage** | "Any suspicious PowerShell in the last 12 hours?", "What alerts fired overnight?", "Check for lateral movement", "Show me what's going on" |
+| Action verbs — "investigate", "look into", "triage", unqualified requests | **Standard** | "Investigate the unfamiliar sign-in alerts", "Look into this hash", "Triage the new HIGH alerts" |
+| Explicit depth — "full", "deep", "thorough", "complete", incident language | **Deep** | "Full investigation on these PowerShell findings", "Deep dive on BD-3263", "This looks like an incident — investigate everything" |
+
+**When ambiguous, default to the lighter tier.** Upgrading after seeing results costs 2-3 minutes. Starting Deep when the analyst wanted Triage wastes 25+ minutes.
+
+**Announce format — one line, then start immediately:**
+> "**Triage** — PowerShell findings, last 12 hours."
+
+> "**Standard investigation** — unfamiliar sign-in alerts, 24h."
+
+> "**Deep investigation** — full analysis of lateral movement indicators."
+
+### What Each Tier Runs
+
+**Triage:**
+- Gate 1: Pull alerts, classify, extract IOCs
+- Gate 2 (basic): Layer 1a discovery scans only — no per-host deep dives, no telemetry pivots, no threat intel, no evidence quality checker
+- Output: Inline summary table with alert list, severity, hosts, IOCs, event types hit
+- No file artifacts — triage is ephemeral
+- If results look concerning, end with: "Found [N] indicators that warrant closer examination. Say 'investigate' or 'go deeper' to run a Standard/Deep investigation."
+
+**Standard:**
+- All 6 gates
+- Gate 2: Full enrichment — Layer 1a/1b, telemetry pivots, per-host deep dives, threat intel
+- Gate 3: Severity scoring (AUTO-CLOSE / STANDARD / DEEP routing still applies within Standard tier)
+- Gate 4: Specialists only if severity routes to DEEP
+- Gate 6: Report + files, NO senior analyst review (unless analyst requests it)
+
+**Deep:**
+- All 6 gates at maximum depth
+- Gate 2: Full enrichment + extended lookback (7d default instead of 24h)
+- Gate 4: Always invoke specialists based on alert type
+- Gate 6: Full report + files + mandatory senior analyst review
+- Cross-reference with prior investigations in `docs/investigations/`
+
+### Tier Upgrades
+
+Tiers upgrade but never downgrade mid-investigation.
+
+**Auto-upgrade triggers (Triage → Standard):**
+- Any alert is CRITICAL or FATAL severity
+- IOC appears in 3+ event types (broad footprint)
+- IOC matches a prior investigation's IOCs
+
+When auto-upgrading, do NOT stop to ask. Announce and continue:
+> "Upgrading to **Standard** — CRITICAL severity indicators found on 3 hosts."
+
+**Analyst-driven upgrades:**
+- "Go deeper" / "full investigation" → upgrade to next tier
+- "Just triage" / "quick look only" → stays at current tier even if triggers fire
+- "Standard is fine" → caps at Standard
+
+The upgrade reuses all work already done. Gate 1 and Gate 2 (basic) artifacts from Triage feed directly into Standard's Gate 2 — no repeated queries.
+
+## The Incident Discovery Workflow
+
+```
+STEP 0: SELECT TIER (from analyst prompt)
+  │ Triage / Standard / Deep
+  │ Announce and start immediately
+  ▼
+Gate 1: ALERTS INTAKE (ALL TIERS)
+  │ Invoke: digital-workers:alert-classifier
+  │ Invoke: digital-workers:fsql-expert (pull alerts)
+  ▼
+Gate 2: GATHER INFORMATION
+  │ TRIAGE: Layer 1a discovery scans only → present summary → STOP
+  │ STANDARD/DEEP: Full enrichment (Layer 1a/1b, telemetry pivots,
+  │   per-host deep dives, threat intel, evidence quality checker)
+  ▼
+Gate 3: ANALYZE SITUATION (STANDARD + DEEP only)
+  │ Invoke: digital-workers:severity-scorer
+  │ Invoke: digital-workers:evidence-quality-checker (analytical reasoning)
+  │ Route to depth: AUTO-CLOSE / STANDARD / DEEP
+  ▼
+Gate 4: DECIDE & ACT (STANDARD + DEEP only)
+  │ STANDARD: Specialists only if severity routes to DEEP
+  │ DEEP: Always invoke specialists based on alert type
+  │ Assign disposition: Critical Threat / Policy Violation / False Positive / Benign
+  ▼
+Gate 5: BUILD & PRIORITIZE CASE (STANDARD + DEEP only)
+  │ Assemble evidence package
+  │ Prioritize relative to other active investigations
+  ▼
+Gate 6: INCIDENT NOTIFICATION (STANDARD + DEEP only)
+  │ Invoke: digital-workers:report-writer
+  │ DEEP only: invoke digital-workers:senior-analyst-review
+  │   (review MUST complete before presenting to analyst)
+  │ If INCIDENT CRITERIA MET: recommend escalation to Incident Response track
+  │ Present to analyst
+  ▼
+COMPLETE
+```
+
+## Investigation Artifacts
+
+Artifacts depend on the investigation tier:
+
+| Tier | Files | Directory |
+|------|-------|-----------|
+| **Triage** | No files — results presented inline only | No directory created |
+| **Standard** | `report.md`, `queries.md`, `iocs.md` | `docs/investigations/YYYY-MM-DD-<brief-description>/` |
+| **Deep** | `report.md`, `queries.md`, `iocs.md`, `review.md` | `docs/investigations/YYYY-MM-DD-<brief-description>/` |
+
+**For Standard and Deep tiers:**
+
+Create the investigation directory at the start of Gate 1. **Use the Write tool** (never Bash/echo) to save artifacts. Write markdown, not JSON.
+
+**The `queries.md` log is mandatory.** After every FSQL query execution, append the query text, result count, and a 1-2 line summary. This is the audit trail.
+
+**The `iocs.md` list is mandatory.** After every IOC extraction, append the IOC with type, source, and reputation (if known).
+
+**The `review.md` file is written by the senior analyst review** (Deep tier only, or when manually requested).
+
+---
+
+## Gate 1: Alerts Intake
+
+### Entry: New alerts exist or user requests investigation
+
+**Org-policy check:** If an org-policy skill is loaded, read its Alert Scope section for severity filter, time range, and connector scope. Adjust the intake query accordingly.
+
+**Step 1: Pull alerts from the mesh**
+
+Invoke `digital-workers:fsql-expert` to query for new alerts. **Use this exact query** (adjust time range if user requests, but DO NOT change the field selectors to `**`):
+
+```
+QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id, detection_finding.time, detection_finding.observables, detection_finding.attacks
+WITH detection_finding.severity_id IN HIGH, CRITICAL, FATAL AND detection_finding.status_id = NEW AFTER 24h
+```
+
+**The `status_id = NEW` filter is critical.** Without it, you get hundreds of alerts (including already-resolved ones) and the investigation drowns in noise. With it, you get the actionable set — typically 5-15 alerts. This is the single biggest factor in investigation quality.
+
+**DO NOT use `detection_finding.**` — it returns millions of characters and will overflow.** The fields above are all you need for triage. Additional fields can be queried in follow-up queries during Gate 2 enrichment.
+
+**Step 1.5: Extract IOCs — max 2 additional queries**
+
+If the intake query returned populated `observables` and `attacks` fields, extract IOCs directly. You're done — skip to Step 2.
+
+If `observables` and `attacks` are empty (skeleton-mapped alerts), run ONE `raw_data` query per distinct alert type to extract IOCs:
+
+```
+QUERY detection_finding.message, detection_finding.time, detection_finding.raw_data
+WITH detection_finding.message = '<alert_message>' AND detection_finding.status_id = NEW AFTER 24h
+```
+
+**Gate 1 IOC extraction is capped at 2 additional queries (1 per alert type).** If raw_data is also empty, document "skeleton-mapped — no IOC data available" and move on. The IOCs will come from Layer 1a discovery scans in Gate 2 instead.
+
+**DO NOT probe multiple field paths** (actor.user.name, finding_info, evidences, unmapped, resources) trying to find IOC data. This is the #1 source of query bloat — one investigation burned 12 queries in Gate 1 probing fields that don't exist. If the intake query + one raw_data query don't yield IOCs, the data isn't there.
+
+**Step 2: Deduplicate and filter**
+
+Review returned alerts. Group alerts that:
+- Share the same IOCs (same IP, same user, same hash)
+- Fired within minutes of each other from different tools
+- Describe the same underlying event from different perspectives
+
+Treat grouped alerts as a single investigation.
+
+**Filter profile-known noise:** If the environment profile is loaded, check each alert message against `known_false_positives` and `systemic_patterns`:
+- **`known_false_positives`** with `last_verified` < 7 days ago → auto-close as False Positive, log in queries.md: "Auto-closed per profile (verified YYYY-MM-DD, N samples)"
+- **`systemic_patterns`** → fast-track through investigation (skip per-host deep dives, skip telemetry pivots, skip threat intel). Still include in the report with disposition and profile citation.
+- **`infrastructure_noise`** entries → auto-close at Gate 1, no further investigation. Log: "Filtered per profile — infrastructure noise (verified YYYY-MM-DD)"
+
+This filtering happens BEFORE Gate 2 enrichment. Queries saved here are the highest-value profile optimization.
+
+**Step 3: Classify each alert**
+
+Invoke `digital-workers:alert-classifier` for each unique alert/group:
+- OCSF category
+- MITRE ATT&CK technique
+- Alert type (Identity/Network/Endpoint/etc.)
+- Initial IOC extraction
+
+**Gate 1 Exit — Save artifacts (Standard + Deep only):**
+1. Create the investigation directory: `docs/investigations/YYYY-MM-DD-<brief-description>/`
+2. Append to `queries.md` — the intake query with result count
+3. Write initial `iocs.md` — IOC list with type and source alert
+
+(Triage tier: no files — proceed directly to Gate 2 basic.)
+
+**Gate 1 Exit Criteria:** All alerts classified, deduplicated, IOCs extracted. **Continue immediately to Gate 2.**
+
+---
+
+## Gate 2: Gather Information
+
+### Entry: Alerts classified with initial IOCs
+
+**Step 0: Read environment profile and connector registry.**
+
+Before authoring ANY enrichment queries (including Triage tier):
+
+1. Call `FSQL_Connectors` to get the current connector landscape.
+2. Read `digital-workers/learned/environment-profile.json` if it exists.
+3. Cross-reference: for each event type needed in this investigation, check which connectors produce it and what the profile says about each.
+4. Apply the behavioral rules:
+   - **Skip** queries where ALL connectors for an event type are profiled as `unpopulated` / `no_data` (cite profile as source, document as known gap with last_verified date)
+   - **Probe** event types where SOME connectors are `untested` — try one targeted `FROM <connector_id>` query before declaring a gap
+   - **Skip re-verification** for `known_false_positives` entries verified < 7 days ago (cite profile: message, last_verified, sample_size)
+   - **Fast-track** `systemic_patterns` entries — run minimal enrichment (1 discovery scan to confirm pattern persists), then proceed directly to Gate 4 with profile-cited disposition
+   - **Apply** `query_performance` hints (batch size limits, known overflow patterns, %ip single-query rule)
+   - **Use workarounds** from `field_population` entries (e.g., `%ip` instead of `device.hostname`)
+5. Pass the profile context to fsql-expert with each query request so it can apply connector-specific knowledge.
+
+If the profile doesn't exist, skip this step and proceed normally. The investigation will create one.
+
+### Triage Tier: Basic Enrichment Only
+
+If the tier is **Triage**, follow this exact query sequence and then present the summary. **Target: 5 queries maximum.**
+
+**Triage Query Sequence:**
+
+1. **Query 1 — Severity-filtered intake** (already done in Gate 1):
+   ```
+   QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id,
+         detection_finding.time, detection_finding.observables, detection_finding.attacks
+   WITH detection_finding.severity_id IN HIGH, CRITICAL, FATAL AND detection_finding.status_id = NEW AFTER 24h
+   ```
+
+2. **Query 2 — Full landscape scan** (ALL new alerts, no severity filter):
+   ```
+   QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id,
+         detection_finding.time
+   WITH detection_finding.status_id = NEW AFTER 24h
+   ```
+   This reveals the complete alert picture — MEDIUM and LOW alerts often form patterns (persistence + execution + discovery clusters) that matter more than individual HIGH alerts.
+
+3. **Queries 3-5 — Layer 1a discovery scans** on the top 2-3 IOCs extracted from Gate 1:
+   ```
+   QUERY *.message, *.time WITH %hash = '<ioc>' AFTER 7d
+   QUERY *.message, *.time WITH %ip = '<ioc>' AFTER 24h
+   ```
+
+4. **Query 6 (optional) — SUMMARIZE for triage distribution** when Layer 1a discovery shows high volume:
+   ```
+   -- If Layer 1a shows 50+ detection_finding hits, get the distribution instead of reading each one
+   SUMMARIZE COUNT detection_finding.message GROUP BY detection_finding.message, detection_finding.severity_id, detection_finding.status_id
+   WITH detection_finding.severity_id IN HIGH, CRITICAL AFTER 24h
+   ```
+   This replaces manually counting alert types from QUERY results. Use when Layer 1a results suggest dozens of alerts across multiple types.
+
+   > **Constraints:** SUMMARIZE has known execution limits — `status_id` filtering fails on detection_finding (use GROUP BY instead), `FROM` not supported, high-cardinality GROUP BY can overflow. If SUMMARIZE returns empty, fall back to QUERY. See fsql-expert Layer 1c for workarounds and check `summarize_support` in the environment profile.
+
+**Dead-end rule: If IOC fields come back empty on an alert type (e.g., observables are null, actor fields are null), do NOT retry with different field paths.** Note it as a data gap (e.g., "skeleton-mapped alerts — no IOC data available") and move on to the next query. Spending multiple queries probing empty fields is the #1 way Triage runs over budget.
+
+**After these queries, present the Triage Output and stop.** Do not run Layer 1b, telemetry pivots, per-host deep dives, threat intel, authentication queries, or evidence quality checks. Those are Standard tier.
+
+**Triage Output:**
+
+```
+TRIAGE SUMMARY — [date] — [description]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Alerts: [N] total ([N] CRITICAL, [N] HIGH, [N] MEDIUM, [N] LOW)
+
+HIGH/CRITICAL:
+  [table: alert name, count, hosts, key IOCs]
+
+MEDIUM (summarized):
+  [table: alert name, count, MITRE mapping if obvious]
+
+LOW (summarized):
+  [one-line summary]
+
+Data Gaps:
+  [any skeleton-mapped alerts, empty IOC fields, etc.]
+
+Key Observations:
+  - [2-4 bullet points: patterns, clusters, concerns]
+
+Upgrade? Say "investigate" for Standard or "deep dive" for Deep.
+```
+
+**Check auto-upgrade triggers before presenting.** If any trigger fires (CRITICAL/FATAL alerts, IOC in 3+ event types, prior investigation match), auto-upgrade to Standard — announce and continue without stopping.
+
+**If no auto-upgrade triggers fire, present the summary and STOP.** The investigation is complete for Triage tier.
+
+---
+
+### Standard + Deep Tiers: Full Enrichment
+
+**Step 1: Enrich IOCs**
+
+For each IOC extracted in Gate 1, invoke `digital-workers:fsql-expert`. Use a **layered query approach** — broad-but-lightweight first, then targeted deep dives.
+
+**Layer 1a: Discovery scan (always start here)**
+
+Search IOCs across the entire mesh using `*.message, *.time`. This returns one lightweight row per matching event with the `__event` field showing which event type it came from — without overflowing.
+
+**BATCH same-type IOCs into single queries using `IN`.** This is the single biggest efficiency win — 5 individual queries become 1:
+
+```
+-- WRONG: 5 separate queries for 5 IPs (wastes 4 queries from budget)
+QUERY *.message, *.time WITH %ip = '172.16.16.70' AFTER 7d
+QUERY *.message, *.time WITH %ip = '172.16.16.58' AFTER 7d
+QUERY *.message, *.time WITH %ip = '172.16.16.43' AFTER 7d
+...
+
+-- RIGHT: 1 query for all IPs
+QUERY *.message, *.time WITH %ip IN '172.16.16.70', '172.16.16.58', '172.16.16.43', '172.16.16.94', '172.16.16.13' AFTER 7d
+
+-- RIGHT: 1 query for all usernames
+QUERY *.message, *.time WITH %username IN 'jacob.mason', 'edward.holmes', 'patricia.porter' AFTER 7d
+
+-- RIGHT: 1 query for all hashes
+QUERY *.message, *.time WITH %hash IN 'abc123', 'def456' AFTER 7d
+```
+
+**One Layer 1a query per IOC type.** If Gate 1 extracted 5 IPs, 3 usernames, and 2 hashes, that's 3 discovery queries (one per type), not 10.
+
+Read the `__event` field in results to discover all event types where the IOCs appear (e.g., `detection_finding`, `email_activity`, `osint_inventory_info`, `process_activity`). This is how you find event types you wouldn't have thought to query.
+
+**MANDATORY: Log every event type seen in `__event` results.** After each Layer 1a scan, note in `queries.md` which event types appeared. If an event type appears that isn't followed up with a Layer 1b query, document why (e.g., "email_activity: 0 hits" or "email_activity: 12 hits — followed up in Query N" or "osint_inventory_info: skipped — inventory data, not actionable").
+
+**NEVER use bare `QUERY %hash = 'x'` or `QUERY ** WITH %hash = 'x'` — these return full OCSF events and will overflow.**
+
+**Run independent queries concurrently.** These can always run in parallel:
+- Layer 1a discovery scans for different IOC types
+- Per-host deep dives on different hosts
+- Threat intel enrichment alongside specialist investigation queries
+
+**Layer 1b: Targeted detail (narrow, specific fields)**
+
+Based on Layer 1a results, query specific event types with field selectors for the details you need. Run `Search_FSQL_SCHEMA` first if you haven't queried this event type before:
+
+```
+-- Detection findings for an IOC (always include status_id)
+QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id,
+      detection_finding.time, detection_finding.observables, detection_finding.attacks
+WITH %ip = '<ioc>' AND detection_finding.status_id = NEW AFTER 24h
+
+-- Email activity (when Layer 1a shows email_activity hits)
+QUERY email_activity.message, email_activity.time, email_activity.actor.user.email_addr,
+      email_activity.email.subject
+WITH %hash = '<ioc>' AFTER 7d
+
+-- Process activity for a specific host (when Layer 1a shows process events)
+QUERY process_activity.message, process_activity.time, process_activity.device.hostname,
+      process_activity.process.cmd_line
+WITH process_activity.device.hostname = '<hostname>' AFTER 24h
+```
+
+**Layer 1c: Aggregation (when you need counts, not individual events)**
+
+After Layer 1a/1b, use SUMMARIZE when you need distributions rather than reading individual events:
+
+```
+-- Scope assessment: how many hosts are affected? (GROUP BY status_id to filter in results)
+SUMMARIZE COUNT detection_finding.device.hostname
+GROUP BY detection_finding.device.hostname, detection_finding.status_id
+WITH detection_finding.severity_id IN HIGH, CRITICAL AFTER 24h
+
+-- Status distribution on expanded lookback (separates active from resolved)
+SUMMARIZE COUNT detection_finding.status_id GROUP BY detection_finding.status_id
+WITH detection_finding.message = '<alert_name>' AFTER 7d
+
+-- Per-host alert count (prioritize deep dives)
+SUMMARIZE COUNT detection_finding.message GROUP BY detection_finding.device.hostname, detection_finding.status_id
+AFTER 7d
+```
+
+Use SUMMARIZE when you catch yourself manually counting results from a QUERY. If you need individual events (for IOC extraction, timeline reconstruction, raw_data), stay with QUERY.
+
+> **Constraints:** SUMMARIZE has known execution limits — `status_id` filtering fails on detection_finding (use GROUP BY instead), `FROM` not supported, high-cardinality GROUP BY can overflow. If SUMMARIZE returns empty, fall back to QUERY. See fsql-expert Layer 1c for workarounds and check `summarize_support` in the environment profile.
+
+**Layer 2: Category with key fields**
+
+When investigating a class of activity rather than a single IOC:
+
+```
+QUERY #network.src_endpoint.ip, #network.dst_endpoint.ip, #network.message, #network.time
+WITH #network.src_endpoint.ip = '<ip>' AFTER 48h
+```
+
+**Layer 3: Full event (rare, scoped)**
+
+Use `**` only when scoped to a single host AND single event type AND narrow time window:
+
+```
+QUERY process_activity.** WITH process_activity.device.hostname = 'BD-2578' AFTER 24h
+```
+
+**Never use `**` on broad observable searches.** If a query result overflows to a file, DO NOT read the file — re-query with specific field selectors or tighter filters.
+
+**Step 1.5: Pivot from findings to telemetry (MANDATORY — Gate 2 cannot exit without this)**
+
+**THIS IS THE MOST COMMONLY SKIPPED STEP. DO NOT SKIP IT.** Every investigation that skipped this step produced a shallow report. Every investigation that ran it found critical evidence (command lines, login patterns, network flows) that detection findings alone did not reveal.
+
+**Do not stay in `detection_finding` for the entire investigation.** Detection findings tell you what an alert fired on. Telemetry event types (`process_activity`, `file_activity`, `authentication`, `network_activity`, etc.) tell you what actually happened. You need both.
+
+After Layer 1a/1b discovery, pivot to the underlying telemetry based on the alert type:
+
+| Alert Type | Query These Event Types |
+|------------|------------------------|
+| Process/script execution | `process_activity` — command lines, parent processes, execution chains |
+| Malware/file-based | `file_activity` — file creation, drops, staging |
+| C2/lateral movement | `network_activity`, `dns_activity`, `http_activity` — traffic flows, DNS, HTTP |
+| Identity/auth anomaly | `authentication` — login patterns, source IPs, failures |
+| Phishing/email | `email_activity` — delivery chain, recipients, attachments |
+| Cloud/API abuse | `api_activity` — API calls, callers, sources |
+
+See the **"Event-Type Query Patterns by Investigation Need"** section in `fsql-reference.md` for exact queries for each event type.
+
+Example pivot for a PowerShell alert:
+```
+-- You found: detection_finding about "powershell.exe fileless script" on BD-3263
+-- PIVOT to process_activity:
+QUERY process_activity.message, process_activity.time,
+      process_activity.process.name, process_activity.process.cmd_line,
+      process_activity.actor.process.name, process_activity.device.hostname
+WITH process_activity.device.hostname = 'BD-3263'
+AND %process_name = 'powershell.exe' AFTER 7d
+```
+
+This tells you what the PowerShell process actually did (command lines, parent processes) — not just that an alert fired.
+
+**Step 1.6: Per-host deep dives (REQUIRED for priority hosts)**
+
+After Layers 1-3 identify the most suspicious hosts, run a per-host deep dive. **Cap the number of hosts by tier:**
+
+| Tier | Max Priority Hosts |
+|------|--------------------|
+| **Standard** | 3 hosts |
+| **Deep** | 5 hosts |
+
+Select hosts with the highest severity alerts, most diverse alert types, or most IOC overlap. If all hosts show the same pattern (e.g., same alert type, same subnet), deep-dive 2 and note "remaining N hosts show identical pattern — sampled 2."
+
+For each priority host:
+
+```
+-- For each priority host, get ALL alerts including status_id to distinguish active vs. resolved
+QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id, detection_finding.device.hostname
+WITH detection_finding.device.hostname = '<hostname>' AFTER 7d
+
+-- Get device owner context
+QUERY detection_finding.device.hostname, detection_finding.device.ip, detection_finding.device.os.name,
+      detection_finding.device.owner.ldap_person.given_name,
+      detection_finding.device.owner.ldap_person.surname,
+      detection_finding.device.owner.ldap_person.job_title, detection_finding.message
+WITH detection_finding.device.hostname = '<hostname>' AFTER 24h
+```
+
+**CRITICAL: Always include `status_id` in deep dive queries.** When expanding the time range beyond 24h, you will pull in historical alerts. You MUST check `status_id` to distinguish between:
+- `NEW` — unresolved, actionable alerts (these matter)
+- `RESOLVED` with `status_detail = "Benign"` — already investigated and closed as false positives (do NOT treat these as active threats)
+- `null` — status unknown, treat with caution
+
+**Building an investigation narrative on RESOLVED/Benign alerts is the #1 way to produce a false escalation.** The senior analyst review will catch this, but you should catch it first.
+
+This is where critical findings emerge — the first two successful investigations found full kill chains, multi-day persistence, and multi-malware compromise because they deep-dived each host. Skipping this step produces shallow investigations.
+
+**Step 2: Threat intelligence**
+
+If IOCs include IPs, hashes, or domains, invoke `digital-workers:threat-intel-enricher` for reputation and campaign correlation.
+
+**Step 3: Populate the Five W's**
+
+From enrichment results, begin answering:
+- **Who**: Which users, accounts, or actors are involved?
+- **What**: What exactly happened? What actions were taken?
+- **When**: What's the timeline? When did it start?
+- **Where**: Which systems, IPs, networks, locations?
+- **Why**: Initial assessment — attack, mistake, policy violation, automation?
+
+**Gate 2 Exit — Save artifacts:**
+1. Append to `queries.md` — all enrichment queries with result counts and key findings
+2. Append to `iocs.md` — any new IOCs discovered with type, source, and reputation
+
+**Step 4: Evidence quality check — data quality**
+
+Invoke `digital-workers:evidence-quality-checker` (Gate 2 pass). Append the check results (PASS/FAIL per check) to `queries.md` so the audit trail shows the quality gate ran. If any check fails, fix before proceeding to Gate 3. **Once all checks pass (or failures are fixed), continue immediately to Gate 3 — do not stop or wait for user input.**
+
+**Gate 2 Exit Criteria (ALL must be true before proceeding to Gate 3):**
+1. IOCs enriched via Layer 1a/1b discovery
+2. Per-host deep dives completed on priority hosts
+3. **At least one telemetry pivot query executed** (process_activity, file_activity, network_activity, or authentication) — if you have not queried any telemetry event type, STOP and run Step 1.5 now
+4. Five W's populated (at least partially)
+5. Threat intel gathered
+6. Evidence quality verified
+
+---
+
+## Gate 3: Analyze Situation (Standard + Deep only)
+
+### Entry: Enrichment complete
+
+**Org-policy check:** If an org-policy skill is loaded, pass its Severity Weights and Crown Jewels sections to the severity-scorer. These override the default weights, thresholds, and asset criticality assignments.
+
+**Step 1: Score severity**
+
+Invoke `digital-workers:severity-scorer` with all gathered context:
+- Alert severity (from source)
+- Asset criticality (inferred from enrichment)
+- Business impact (potential)
+- Confidence (based on evidence quality)
+- Threat context (from threat intel)
+
+**Step 2: Route to depth**
+
+Based on composite score and override rules:
+
+| Depth | Next Action |
+|-------|------------|
+| **AUTO-CLOSE** | Skip to Gate 4 with disposition: False Positive or Benign Activity |
+| **STANDARD** | Proceed to Gate 4 with current evidence (no deep investigation) |
+| **DEEP** | Invoke specialist investigators in Gate 4 before disposition |
+
+**Step 3: Evidence quality check — analytical reasoning**
+
+Invoke `digital-workers:evidence-quality-checker` (Gate 3 pass). Append the check results to `queries.md`. If any check fails, fix before proceeding to Gate 4. **Once all checks pass (or failures are fixed), continue immediately to Gate 4 — do not stop or wait for user input.**
+
+**Gate 3 Exit Criteria:** Severity scored, depth routed, evidence quality verified, ATT&CK mapped.
+
+---
+
+## Gate 4: Decide & Act (Standard + Deep only)
+
+### Entry: Analysis complete, depth determined
+
+**For AUTO-CLOSE:**
+- Propose disposition (False Positive or Benign Activity)
+- Document reasoning with evidence
+- If an org-policy skill is loaded and specifies `autonomy_level: recommend-close`, note the disposition as a recommendation (the analyst will see it in the report) — do not stop for confirmation here
+- Continue to Gate 5
+
+**For STANDARD:**
+- Review Five W's — are they complete enough for a verdict?
+- If yes: assign disposition with evidence
+- If no: run targeted follow-up queries via `digital-workers:fsql-expert`, then decide
+
+**Org-policy check:** If an org-policy skill is loaded, read its Incident Criteria (for escalation thresholds), Autonomy Level (auto-close vs. recommend-close), Custom Dispositions (additional categories), and Custom Runbooks (org-specific investigation procedures for matching alert types).
+
+**For DEEP:**
+
+Check if the org-policy defines a custom runbook for this alert type. If a match is found, invoke the runbook skill. Otherwise, invoke specialist investigators based on alert type from classification:
+
+| Alert Type | Skill to Invoke |
+|-----------|----------------|
+| Identity/Access | `digital-workers:identity-investigator` |
+| Network/Lateral | `digital-workers:network-investigator` |
+| Malware/Endpoint | (future: `endpoint-investigator` — use `fsql-expert` for manual process/file queries) |
+| Phishing/Email | (future: `email-investigator` — use `fsql-expert` for manual email queries) |
+| Cloud/Application | (future: `cloud-investigator` — use `fsql-expert` for manual API queries) |
+
+For alert types without a dedicated investigator in V1, use `digital-workers:fsql-expert` to run investigation queries manually following the patterns in the reference.
+
+**Always invoke the matched specialist, even when data gaps are expected.** The specialist is designed to discover and document gaps — that documentation is itself a finding. Skipping the specialist because "the data probably isn't there" means gaps get documented ad hoc instead of through the structured specialist process. If the specialist finds no data, it will report that as a finding with impact assessment.
+
+**Concurrency:** When multiple specialists are needed (e.g., Identity + Network), or when specialist investigation and threat intel enrichment are independent, invoke them in parallel using concurrent tool calls. Don't serialize work that has no dependencies.
+
+**After specialist investigation, propose disposition:**
+
+| Disposition | Criteria |
+|-------------|---------|
+| **Critical Threat** | Confirmed malicious activity. Evidence of compromise. Immediate response needed. |
+| **Policy Violation** | Real activity violating policy. May not be malicious. Remediation needed. |
+| **False Positive** | Detection logic triggered incorrectly. No actual security event. |
+| **Benign Activity** | Real activity that is expected or authorized. No action needed. |
+
+**INCIDENT ESCALATION RECOMMENDATION**: If proposed disposition is Critical Threat AND any of the following:
+- Active ongoing compromise
+- Data exfiltration confirmed or in progress
+- Lateral movement to high-value assets
+- Credential compromise with privilege escalation
+
+Then: **RECOMMEND INCIDENT ESCALATION**. Present evidence mapped against incident criteria. The analyst decides whether to formally declare an incident — that decision has compliance and business implications that require human judgment.
+
+**Gate 4 Exit — Save artifacts:**
+1. Append to `queries.md` — all specialist queries with result counts and findings
+2. Append to `iocs.md` — any new IOCs from specialist investigation
+
+**Gate 4 Exit Criteria:** Disposition proposed with supporting evidence. Incident escalation recommended if criteria met. **Continue immediately to Gate 5 — do not stop or wait for user input.**
+
+---
+
+## Gate 5: Build & Prioritize Case (Standard + Deep only)
+
+### Entry: Disposition assigned
+
+**Step 1: Assemble evidence package**
+
+Compile all investigation artifacts:
+- Original alert(s)
+- Classification (OCSF, ATT&CK)
+- Severity score with dimension breakdown
+- All FSQL queries run and their results
+- IOCs with reputation
+- Five W's with confidence levels
+- Specialist investigation findings (if DEEP)
+- Disposition with supporting evidence
+
+**Step 2: Prioritize**
+
+If investigating multiple alerts, prioritize by:
+1. Critical Threats first (always)
+2. Then by composite severity score (highest first)
+3. Then by timestamp (oldest unresolved first)
+
+**Gate 5 Exit Criteria:** Evidence package complete, priority assigned. **Continue immediately to Gate 6 — do not stop or wait for user input.**
+
+---
+
+## Gate 6: Incident Notification (Standard + Deep only)
+
+### Entry: Case built and prioritized
+
+**Org-policy check:** If an org-policy skill is loaded, read its Escalation Targets (notification routing per disposition) and Report Format (section preferences). Pass these to the report-writer.
+
+**Step 1: Generate report**
+
+Invoke `digital-workers:report-writer` with the complete evidence package.
+
+The report will include:
+- Business summary (plain English, always present)
+- Technical investigation (Five W's, IOCs, ATT&CK, evidence chain)
+- Recommended next steps
+- Show-your-work section (available on request)
+
+**Step 2: Save investigation**
+
+Save the report to the investigation directory as `report.md`
+
+**Step 3: Senior Analyst Review (BEFORE presenting to analyst)**
+
+**THIS STEP IS PART OF GATE 6, NOT OPTIONAL.** Do not present the report to the analyst until the review is complete. The investigation is not finished until the review runs.
+
+**Trigger:** If the investigation tier is **Deep**, OR the proposed disposition is Critical Threat (regardless of tier), you MUST invoke `digital-workers:senior-analyst-review` now — before presenting to the analyst. Standard tier skips this unless the analyst explicitly requests it.
+
+**Configurable:** If an org-policy skill is loaded, check its `review_trigger` setting:
+- `all` — review every investigation
+- `high_critical` — review HIGH and CRITICAL only (default)
+- `critical_only` — review only CRITICAL
+- `manual` — never auto-trigger, analyst invokes manually
+
+**If review identifies gaps:**
+1. Run the suggested follow-up queries via `digital-workers:fsql-expert`
+2. Update the evidence package, Five W's, and disposition if warranted
+3. Re-run `digital-workers:report-writer` with updated findings
+4. Save updated `report.md`
+5. Re-run `digital-workers:senior-analyst-review` on the updated investigation (max 2 cycles)
+
+**If review approves:**
+- Note "Senior Analyst Review: APPROVED" in the report
+- Proceed immediately to Step 4
+
+**Save:** Write `review.md` — the senior analyst review output (verdict, checks, any gaps identified)
+
+**Step 4: Present to analyst**
+
+Only after the review is complete (or if review was not triggered), present the report to the analyst.
+
+**Display the full report inline in the conversation.** The analyst should be able to read the complete investigation — business summary, disposition, Five W's, IOCs, evidence chain, and recommended next steps — without opening any files. The files (`report.md`, `queries.md`, `iocs.md`, `review.md`) are the durable record; the conversation is where the analyst reads and acts.
+
+If multiple alerts were investigated, present a summary table first, then the full report for each alert in priority order:
+
+```
+INVESTIGATION SUMMARY — [date]
+┌─────┬──────────────┬──────────┬─────────────┬───────────────┐
+│  #  │ Alert        │ Severity │ Disposition  │ Action Needed │
+├─────┼──────────────┼──────────┼─────────────┼───────────────┤
+│  1  │ [title]      │ CRITICAL │ Crit Threat  │ ESCALATE      │
+│  2  │ [title]      │ HIGH     │ Policy Viol  │ Remediate     │
+│  3  │ [title]      │ HIGH     │ False Pos    │ Tune rule     │
+│  ...│              │          │              │               │
+└─────┴──────────────┴──────────┴─────────────┴───────────────┘
+
+Starting with Alert #1 (highest priority)...
+```
+
+**Step 5: Incident escalation recommendation (if applicable)**
+
+If any alerts meet incident criteria, present the evidence for analyst review:
+
+```
+⚠️ INCIDENT CRITERIA MET: [alert title]
+Confidence: [HIGH/CONFIRMED]
+
+Evidence supporting incident declaration:
+1. [Specific criterion met with evidence reference]
+2. [Specific criterion met with evidence reference]
+3. [Specific criterion met with evidence reference]
+
+Proposed disposition: Critical Threat — Recommend Incident Escalation
+Recommended IR actions:
+1. [Specific containment recommendation]
+2. [Specific remediation step]
+3. [Notification recommendation]
+
+⚡ ANALYST ACTION REQUIRED: Review evidence and confirm whether to formally declare an incident.
+```
+
+**Step 4: Update environment profile with known false positives**
+
+After the report is finalized, review all detection messages that were dispositioned as **False Positive** or **Benign Activity** in this investigation. For each such message:
+
+1. Check if it already exists in `digital-workers/learned/environment-profile.json` under `known_false_positives`
+2. If it exists: update `last_verified` to today's date, increment `sample_size` if new samples were found, add this investigation ID to `investigations_confirmed`
+3. If it does NOT exist and the investigation confirmed ALL instances as RESOLVED/Benign with sample size ≥ 5: add a new entry:
+
+```json
+{
+  "known_false_positives": {
+    "<detection message text>": {
+      "status": "all_resolved_benign",
+      "connectors_seen": ["<connector_ids>"],
+      "sample_size": <count>,
+      "sample_window": "<time range queried>",
+      "last_verified": "<today's date>",
+      "investigations_confirmed": ["<this investigation ID>"],
+      "note": "<brief explanation of why this is benign>"
+    }
+  }
+}
+```
+
+**Why Gate 6 and not inline:** Known-FP entries suppress future verification queries. Writing them prematurely (before the investigation is complete) risks suppressing a detection that turns out to be a true positive after deeper analysis in Gates 4-5. Gate 6 writes are safe because the full investigation has concluded and the disposition is final.
+
+**Gate 6 Exit Criteria:** Report generated, senior analyst review completed (if triggered), investigation saved to `report.md` and `review.md`, analyst notified, escalation recommendation presented if applicable, environment profile updated with verified known false positives.
+
+**The investigation is now COMPLETE.** If there are more alerts to process, continue to the next alert. If this was the only alert (or the last in a batch), the workflow is finished.
+
+---
+
+## Processing Multiple Alerts
+
+When investigating a batch of alerts:
+
+1. Run Gates 1-3 for ALL alerts first (intake, enrich, score)
+2. Sort by priority (Critical Threats first, then by severity score)
+3. Run Gates 4-6 for each alert in priority order
+4. Continue to the next alert automatically — do not stop between alerts
+
+Present all reports at the end. The analyst can ask to dive deeper on any alert after reviewing the full batch.
+
+## Loop Mode Behavior
+
+When running in `/loop` mode for continuous monitoring:
+
+1. Query for new alerts since last check
+2. Run **Triage** on all new alerts (fast scan, no files)
+3. Present concise summary in conversation:
+   ```
+   [LOOP] 3 new alerts triaged:
+   - Alert A: 2 LOW findings, likely benign (no upgrade triggers)
+   - Alert B: 1 HIGH finding, single host (no upgrade triggers)
+   - Alert C: 3 CRITICAL findings, 5 hosts — AUTO-UPGRADING to Standard
+   ```
+4. Auto-upgrade to Standard for any alert that hits upgrade triggers
+5. For recommended escalations, break out of loop behavior and present full advisory
+
+## Red Flags
+
+| Red Flag | Correct Action |
+|----------|---------------|
+| "This alert is obviously a false positive, skip investigation" | STOP. Run the tier's gates. Document the evidence. The documentation IS the value. |
+| Running Deep when the analyst asked a question ("Any...?", "What's...?") | STOP. Questions = Triage. Don't waste 30 minutes when they wanted a 5-minute scan. |
+| Running Triage when the analyst said "investigate" or "full" | STOP. "Investigate" = Standard minimum. "Full"/"deep"/"thorough" = Deep. |
+| Stopping to ask which tier to use | STOP. Parse the prompt, select, announce, and go. The analyst can interrupt if wrong. |
+| Retrying empty fields with different field paths | STOP. If IOC/actor/observable fields are null, the data isn't there. Note the gap and move on. Don't spend 5 queries probing a skeleton-mapped alert. |
+| "I already know what this is" | STOP. You're skipping Gate 2 (gather information). Assumptions kill. |
+| "Let me just check the severity and decide" | STOP. Severity alone doesn't determine depth. Score all five dimensions. |
+| "No data found, closing as benign" | STOP. No data ≠ benign. It might mean the data source is unavailable. Document as Insufficient Data. |
+| "I'll write the report later" | STOP. The report is part of the investigation, not an afterthought. Gate 6 is mandatory. |
+| "This is low priority, I'll skip the specialist" | STOP. If the severity scorer routed to DEEP, run the specialist. Override requires explicit analyst direction. |
+| Jumping straight to Gate 4 without Gates 1-3 | STOP. Every investigation starts at Gate 1. No exceptions. |
+| Using Bash, cat, python, or jq to process data | STOP. **Never use shell commands to process investigation data.** Analyze MCP results directly as an LLM. Use the Read tool for files. Write more specific queries to reduce payload size. |
+| Lookback query without `status_id` in fields | STOP. Historical alerts may be RESOLVED/Benign. Always include `status_id` so you can distinguish active threats from closed false positives. |
+| Citing RESOLVED/Benign alerts as active threats | STOP. Check `status_id` and `status_detail`. RESOLVED+Benign means the source platform already investigated and closed it. Do not build an APT narrative on closed alerts. |
+| Skipping the senior analyst review on a DEEP investigation | STOP. The review is Step 5 of Gate 6 — it runs BEFORE you present to the analyst. It is not optional. |
+| Skipping the evidence-quality-checker because "the data looks fine" | STOP. The checker exists because data that looks fine can still produce false escalations. Run it. |
+| Only querying `detection_finding` and never pivoting to telemetry | STOP. Detection findings are alerts, not evidence. Pivot to `process_activity`, `file_activity`, `authentication`, etc. to see what actually happened. See Step 1.5 in Gate 2. |
+| Running individual queries for each IOC instead of batching | STOP. Use `%ip IN '1.2.3.4', '5.6.7.8'` to search multiple IOCs in one query. 5 separate IP queries = 5 queries burned. 1 batched query = 1. |
+| Probing multiple field paths in Gate 1 (actor, finding_info, unmapped, resources, raw_data...) | STOP. Gate 1 gets 2 IOC extraction queries max. If the intake + one raw_data query don't yield IOCs, move to Gate 2. |
+| 20+ queries on a Standard investigation | STOP. Standard budget is 15. You're over-investigating. Stop enrichment and write the report with what you have. |
+| Investigation taking >20 min at Standard tier | STOP. Check your query count. You've probably been field-path chasing or running per-IOC queries that should be batched. |