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

# Optimization overview

> Turn confirmed signals into shippable improvements — proposals, simulation, approval, deploy.

**Optimization** is the machinery between "we have a problem" (a signal or cluster) and "the problem is fixed" (a shipped version). It proposes concrete changes, tests them, and hands them to a human for approval.

You don't have to use it — you can hand-fix everything through the normal Draft-and-Publish flow. But Optimization automates the ceremony: proposing, testing, and preparing changes for review.

## The flow, in six steps

1. **Diagnose** — pick a cluster (or signal). Nora locates the root cause.
2. **Propose** — Nora generates 1-3 candidate fixes targeting the root cause.
3. **Pick a lever** — you decide which part of the system to change: prompt, tool, retrieval, memory, etc.
4. **Simulate** — every candidate runs against your dataset. Before/after numbers.
5. **Approve** — pick the winner. Optional gates (human review, code review, testing).
6. **Deploy** — the change applies to Draft; you publish (or auto-publish if configured).

## Pages

<CardGroup cols={2}>
  <Card title="Diagnose a failure" icon="magnifying-glass-chart" href="/reliable/optimization/diagnose">
    Root cause identification.
  </Card>

  <Card title="Improvement proposals" icon="lightbulb" href="/reliable/optimization/proposals">
    The candidate fixes and their diffs.
  </Card>

  <Card title="Which lever to tune" icon="sliders" href="/reliable/optimization/levers">
    Prompt vs. tool vs. retrieval vs. memory vs. rules.
  </Card>

  <Card title="Approve & deploy" icon="check-double" href="/reliable/optimization/approve">
    Human gates and rollout.
  </Card>

  <Card title="Improvement history" icon="clock-rotate-left" href="/reliable/optimization/history">
    Every improvement, its result, its status.
  </Card>
</CardGroup>

## Automatic vs. manual

The whole flow can run automatically for low-risk changes — you set the thresholds and Nora ships fixes without waking you up. Or it can require human approval at every step.

Recommended: automatic for well-understood levers with strong sim results (small prompt tweaks, rule additions). Manual for anything model-swap, tool-config, or memory-structural.

Configure per Flow: **Flow settings → Improvement automation**.

## Reproducibility

Every improvement carries:

* The cluster that seeded it.
* The proposals that were considered.
* The simulation results (target vs. baseline).
* The approver.
* The deploy timestamp.

Everything is reviewable months later. Great for compliance audits, incident review, and understanding why the Flow is the way it is.

## Improvements and versions

Every deployed improvement creates a new Flow version with the improvement noted. Rollback rolls back the whole improvement atomically.

You can see improvements attached to any version — "v18 was published to fix cluster #142 (billing hallucinations)."

## When improvements aren't automatic

Optimization proposes *changes*, but some fixes require things Optimization doesn't do:

* Adding a new document to knowledge — you upload.
* Building a new tool — you build.
* Fixing a broken upstream API — you fix.

For these, Optimization surfaces a **root-cause note** in Signals and stops. You take it from there.