| name | headless-investigate-incident |
| description | Headless incident investigation planning that formulates multiple hypotheses from organizational context. Use when an agent should autonomously plan an investigation for an alert, incident ticket, or symptom description — correlating the affected system's architecture, recent changes, and historical incidents to produce ranked hypotheses with parallel investigation tracks. Output is structured for AI agent consumption. Does not gather evidence or recommend fixes.
|
Incident Investigation Planning
Autonomous investigation planning for headless execution. Apply this to the incident in the user's prompt. Produces ranked hypotheses and parallel investigation tracks grounded in organizational context. Does not gather evidence or implement fixes.
Gotchas
- Anchoring on the alert name. Alert names describe symptoms, not causes. Investigate the system, not the alert string.
- Single-hypothesis thinking. Always produce 3+ hypotheses. The first plausible explanation is rarely the right one — satisfaction of search is the top failure mode in incident investigation.
- Ignoring blast radius. Before deep-diving, assess what else is affected. A single-service alert can mask a platform-wide issue.
- Skipping duplicate check. If someone is already investigating this, your plan should build on their work, not duplicate it.
How This Works
- Parse the incident via
context_get_urls (URL), context_search_issues or context_research (Jira ticket), context_research (Datadog/Sentry incident), or from the prompt. Extract: alert name, affected service(s), symptom description, severity, start time, error messages, impacted metrics.
- Check for related investigations via
context_search_issues / context_search_messages (CLI) or context_research (Datadog/Sentry incidents): all open incidents, active investigations, or recent postmortems for the affected service(s). Note findings to avoid duplicate work.
- Hydrate with organizational context via
context_research:
- System understanding (
effort: medium): "How does [affected service] work? Architecture, dependencies, upstream/downstream services, deployment pipeline, known failure modes, recent incidents."
- Recent changes (
effort: medium): "What changed in [affected service] and its dependencies in the last 48-72 hours? PRs merged, deployments, config changes, infrastructure changes, traffic pattern shifts."
- Formulate hypotheses — 3-5 candidate root causes, each with:
- Hypothesis statement
- Supporting evidence from context
- What evidence would confirm or rule it out
- Investigation steps to test it
- Produce structured output following the output format below.
Output Format
Output is consumed by an AI agent, not a human. Optimize for token efficiency and actionability. No narrative prose.
INCIDENT
service: [affected service(s)]
severity: [SEV level]
start_time: [timestamp]
symptoms: [one-line description]
error: [error message if any]
RELATED_INVESTIGATIONS
- [ticket ID] | [status] | [summary] | [relevance to this incident]
HYPOTHESES
1. [statement]
likelihood: HIGH|MEDIUM|LOW
evidence: [compact citations — PR#, dates, Slack refs]
confirm_by: [what evidence would prove this]
rule_out_by: [what evidence would disprove this]
next_actions: [specific investigation steps]
2. ...
3. ...
PARALLEL_TRACKS
track_1: [hypothesis IDs that can be investigated together]
actions: [grouped investigation steps]
track_2: ...
BLAST_RADIUS
affected_services: [list]
affected_users: [scope estimate]
upstream_risk: [services that may be causing this]
downstream_risk: [services that may be impacted]
ESCALATION_TRIGGERS
- [condition] → [who to page]
Abort Conditions
- Can't fetch or parse the incident — stop and report what was attempted.
- No relevant context for the affected service — produce minimal output noting what was searched and LOW confidence on all hypotheses.
- Affected service is completely unclear — report that the investigation needs more information before planning.
Tool Selection
| Question | Preferred tool | Fallback / Why |
|---|
| System architecture, history, failure modes | context_research (effort: medium or high) | Cross-source synthesis needed |
| Recent changes and deployments | context_research (effort: medium) | Need to correlate PRs, deploys, and config across sources |
| All open Jira tickets for a service (exhaustive list) | context_search_issues (CLI) | context_research with "Prefer issue tracker results" instruction |
| Datadog/Sentry incident data for a service | context_research (effort: medium) | Direct incident-platform data requires cross-source investigation |
| PRs most related to the affected subsystem | context_search_prs (CLI) | context_research with "Prefer PR descriptions and review discussions" instruction |
| Focused question about specific service behavior | context_research (effort: low) | One entity, one question |
| Fetch incident details from URL | context_get_urls | Already have the URL |
Fine-grained tools (context_search_prs, context_search_issues, context_search_messages, context_search_code, etc.) are available in the Unblocked CLI. On MCP, fall back to context_research with a steering instruction.
