> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracelit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolutions

> Step-by-step AI resolution: from incident to root-cause analysis, patch, and GitHub pull request — including modes, gates, and branch mapping.

Resolutions are Tracelit's agentic loop: take an incident, gather code and telemetry context, propose a minimal fix, and open a pull request for review.

<img src="https://mintcdn.com/tracelit/d4JOBsE1ajT2ZZdf/images/ai-code.png?fit=max&auto=format&n=d4JOBsE1ajT2ZZdf&q=85&s=ca4add968c30e36d5881b37f81eeca07" alt="Tracelit AI resolution flow from detection to pull request" className="rounded-lg" width="2644" height="2064" data-path="images/ai-code.png" />

***

## Prerequisites

Before a resolution can run:

1. **GitHub** is connected (Settings → Integrations).
2. A **repository** is linked on the site or service under **Utilities → Repository**.
3. **Branch mapping** is set for Development and Production (and you trust those branches).
4. The environment's **Allow resolutions** gate is on in **Utilities → Environment**.
5. For backend services, **code analysis** may also need to be enabled for that environment.

Local backend environments typically keep resolutions off.

***

## Resolution modes

Configure how aggressive Tracelit should be when proposing fixes (per site / service):

| Mode           | Behavior                                                                  |
| -------------- | ------------------------------------------------------------------------- |
| **Manual**     | You start a resolution from an incident. Tracelit does not auto-start.    |
| **Autonomous** | Eligible incidents can start a resolution automatically when gates allow. |

Auto-merge of PRs (if enabled) still respects branch protection and required CI checks. Tracelit never pushes straight to your default branch.

***

## End-to-end steps

<Steps>
  <Step title="Incident opens">
    An error or anomaly creates an incident. Confirm the environment is one you intend to fix (usually Development or Production).
  </Step>

  <Step title="Start resolution">
    From the incident, choose **Run AI Resolution** (manual mode), or wait for autonomous start when configured.
  </Step>

  <Step title="Context gathering">
    Tracelit loads the incident payload, related logs / traces or session replay, and source files from the linked repo at the mapped branch.
  </Step>

  <Step title="Root-cause analysis">
    The agent identifies the likely failing path and explains the cause in plain language.
  </Step>

  <Step title="Patch generation">
    A minimal diff is produced — smallest safe change that addresses the root cause.
  </Step>

  <Step title="Pull request">
    A PR opens on a fresh branch with summary, diff, confidence, and links back to the incident / evidence.
  </Step>

  <Step title="Review and merge">
    You review normally, or allow auto-merge when confidence and CI meet your policy.
  </Step>
</Steps>

<img src="https://mintcdn.com/tracelit/d4JOBsE1ajT2ZZdf/images/ai-stage.png?fit=max&auto=format&n=d4JOBsE1ajT2ZZdf&q=85&s=2da1b21e0e2c0a783f7045bd4764f5b2" alt="Resolution pipeline stages in Tracelit" className="rounded-lg" width="2638" height="2008" data-path="images/ai-stage.png" />

***

## Following a live resolution

Open **Resolutions** in the app to watch job stages (clone, analyze, patch, push, PR). Failed stages show logs so you can fix repo access, branch mapping, or build issues.

| Stage          | What happens                              |
| -------------- | ----------------------------------------- |
| Clone / detect | Repository access and framework detection |
| Analyze        | Root cause from telemetry + source        |
| Patch          | Diff generation                           |
| Verify build   | Optional build check when configured      |
| Push / PR      | Branch push and pull request creation     |

***

## GitHub events

After the PR exists, Tracelit reconciles GitHub webhooks:

| Event                     | Effect                                           |
| ------------------------- | ------------------------------------------------ |
| PR merged                 | Incident can move to resolved; job marked merged |
| PR closed without merge   | Job dismissed                                    |
| New commits on the branch | Re-checks auto-merge eligibility                 |

***

## Troubleshooting

| Symptom                      | Check                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------- |
| No **Run resolution** action | Environment gate, resolution mode, plan limits                                    |
| Clone / access errors        | GitHub App installation and repo permissions                                      |
| Wrong files changed          | Branch mapping in **Utilities → Repository**                                      |
| PR never opens               | Job log for push/PR stage; branch protection is fine — PR must still be creatable |

***

## Related

| Topic                | Guide                                                |
| -------------------- | ---------------------------------------------------- |
| Incident detection   | [Incidents](/agentic/incidents)                      |
| Gates, repo, archive | [Utilities](/agentic/utilities)                      |
| Product overview     | [AI resolutions](https://tracelit.io/ai-resolutions) |