DEVELOPER DOCUMENTATION

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.

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:

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

Resolve one worker

Prefer the stable contract ID. Exact-name resolution fails if no active worker matches or if more than one worker matches.

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.

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.

Generate the authoring scaffold

Request the case scaffold before writing the course. It deterministically organizes the captured evidence into approved grounding, a lesson outline, assessment constraints, canonical authoringIntent, and ordered existing LMS operations. The scaffold is strictly no-write and never includes answer keys. Preserve its intent in the course draft so local validation, remote validation, publishing, and Preview evaluate the same intended workflow.

Preview the real learner experience

Use LMS Preview against the exact course revision or published version. Hosted visual proof can render desktop and mobile PNGs plus ARIA, diagnostics, and a provenance manifest without a local browser. Test only supported typed interactions, then optionally share an observe-only link with a signed-in employer organization member. Preview is isolated: it creates no assignment, Project To-do, attempt, notification, or reporting row.

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.

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.

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.

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 canonical draft records the corresponding authoring intent:

Validation intent	Completion policy	Meaning
`INDIVIDUAL_MASTERY`	`SYSTEM`	Automatic one-module mastery. Requires at least one required auto-graded question and disallows manual questions.
`STANDARD`	`EMPLOYER_REVIEW`	Standard course validation with an employer decision after submission.

OpenTrain rejects INDIVIDUAL_MASTERY + EMPLOYER_REVIEW as a typed contradiction. Draft checkout, diff, push, publish, and Preview preserve the declared intent; an explicit request override is reported rather than silently rewriting it.

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.

Ask OpenTrain