> ## Documentation Index > Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Improve > How Sovara turns observations into targeted improvements. Improvement starts after a run has been inspected and the failure mode is clear. Sovara helps you turn that review into a change that is specific enough to fix the problem without making nearby cases worse. The important decision is where the fix belongs. Some failures need code. Some need a better prompt. Some need a new tool. Some come from domain knowledge the agent lacks, where the right fix is a reusable lesson. ## Choose the right fix Use the smallest fix that addresses the actual failure: | Failure pattern | Better fix | | -------------------------------------------------------------------- | ----------------------------- | | The agent could not perform an action | Add or improve a tool | | The agent did not follow instructions that are not context dependent | Update the prompt or workflow | | The agent missed a domain rule or context-dependent instruction | Create a lesson | The goal is not to turn every annotation into a lesson. A lesson is useful when the lesson is reusable, conditional, and likely to matter again. Learn more in [What are lessons?](/sovaradb/lessons). ## Make domain lessons reusable When the failure comes from missing domain knowledge, open Lessons and create a lesson. Capture the lesson in a form that is precise, scoped, and retrieval-friendly. Click New Lesson, write the rule, and use Suggest to draft the **Use this when** field. Before relying on the lesson, review it with Review. The detailed workflow is covered in [Creating and managing lessons](/sovaradb/creating-managing-lessons). ## Validate the change After applying a fix, rerun representative examples and inspect the new traces. The question is not only whether the original failure disappeared. Check whether the fix changed related behavior in a way you did not intend. Use [Runs](/observability/runs) to compare executions, [Manual inspection](/observability/manual-inspection) to inspect the changed steps, and [Run chat](/observability/run-chat) to get a fast read on the new run. For failures that should become regression tests, add repeatable coverage to the test suite that exercises the affected workflow. ## Close the loop Once a fix works, keep the annotation history. It tells Sovara which behavior is already covered and helps the recommendation algorithm avoid wasting reviewer time on examples that no longer teach anything new. If similar failures keep appearing, the fix is probably too narrow, not being retrieved at the right time, or applied at the wrong layer. In that case, go back to the reviewed runs and refine the prompt, tool, lesson, or test until the pattern is covered.