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

# Manage individualized retraining with an agent

> Create one worker-specific LMS retraining occurrence from a documented quality gap, preview it safely, assign it once, and monitor the canonical Project To-do.

Individualized retraining turns one documented quality gap into one worker-specific LMS assignment. It uses the same course, assessment, mastery, Project To-do, grading, and retry systems as the OpenTrain dashboard.

<Warning>
  Retraining is always person-specific. Resolve exactly one active contract. Never substitute an active-roster or future-hire audience for an individualized assignment.
</Warning>

## Discover the live contract

Do not rely on remembered rollout state, authorization, enums, or limits. Read both capability documents before you author or assign training:

```bash theme={null}
opentrain capabilities --json
opentrain lms capabilities --json
```

First inspect the root response's `agentSurfaces` entry for LMS retraining. Its family status and per-operation `authorized` values describe whether this token can perform the workflow. Then use the LMS response's `retraining` section for operations, modes, close outcomes, exact-one recipient and due-date rules, receipt lifetime, and required human checkpoints. That response also reports the current course schema, lesson content, assessment question types, asset limits, Preview behavior, and mastery rules.

Treat `disabled`, `rollout_gated`, or `unauthorized` as fail-closed results. Do not bypass them with direct database writes.

## Before you start

You need:

* a job with **Training** enabled;
* one active contract ID, or an exact worker name that resolves to one active contract;
* a published course module registered as a skill-gap module;
* `lms:read` and `lms:write` permissions;
* the observed mistake, the expected behavior, and a worker-safe summary;
* either a due offset or an absolute local date, time, and IANA time zone.

Use existing LMS authoring and Preview operations to build and inspect the lesson and Native Forms assessment. The retraining case stores the employer's quality finding and connects it to that canonical module; it does not create a separate course or grading engine.

## The safe workflow

<Steps>
  <Step title="Resolve one worker">
    Prefer the stable contract ID. Exact-name resolution fails if no active worker matches or if more than one worker matches.
  </Step>

  <Step title="Create or reuse the module">
    Author the lesson and assessment with the normal LMS tools. Publish the course version, then register the module in the skill-gap registry. Reusing a module never adds worker evidence to the module itself.
  </Step>

  <Step title="Create a draft case">
    Capture the quality gap, expected behavior, approved Instructions references, evidence, delivery mode, due rule, and blocking policy. The case remains employer-only and creates no worker obligation.
  </Step>

  <Step title="Preview the real learner experience">
    Use LMS Preview against the exact course revision or published version. Review desktop and mobile output from the real learner renderer. Preview is isolated: it creates no assignment, Project To-do, attempt, notification, or reporting row.
  </Step>

  <Step title="Generate and review the assignment plan">
    Planning is strictly no-write. An authorized employer must review and explicitly approve the exact masked recipient, immutable course version and content hash, module, frozen due instant, eligibility, exact effect counts, request hash, and signed short-lived receipt.
  </Step>

  <Step title="Confirm once">
    After that human approval, submit the reviewed receipt, expected case revision, explicit confirmation, and a stable idempotency key. `confirmAssign: true` records the approved mutation; it does not authorize an agent to approve its own plan. OpenTrain atomically creates exactly one canonical Project To-do assignment and moves the case from `DRAFT` to `ASSIGNED`.
  </Step>

  <Step title="Monitor and review">
    Read the case for its live assignment, mastery budget, bounded run history, result-release state, and authorized employer-review projection. Use the existing grading, release, decision, and `RETURN` operations when needed.
  </Step>
</Steps>

## Mastery and employer-review modes

| Mode              | Completion behavior                                                                                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MASTERY`         | One module is submitted as a run. Required auto-graded questions must all pass. Correct prior answers carry forward and lock; missed answers are cleared for the next run. |
| `EMPLOYER_REVIEW` | The canonical LMS assignment waits for an authorized employer decision after the required work is submitted.                                                               |

The case does not grant attempts directly. When an exhausted mastery assignment needs one more run, use the canonical Project To-do `RETURN` operation with feedback and a stable idempotency key.

## Due-date behavior

Choose exactly one due channel:

* `dueOffsetMinutes`; or
* `absoluteDue` with `localDate`, `localTime`, and `timeZone`.

The no-write plan resolves either choice to one exact instant. The signed receipt freezes that instant, so a later confirmation does not recalculate the deadline.

## Occurrences and duplicates

One open occurrence may exist for the same worker and course module. A repeated retraining is a new case with a new operation key and a reference to the closed prior case. The earlier assignment, attempts, messages, and audit history stay unchanged.

Retries with the same idempotency key and identical request return the original result. Reusing the key for a different request fails.

## Choose a surface

* [CLI retraining commands](/docs/developers/cli/lms-retraining)
* [MCP retraining tools](/docs/developers/mcp/lms-retraining)
* [Retraining API](/docs/developers/api-reference/lms/retraining)
* [Scopes and live capabilities](/docs/developers/concepts/scopes-and-capabilities)