OverviewHow It WorksQuickstartGlossaryCourse Creation GuideCourse SchemaBrand SchemaReview GateDesign GuideCLI ReferenceMCP ServerKnowledge GraphMastery LearningAdaptive DiagnosticsSpaced RepetitionTask SelectionGamificationLearning StaircaseBilling

Review gate

A course must pass 10 automated checks before publication. A score of 10/10 means these checks passed. Review the teaching, answers, and factual accuracy against your sources before you publish.

How review works

Run the review locally with the CLI or the graspful_review_course MCP tool. The server runs the same checks when you request publication.

graspful validate course.yaml
graspful review course.yaml

# Inspect the result and failures in automation
graspful review course.yaml --format json

A draft may contain empty concepts while you author it. Publication requires teaching content, answerable questions, and completed concepts. Replace scaffold placeholders before you request publication.

If publication fails, inspect the returned failures and keep working on the draft. Confirm published: true in the server response before sharing a course as published.

The 10 checks

This list comes from the same shared registry as the course reviewer.

  1. yaml_parses

    Course structure and problem answers match the shared schema.

    How to fix: Fix schema errors. Choice answers use valid zero-based indices; other types must match their answer contract.

  2. unique_problem_ids

    Every problem has a unique ID across the course.

    How to fix: Use a distinct concept, knowledge point, and problem prefix for each problem ID.

  3. publication_readiness

    Every concept has teaching content. Names, questions, answers, and teaching contain no known scaffold markers.

    How to fix: Author each concept, add at least five words of teaching per knowledge point in instruction or callout content, and replace placeholder text. Draft scaffolds can still validate.

  4. question_deduplication

    Questions at the same difficulty have distinct normalized text.

    How to fix: Write distinct problem variants instead of repeating the same question at the same difficulty.

  5. difficulty_staircase

    Each concept has problems at two or more difficulty levels.

    How to fix: Include easier and harder problems. Problems without a difficulty use the import default of 3.

  6. problem_teaching_alignment

    A vocabulary check flags knowledge points whose questions all appear unrelated to the teaching path.

    How to fix: Teach the material tested by the questions in this knowledge point, earlier knowledge points, or its prerequisites. Check factual and teaching accuracy against your sources separately.

  7. problem_variant_depth

    Each knowledge point has at least three problems.

    How to fix: Add at least three answerable problem variants for each knowledge point.

  8. instruction_formatting

    Instructions longer than 100 words include content blocks.

    How to fix: Split long prose into smaller knowledge points or add useful content blocks.

  9. worked_example_coverage

    At least half of authored concepts include a worked example.

    How to fix: Add a worked example, in text or content blocks, to at least half of the authored concepts.

  10. import_dry_run

    Concept and knowledge point IDs are unique in their scopes, and prerequisites exist without cycles.

    How to fix: Resolve duplicate IDs, unknown prerequisite references, and prerequisite cycles.

What the score means

The score counts automated checks that passed. It does not measure a learner's mastery or establish that every fact and explanation is correct. Vocabulary alignment is a heuristic. It can miss ambiguous, misleading, or poorly taught questions.

Read warnings as well as failures. Warnings, such as missing key-prerequisite links, can identify improvements even when the publication checks pass. Import can also fail for account permissions, conflicting course IDs, or service errors.