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

# Fixes

> Draft a candidate change from a Problem's evidence, verify it on a held-out replay gate, and deliver it as a draft PR that Moda monitors after merge.

A Fix is what closes a [problem](/dashboard/problems): **a fix with proof**. From a problem's evidence, Moda scopes a frozen replay set, routes the change to a target artifact (usually a managed prompt), proposes a candidate revision, and verifies it on held-out production cases before anything is delivered. Open **Improve → Fixes** to see the ranked queue, or draft one directly from a problem's Dossier.

<Note>
  Moda never merges a fix and never pushes to your default branch. Delivery is always a **draft** pull request (or a branch you apply yourself), and a human reviews and merges it.
</Note>

## Draft a fix

The Dossier header's primary action is **Draft fix** (a split button; **Mark as fixed manually…** remains available for changes you shipped outside Moda). Drafting kicks off a pipeline whose progress shows directly on the button: **Drafting…**, **Fix proposed — review**, **Verifying…**, then **Fix ready** or **Gate failed**.

<Steps>
  <Step title="Scope">
    Moda reads the problem's verified evidence anchors and builds a replay set from them, split deterministically into **repair** cases (used to propose the change) and a **holdout** (reserved for the verdict). Problems with too little usable evidence rest as diagnosis-only fixes rather than guessing.
  </Step>

  <Step title="Route and propose">
    If the evidence concentrates on one managed prompt version, the fix targets that prompt and Moda proposes a candidate revision from the repair cases' failure evidence. Evidence that points at a tool schema, or at nothing routable, still produces an investigation packet — those fixes are deliverable as diagnosis, not dead ends.
  </Step>

  <Step title="Verify">
    Two replay comparisons run on the frozen set: the gate (baseline vs. candidate) and a control (baseline vs. baseline) that measures replay noise. The verdict reads only the holdout.
  </Step>

  <Step title="Deliver">
    A verified fix can open a draft PR, be applied on a local branch, or be handed to a coding agent as a packet. Merging the PR starts confirmation monitoring.
  </Step>
</Steps>

## The Fixes page

**Improve → Fixes** lists every fix, ranked by the underlying problem's rank. Each row shows the fix type chip, a one-sentence rationale, and a gate badge — plus inline **Open PR** and **Dismiss** actions where they apply. The gate badge only appears when the holdout has at least 5 cases; below that the row shows **Insufficient evidence** instead of a verdict. Dismissing requires a reason, which is recorded as [problem feedback](/dashboard/problems#feedback-actions) and steers discovery.

## The Fix tab

A problem with a fix gains a **Fix** tab beside Dossier and Conversations: a vertical stepper of five cards, one per pipeline stage.

| Card             | What it shows                                                                                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Target**       | The routed artifact (prompt, tool, or unrouted) with its source path and route confidence.                                                                                  |
| **Candidate**    | The proposed revision as a diff against the pinned baseline version, with changelog and risks, and Approve/Reject actions.                                                  |
| **Verification** | The gate scoreboard: the holdout headline, repair results labeled *training cases*, the noise floor from the control run, listed abstentions, and a link to the replay run. |
| **Delivery**     | The chosen channel and, for PRs, the draft PR link and its status.                                                                                                          |
| **Confirmation** | The merge record (PR, merge commit, shipped version) and the monitoring state.                                                                                              |

## Lifecycle

The dashboard renders stage chips; each chip covers one or more underlying statuses (the raw status is always visible on the fix detail and in the API).

| Stage          | Statuses                                                     | Meaning                                                                                                                                                                                  |
| -------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Drafting       | `DRAFT`, `SCOPING`                                           | Evidence is being scoped into the frozen replay set and routed to a target.                                                                                                              |
| Diagnosis only | `NO_EVIDENCE`, `BLOCKED_COVERAGE`, `UNROUTED`, `NO_HEADROOM` | The pipeline rested without a candidate — too little evidence, no replayable cases, no routable target, or the proposer found no headroom. Still deliverable as an investigation packet. |
| Proposing      | `PROPOSING`, `PROPOSED`                                      | A candidate revision is being generated, or is registered and waiting for the gate.                                                                                                      |
| Verifying      | `GATING`                                                     | Gate and control replay runs are in flight.                                                                                                                                              |
| Gate failed    | `GATE_FAILED`, `GATE_INCONCLUSIVE`                           | The candidate did not beat baseline, or the gate produced no verdict. Inconclusive is a first-class outcome — it is never shown as a pass.                                               |
| Fix ready      | `VERIFIED`                                                   | The candidate won on the holdout. Ready to deliver.                                                                                                                                      |
| Delivered      | `PR_OPEN`, `APPLIED_LOCALLY`, `HANDED_OFF`                   | A draft PR is open, the change was applied on a named branch, or the packet was handed to an agent.                                                                                      |
| Monitoring     | `SHIPPED`, `CONFIRMING`                                      | The PR merged; the problem is in fixed-monitoring and Moda watches for recurrence.                                                                                                       |
| Held           | `HELD`                                                       | 14 clean monitoring days after the merge — the fix held.                                                                                                                                 |
| Regressed      | `REGRESSED`                                                  | The problem reopened while monitoring; the fix did not hold.                                                                                                                             |
| Closed         | `REJECTED`, `SUPERSEDED`, `ABANDONED`                        | Dismissed with a reason, replaced by a newer fix for the same problem or file, or abandoned.                                                                                             |

## Verification you can trust

The gate is built so a green badge means something:

* **The holdout is the only headline.** Repair cases shape the candidate, so their scores are shown as *training cases*, never as the verdict. The holdout never reaches the proposer.
* **Wins must clear the noise floor.** A control run replays baseline against baseline on the same cases; any disagreement there is pure replay noise. The candidate passes only when its holdout wins minus losses exceed `max(2, noise floor + 1)` and losses stay within the noise floor.
* **Abstentions are counted, not hidden.** Holdout cases that cannot be replayed faithfully are excluded from scoring and listed as abstained. More than 30% abstained makes the verdict inconclusive — never a pass.
* **No badge below minimum evidence.** A holdout under 5 cases shows *Insufficient evidence* instead of a verdict.
* **Every number links to its replay run**, so you can read the per-case transcripts behind the scoreboard.

## Delivery channels

| Channel          | What happens                                                                                                                                                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Draft PR**     | Moda's GitHub App opens a draft PR on branch `moda/fix/<shortref>` with the cited root cause, the verification scoreboard, rollback instructions, and evidence quoted inside a fenced block marked as untrusted data. The body ends with the magic word `Fixes MODA-FIX-<SHORTREF>`. |
| **Local branch** | You apply the change yourself (for example with `moda fix checkout`) and record the branch; the fix is tracked as applied locally. A hand-authored PR must carry the same magic word for the merge to confirm the fix.                                                               |
| **Agent packet** | Any fix — including diagnosis-only ones — exposes a compact `moda.fix_packet.v1` packet (cause, target, evidence links, verify command, handback instructions) for a coding agent to work from.                                                                                      |

## Confirmation and reopening

Merging a PR whose body or branch carries `MODA-FIX-<SHORTREF>` confirms the fix — whether Moda or a human authored the PR. The fix moves to **Monitoring**, and Moda records a `mark_fixed` on the problem with structured fix provenance (PR, merge commit, shipped prompt version). While the problem sits in fixed-monitoring the fix shows as confirming; if the problem [reopens](/dashboard/problems#lifecycle-columns), the fix flips to **Regressed**. After 14 clean monitoring days it becomes **Held**.

## Throttles

* At most **3 open Moda fix PRs** per workspace — merge or close one before submitting another.
* **One open fix per problem and per target file.** Drafting again while a fix is active returns the existing fix, and submitting a fix supersedes older drafts for the same problem or file. An already-open sibling PR blocks a second submission.
* Dismissal always requires a reason, which feeds problem feedback.

## Next steps

* [Problems](/dashboard/problems) — the root-cause groups fixes are drafted from.
* [Fixes in the Data API](/data-api/fixes) — the same objects and pipeline over HTTP.
* [CLI reference: Fixes](/cli/reference#fixes) — drive the loop from the terminal, including the fail-to-pass `moda fix verify` loop for coding agents.
* [Replays and Playground](/dashboard/evaluate) — the replay machinery the gate runs on.