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

# Changes

> Agent-scoped fixes that address one or more findings, with a draft-to-published workflow.

A **change** is one atomic, agent-scoped suggestion that addresses a set of
[findings](/docs/findings) — "rewrite the voicemail-detection branch of the prompt",
say, in response to a cluster of *Voicemail not detected* findings. Where a
finding is the durable record of a *problem*, a change is the record of the
*fix*: what you'll change, who owns it, and how far along it is.

A change is bound to a single [agent](/docs/agents). It inherits that agent from
the findings you build it from — specifically the first agent on the seeding
finding — so a finding with no agent can't seed a change.

## Draft vs. published

Every change starts life as a **draft**: a private idea with no workflow
status, hidden from the main Changes list. The list has three views —
**Published**, **Drafts**, and **All** — so drafts stay out of the shared
worklist until someone signs off. A draft leaves draft state one of two ways:

| Action      | Result                                                      |
| ----------- | ----------------------------------------------------------- |
| **Publish** | Moves to the `backlog` status and joins the published list. |
| **Discard** | Moves to the `cancelled` status.                            |

`draft` is a separate flag from `status` — a draft simply has no status yet.
You can't set a workflow status while a change is still a draft; publish or
discard it first.

## Status workflow

Once published, a change carries one of five statuses: `backlog`, `todo`,
`in_progress`, `done`, and `cancelled` for work you abandon. They're ordinary
workflow states — set whichever reflects reality, there's no forced
progression.

## Anatomy of a change

| Field           | What it is                                                                           |
| --------------- | ------------------------------------------------------------------------------------ |
| **Title**       | Short headline (optional, up to 255 characters).                                     |
| **Description** | Rich text (Tiptap / ProseMirror JSON) — the proposed change, rationale, links.       |
| **Agent**       | The agent the change targets, derived from its findings.                             |
| **Findings**    | One or more linked findings the change addresses.                                    |
| **Assignee**    | The org member who owns the fix (must belong to the org).                            |
| **Status**      | `null` while a draft, then one of the five workflow states.                          |
| **Type**        | The kind of change — see [Change types](#change-types).                              |
| **Generated**   | When the change was created — a change can be drafted by a person or surfaced by AI. |

## Change types

Every change carries a **type** that categorises the kind of work it involves.
Five types are built in and available to every org:

| Type              | For                                                |
| ----------------- | -------------------------------------------------- |
| **Code change**   | Application or integration code.                   |
| **Prompt change** | Edits to an agent's prompt or instructions.        |
| **Monitoring**    | New alerts, metrics, or monitors.                  |
| **Strategy**      | Higher-level operational or policy decisions.      |
| **Generic**       | Anything that doesn't fit the above (the default). |

Owners and admins can define **custom types** for the org under
**Settings → Organization → Change types** — give each a name and a color. A
change defaults to **Generic**; set its type from the change detail page or when
drafting it. Deleting a custom type reverts any change using it back to Generic.

## Acting on a change

From a change's detail page — or its card on a [finding](/docs/findings) — a
few actions sit alongside the title:

| Action             | What it does                                                                                                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solve**          | Opens the in-product assistant on a new chat with a prompt that links this change and asks it to apply the change, keeping the change's [status](#status-workflow) up to date as it makes progress. |
| **Copy as prompt** | Copies the full change (title, summary, linked findings) to your clipboard as a ready-to-run prompt, to paste into any other tool.                                                                  |
| **Copy link**      | Copies a direct link to the change.                                                                                                                                                                 |

## Linking findings

A change links to findings through the `solution_findings` join, and the
relationship is many-to-many: one change can address several findings, and
you can link or unlink them as your understanding changes. Deleting a change
removes its finding links by cascade but **never** deletes the underlying
findings — the problems outlive any single proposed fix.

A finding's detail page surfaces the changes linked to it, so you can track
the fix alongside the problem. See [Findings](/docs/findings).

## Programmatic access

Changes are **MCP-only** today — there is no `/v1/changes` REST
endpoint. Over [MCP](/docs/mcp) an agent can draft and manage them end to end:

* `list_solutions` / `get_solution` / `list_solution_findings` — read.
* `create_solution` — draft one change (optionally with a `type`). It inserts
  exactly **one** draft per call, so never bundle several ideas into one body —
  call it again for each distinct suggestion.
* `publish_solution` (→ `backlog`) / `discard_solution` (→ `cancelled`) — move
  out of draft.
* `update_solution` — edit title, description, status, or assignee.
* `link_finding_to_solution` / `unlink_finding_from_solution` — manage linked
  findings.

See the [MCP reference](/docs/mcp#changes) for full tool schemas.

## Related

* [Findings](/docs/findings) — the problems a change addresses.
* [Reports](/docs/reports) — written analyses of the operation a change lives in.
* [Agents](/docs/agents) — every change is scoped to one agent.
* [Triage findings](/docs/guides/triage-findings) — the workflow from a finding to a published change.
* [MCP](/docs/mcp) — draft and manage changes programmatically.