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

# Build a lesson from an evaluation

> Turn a verified correction into a lesson: verify the correction, write the guidance and its rule, add examples, and save a version for independent review.

This guide follows one correction from a saved Herman answer to a lesson waiting for review. Read the [Lessons learned overview](https://docs.plastics.com/lessons/overview.md) first if you are new to lessons.

You need evaluation access in your workspace and permission to author lessons. Approving a lesson takes a second person: you cannot approve a lesson you wrote or one built on a correction you wrote.

## The example used in this guide

A buyer asked Herman to compare the tensile strength of three PBT grades. One grade had no published tensile value, so Herman estimated it and then ranked that grade first. The reviewer's correction: estimated values must be labeled as estimates, and grades must not be ranked on them.

The resulting lesson:

* **Guidance**: When a comparison uses estimated values, label each one as an estimate and do not rank grades on estimated values.
* **Limit**: Does not apply when the comparison fell back to a simpler method, because no values are ranked in that case.
* **Applies when**: Estimated values used is true.
* **Excludes**: Comparison fallback used is true.

## Steps

**1. Add the answer to the review queue**

In **Evaluations**, open **Saved questions** and choose the answer you want to correct. Select **Add to review queue**. The case appears in **Evaluations → Review queue**.

**2. Rate and correct the answer**

Open the case and select **Assign to me**, or assign a reviewer. Rate the answer, then write a **Suggested correction**: what the answer should have said.

Cite the source for the correction: the document, its revision, and the exact page, table, or section. The correction must be checkable against that source. Select **Submit for independent review**.

**3. Get an independent decision**

A different reviewer opens the case, checks the correction against the cited source, sets **Decision** to **approved**, confirms the check, and selects **Record independent decision**.

Lessons can only be built from an approved case. If the source changes after approval, the case must be reloaded before you can write lessons from it.

**4. Open Step lessons on the approved case**

On the approved case, set **Candidate type** to **lesson**. The **Step lessons** panel opens. Choose the **Verified correction** to build from.

Select **Write a lesson** to start from a blank lesson, or **Draft with AI** to have Herman propose one or more lessons from the correction. AI drafts are a starting point; review every field before saving.

**5. Write the guidance and its limit**

Fill in **Guidance for Herman** and **Counterexample and limit**. See [Write good guidance](#write-good-guidance).

**6. Set the rule for when it applies**

Under **Apply when**, build the rule from the inputs the step can see. Add **Exclusions** for situations where the guidance would be wrong. See [Build the rule](#build-the-rule).

**7. Add examples**

Under **Applicability examples**, add at least one positive, one negative, and one unknown example. See [Add examples](#add-examples).

**8. Check and save**

Select **Check applicability**. The check confirms the rule and every example match the current step contract. Fix anything it reports.

Write the **Reason for this lesson**, usually a sentence on what went wrong in the original answer. Select **Save candidate version**. The lesson appears on the **Lessons Learned** page as **Needs review**.

You can write several lessons from one correction when the correction covers separate problems. Keep each lesson to one behavior so each can be tested, approved, and released on its own.

## The lesson fields

| Field | What to put here |
| - | - |
| Guidance for Herman | The instruction, in one or two sentences. Up to 2,000 characters. |
| Counterexample and limit | Where the guidance stops applying, or what Herman should not overcorrect into. Required. |
| Classification | **reasoning omission** when Herman left out a needed step in its reasoning (shown as Corrective rule on the lesson record). **restraint** when Herman claimed or did more than the evidence supports. **response structure** when the content was right but the presentation was not. |
| Priority | **Required when applicable**: Herman must follow it whenever the rule matches. **Supplementary**: useful guidance Herman can weigh against other instructions. |
| Lifecycle | **Durable guidance** for behavior that stays correct. **Review when source changes** when the lesson depends on the cited source and should be rechecked if that source is revised. |
| Apply when | The rule that decides whether the lesson applies to an answer. |
| Exclusions | Optional. Situations that turn the lesson off even when **Apply when** matches. |
| Applicability examples | 3 to 12 example inputs with the outcome each should produce. |
| Reason for this lesson | Why this lesson exists. Reviewers read this when deciding. |

Lessons currently apply to one step, **Comparison response**: the step that writes the answer when a buyer compares grades.

## Write good guidance

Write an instruction Herman can follow without seeing the original question.

* State the behavior, not the incident. "Label estimated values as estimates" works for every comparison; "The PBT answer was wrong" does not.
* Keep one behavior per lesson. If the guidance needs "and also", it is probably two lessons.
* Do not include product data. Grade properties, certifications, prices, inventory, and lead times must come from systems of record. Approvers reject lessons that contain them.
* Use the limit to prevent overcorrection. A lesson about labeling estimates should not make Herman refuse to compare grades that have published values.

| Instead of | Write |
| - | - |
| Don't rank Grade X first. | Do not rank grades on estimated values. |
| PBT tensile strength for Grade X is unknown. | When a value is missing, say it is missing instead of estimating it. |
| Be more careful with numbers. | When a comparison uses estimated values, label each one as an estimate. |

## Build the rule

The rule uses inputs the comparison step already has when it writes an answer:

| Input | Type | Meaning |
| - | - | - |
| Estimated values used | True or false | Some compared values were estimated rather than published. |
| Comparison fallback used | True or false | The comparison fell back to a simpler method. |
| Numeric comparison rows available | True or false | The answer has numeric rows to compare. |
| Multiple items being compared | True or false | More than one item is being compared. |
| Number of comparison sides | Number | How many items are compared. |
| Material domain | Text | The material family being compared. |
| Research findings available | True or false | Research findings were supplied to the step. |

Choose a **Match rule** for each condition:

| Match rule | Use it for |
| - | - |
| Equals | One input has one value, such as Estimated values used is true. |
| Is one of | One input matches any value in a list. Enter allowed values one per line. |
| Is known | The input is known, whatever its value. |
| Is unknown | The input is missing for this answer. |
| All conditions | Every nested condition must match. |
| Any condition | At least one nested condition must match. |

Make the rule as narrow as the correction supports. A rule that matches every comparison applies the guidance to answers it was never checked against.

## Add examples

Examples prove the rule does what you intend. Each example is a set of input values and the expected outcome.

| Kind | Expected outcome | In the example lesson |
| - | - | - |
| Positive | **Applies** | Estimated values used: true. Comparison fallback used: false. |
| Negative | **Does not apply** | Estimated values used: false. |
| Unknown | **Unknown** | Estimated values used: unknown. |

Every lesson needs all three kinds. An unknown example must leave at least one input the rule depends on unknown or missing; this shows what Herman does when it lacks the information. Each example's inputs must be different from the others.

When **Check applicability** fails, the message says which example disagrees with the rule. Fix the rule if it is wrong; fix the expected outcome if the example is wrong. Do not change an example only to make the check pass.

## After you save

The new version shows **Needs review** on the **Lessons Learned** page.

1. **Review.** A qualified colleague opens the lesson, selects **Review and decide**, confirms the lesson contains no product data, and approves or rejects it with an explanation.
2. **Test.** In the lesson record, select **Run tests** under **Tests**. When the rule tests pass, a quality gate can compare answers with and without the lesson. See [Testing](https://docs.plastics.com/lessons/overview.md#testing).
3. **Revise.** To change a lesson, open it and select **Edit as new version**. The new version needs its own review and tests.

> [!NOTE]
>
> Approving or testing a lesson does not change Herman's answers. Release is a separate step and is not yet available.

## Checklist before you save

* The source case is approved and its source is current.
* The guidance states one behavior and contains no product data.
* The limit says where the guidance stops.
* The rule is as narrow as the correction supports.
* There is at least one positive, one negative, and one unknown example.
* **Check applicability** passes.
* The reason explains what went wrong in the original answer.

## Troubleshooting

| Message or symptom | What to do |
| - | - |
| **Step lessons** does not appear | The review case is not approved yet, or lesson authoring is not turned on in your workspace. |
| **Draft with AI** is disabled | AI drafting is not available in your workspace yet. Use **Write a lesson**. |
| "Source, contract, version or access changed, or the examples do not match the rule. Reload before continuing." | Select **Reload lessons**, check the examples against the rule, and save again. |
| "Could not confirm this request. Retry the same request to avoid duplicates." | Select **Retry same request**. Retrying with the same request does not create a duplicate. |
| "Lesson uses a stale step contract" in rule tests | The comparison step's inputs changed. Edit the lesson as a new version and update its rule. |
| You cannot approve your own lesson | Expected. An approver must be someone other than the author and the person who wrote the correction. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.