> For the complete documentation index, see [llms.txt](https://docs.cleric.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cleric.ai/investigation/how-investigations-work.md). # How Investigations Work Before investigating a new production problem, Cleric creates an **issue** to track it. Issues can start from monitoring alerts, Slack messages, or web requests. Each issue keeps the full history: the original report, related alerts, Cleric's investigation, evidence, suggested fixes, follow-up conversation, monitoring checks, and final resolution. ## Issue Lifecycle Most issues move through this lifecycle: 1. **Issue creation**: Cleric receives an alert or user request. If the alert matches a recent related issue, Cleric groups it into that issue instead of creating a duplicate. 2. **Investigation**: Cleric gathers context, queries connected integrations, correlates evidence, and looks for a root cause. 3. **Outcome**: Cleric either suggests a fix or reports that the evidence is inconclusive. Cleric continues to monitor the problem in the background. 4. **Resolution**: The issue closes when the problem clears, a fix is verified, or Cleric determines that the alert was a false positive. ## Issue Creation ### From Alerts Alert-triggered issues start when a configured automation receives a matching alert in Slack. Cleric uses the alert text, source metadata, Slack channel, service names, labels, and links to understand what fired and whether it should create a new issue. Before creating a new issue, Cleric checks whether the alert belongs to a recent open issue. If it does, Cleric groups the alert into the existing issue instead of starting another. ### From Slack or the Web User-initiated issues start when you mention `@Cleric` in Slack or create a **New issue** in the web app. These issues are interactive: Cleric can ask follow-up questions, incorporate your answers, and continue investigating in the same thread or web chat. ## Investigation Cleric investigates each issue systematically, but adapts as evidence emerges. ### Initial Assessment Cleric starts by identifying the problem scope: * Parse alert or request metadata, including severity, source system, labels, tags, and affected components * Identify likely services, environments, clusters, namespaces, or infrastructure resources * Determine whether the issue is alert-triggered or user-initiated * Look for related issues, recent alerts, and relevant historical context ### Evidence Gathering Cleric queries your connected integrations to gather relevant data. Depending on the issue, this can include metrics, logs, traces, deployments, Kubernetes resources, cloud resources, incident history, code changes, runbooks, and monitoring configuration. The investigation changes direction as evidence appears. If an alert initially looks like an infrastructure problem but logs point to a recent deployment, Cleric pivots toward application and release evidence. ### Correlation Cleric correlates data across systems to identify relationships that may not be obvious from a single dashboard or log stream: * Align events across monitoring systems, deploy history, logs, and infrastructure changes * Compare symptoms against baselines and known historical patterns * Connect application errors with resource pressure, configuration changes, dependency failures, or traffic shifts * Separate likely causes from coincidental events ### Results Cleric reports what it found with evidence, reasoning, uncertainty, and recommended next steps. The web issue page preserves the full activity log so you can inspect tool executions, intermediate findings, and conversation history. ## Issue Statuses Cleric exposes five issue statuses, listed below. Note that issues that only invoke custom agents may not enter certain states. | Status | What it means | What to do next | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **Investigating** | Cleric is actively working, gathering evidence, or still running the investigation. | Wait for results, or interrupt the agent and provide additional context if desired. | | **Fix suggested** | Cleric found a likely root cause and proposed a remediation. The issue is still open until the fix is applied, verified, or otherwise resolved. | Review the suggested fix and apply it if appropriate. | | **Monitoring** | Cleric is watching an observable recovery signal before making a final resolution call, such as whether the alert clears or metrics return to normal. | Add missing context, grant access to missing data, or ask follow-up questions. | | **Inconclusive** | Cleric completed the investigation but could not identify a confident root cause or actionable fix from available evidence. | Add missing context, grant access to missing data, or ask follow-up questions. | | **Resolved** | The issue is closed because the problem cleared, a fix was verified, another fix resolved it, the issue self-resolved, or it was determined to be a false positive. | No action required. | ### Common Status Transitions Issues do not have to visit every status. Common paths include: * **Fix found**: `Investigating → Fix suggested → Resolved`. Cleric may monitor fix application or recovery in the background while the user-facing status remains **Fix suggested**. * **No clear root cause**: `Investigating → Inconclusive`. * **Observable recovery without a proposed fix**: `Investigating → Monitoring → Resolved`. **Monitoring** appears when the investigation has completed, there is no active proposed fix, and Cleric has scheduled an active resolution check that can observe whether the issue clears. * **Monitoring cannot confirm recovery**: `Investigating → Monitoring → Inconclusive`. This can happen when the scheduled check reports that the signal is no longer reliable, or when the observation window expires without enough evidence to mark the issue resolved. * **False positive, self-resolved, or fixed via other means**: `Investigating → Resolved`. ## When Cleric Needs More Information How Cleric handles missing information depends on how the issue started. ### User-Initiated Issues When you start an issue via `@Cleric` in Slack or the web app, Cleric can ask clarifying questions before continuing. This happens when: * **Scope is ambiguous**: The issue could apply to multiple services, environments, clusters, or time windows. * **Access is missing**: Cleric identifies a relevant data source it cannot reach. * **Evidence conflicts**: Cleric finds plausible explanations that require human context to prioritize. * **Operational context is unavailable**: Cleric needs information that is not present in connected tools, such as whether a deployment or load test was intentional. Reply in the same Slack thread or web chat. Cleric incorporates your answer and continues the issue. ### Alert-Triggered Issues When an alert triggers an issue automatically, Cleric does not usually ask questions before reporting findings. It investigates with available data and explicitly notes any gaps, missing access, or assumptions that could affect the conclusion. ## When Cleric Cannot Find a Root Cause Not every issue reaches a definitive root cause. When the evidence is insufficient, Cleric should make that uncertainty explicit instead of guessing. In inconclusive cases, Cleric reports: * **Partial findings**: Relevant logs, metric anomalies, configuration changes, or timeline details that may still help your team. * **Access limitations**: Data sources that could not be reached because of permissions, missing integrations, retention windows, or connectivity. * **Remaining uncertainty**: What Cleric could not prove and what additional information would help. You can continue the issue at any time by replying with more context, asking Cleric to check another source, or starting a deeper investigation from a specific hypothesis. ## Where to Inspect an Issue Use Slack for fast collaboration and the web app for the complete record. * **Slack thread**: See updates, answer questions, add context, and ask follow-ups where your team is already working. * **Web issue page**: Review status, grouped alerts, investigation history, evidence, suggested fixes, activity logs, and the complete conversation.