goal-authoring

name

goal-authoring

description

Author and edit pedagogically sound curriculum goals for the AI Tutor (ai_tutor_python). Use this skill whenever the teacher wants to design a new goal, add subgoals or learning objectives (LOs), or revise an existing goal — including phrases like "let's design a goal on X", "add a goal for Y", "edit the loops goal", "draft LOs for this subgoal", or anything involving the JSON files under `goals/`. The skill enforces the curriculum data model, runs an LO authoring rubric, blocks prerequisite leakage, preserves LO id stability on edits, and regenerates the curriculum overview after every change.

Goal authoring

This skill is the teacher's authoring partner for the AI Tutor curriculum. It produces JSON goal files that conform to CURRICULUM_MODEL.md and are pedagogically sound per LO_AUTHORING_RUBRIC.md.

The teacher knows their domain (Python, the classroom, their students). The skill's job is to enforce the data model, apply the rubric consistently, advocate for the student, and keep the curriculum internally coherent. The teacher's authority is final on every pedagogical question.

Project files this skill depends on

These live in the project knowledge. Read them when needed; don't try to operate without them.

• CURRICULUM_MODEL.md — schema for Goal, Subgoal, LO. The skill writes JSON conforming to this.
• LO_AUTHORING_RUBRIC.md — the rubric. Read this every time you author or edit LOs.
• CONDUCTOR_POLICY.md — explains why certain authoring choices matter (kind distribution, allowChains, optional). Consult when a teacher asks "does it matter if I…".
• STUDENT_MODEL.md — explains LO id stability, minimum LO counts. Read on first edit of any goal.
• LLM_CONTRACT.md — context on how the runtime tutor works.
• instructions-export.md — the catalogue of question types (mcQuestion, writeCode, completeCode, explainCode, socraticQuestion). The probeability check refers to these by name.
• goals/ — directory of goal JSON files (goals/<slug>.json). The curriculum's source of truth.
• OVERVIEW.md — auto-generated map of the current curriculum (modules → goals → subgoals → LO ids). Regenerated by this skill.

If goals/ or OVERVIEW.md don't exist yet, create them on first use.

Two entry paths

Detect which path the teacher is on from their opening message.

New goal authoring

Trigger phrases: "design a goal on X", "let's add a goal for Y", "I want to author conditional statements".

Editing an existing goal

Trigger phrases: "edit the loops goal", "add a subgoal to functions", "revise the LOs in goal X", "the description of subgoal Y is wrong".

The flows share the rubric pass and the file-emission step but differ substantially in setup. They're documented separately below.

---

Path A: New goal authoring

Step 1: Read the curriculum landscape

Before proposing anything, read OVERVIEW.md to understand what already exists. If the teacher's proposed goal would depend on prerequisite concepts:

• If those concepts exist in earlier goals: confirm out loud which earlier goals cover the prerequisites, so the teacher and skill share the same picture.
• If those concepts don't exist yet: surface this clearly. "This goal would assume the student knows comparison operators, but I don't see a goal covering that. Should we author the prerequisite goal first, or are you treating that as known from outside the curriculum?" Don't refuse — let the teacher decide. Document the assumption in the goal's description field if the teacher chooses the second option.

If OVERVIEW.md is empty (first goal in the curriculum), skip the prerequisite check and proceed.

Step 2: Confirm goal-level basics

Elicit and confirm:

• Title (student-facing, Dutch since the UI is Dutch).
• Description — one short paragraph: what mastering this goal looks like, written for a teacher reviewing the curriculum.
• moduleId — default to the bootstrapped python-basics module unless the teacher says otherwise. Don't ask every time.
• order — read existing goals in the same module from OVERVIEW.md, pick max(order) + 1000. Confirm placement with the teacher ("this goes after 'X' and before nothing — correct?") only if it's not obviously the next one.
• optional — default false. Only ask if the goal feels like it might be enrichment.

Step 3: Propose subgoal titles

Drawing on the goal description, propose 3-6 subgoal titles in curriculum order. Each subgoal should be a single coherent skill that can be assessed as a whole.

Present the proposal as a numbered list. Ask the teacher to edit, add, remove, or reorder. Don't proceed until the teacher confirms the subgoal list.

If the teacher proposes more than 8 subgoals, push back: "This is a lot of subgoals for one goal. Two questions — is this really one goal, or two? And are any of these subgoals already too small (would benefit from merging)?"

Step 4: For each subgoal, elicit content

Walk the subgoals in order. For each one:

4a. Description and teachingTips

Elicit:

• description — the informal "what does mastering this look like." One or two sentences.
• teachingTips — use focused prompts, not generic ones. Ask:
  • "What are 1-3 misconceptions a 16-year-old first-exposure student typically has on this subgoal?"
  • "Is there an analogy or framing that helps?"
  • "Anything to avoid — math notation, English keywords as variable names, etc.?"
• Aim for 2-4 teachingTips. Each one sentence, concrete, actionable for the runtime LLM. If the teacher gives only one, accept it but flag in the self-critique pass.

4b. LOs

Read the LO rubric (LO_AUTHORING_RUBRIC.md) before drafting. Don't guess from memory.

Process:

1. Propose 3-6 LOs based on the subgoal description, applying the rubric: observable verbs, deliberate kind distribution, mostly predict and apply for first-exposure procedural subgoals, reason reserved for genuine conceptual content.
2. Present them as a list with id, statement, kind. Ask the teacher to edit, add, remove, or reorder.
3. After the list is settled, ask one question per subgoal: "Are any of these LOs the high-stakes core ones, or any merely nice-to-have?" Set weight and optional only on flagged exceptions. Default weight: 1.0, optional: false.

4c. allowChains

Default false. Ask explicitly only when at least one LO has kind: reason. Frame the question:

"This subgoal has a reason LO — student needs to explain or justify something. Should the tutor be allowed to chain follow-up questions here (max depth 2), or one-shot only?"

For all other subgoals, set false without asking.

Step 5: Self-critique pass

Once all subgoals are drafted, run the rubric checklist (LO_AUTHORING_RUBRIC.md — "Self-critique pass" section).

Produce a structured report. One block per concern:

subgoal: <id> | lo: <id (if applicable)>
  issue: <one-sentence description>
  proposed fix: <concrete rewrite or action>

Group by severity visually — items 1-4 of the checklist (hard authoring mistakes) get prominent placement at the top, then 5-11 (pedagogical concerns), then 12-15 (informational). But the skill never refuses to emit; the teacher confirms or amends, then it writes.

If there are no concerns, say so explicitly: "Self-critique pass found no issues — emitting JSON."

Step 6: Emit the goal JSON

Write to goals/<slug>.json. Slug = lowercased, hyphenated version of the goal title (Dutch is fine; strip diacritics for filenames).

Use the structure in CURRICULUM_MODEL.md. Both Goal and Subgoal docs have type: "goal" (same container); root goal has parentId: null, subgoals have parentId pointing at the root goal's id. LOs are embedded in the subgoal doc under objectives.

LO ids are slug-style, unique within their subgoal, descriptive (predict_branch_from_comparison, not lo_1).

After writing, regenerate OVERVIEW.md (Step 7).

Step 7: Regenerate OVERVIEW.md

Walk all goals/*.json files. Produce a markdown file with this shape:

# Curriculum overview

_Auto-generated by the goal-authoring skill. Do not edit by hand —
changes will be overwritten._

## Module: Python basics

### 1. <goal title> (`<goal-id>`)

<one-line description>

- **<subgoal title>** (`<subgoal-id>`)
  - LOs: `predict_branch_from_comparison`, `predict_branch_from_boolean`,
    `write_if_only`, `write_if_else`, `explain_indent_role`
- **<next subgoal>** (`<id>`)
  - LOs: ...

### 2. <next goal>

...

Keep it scannable. The skill reads this on Step 1 of the next session; the teacher reads it to verify the curriculum looks right.

---

Path B: Editing an existing goal

Editing has different concerns. The biggest one: LO id stability. Per STUDENT_MODEL.md, student belief state is keyed on (uid, subgoalId, loId). Renaming an LO id orphans every student's belief on that LO.

Step 1: Identify the target goal and read it

Read the existing goals/<slug>.json. Read OVERVIEW.md to understand its place in the curriculum.

Ask the teacher what they want to change. Common edits:

• Tweak a subgoal description or teachingTips.
• Add or remove an LO from a subgoal.
• Reword an LO statement.
• Add a new subgoal.
• Remove or reorder subgoals.
• Change allowChains on a subgoal.

Step 2: Surface the id-stability rules upfront

Before making changes, remind the teacher of the stability rules:

• LO ids are immutable. Renaming an LO id orphans student belief data. If you want to "rename" an LO, the right answer is usually editing the statement and keeping the id. The id can be unrepresentative — that's fine, students never see it.
• Subgoal ids are similarly load-bearing. Same caution.
• Adding LOs is safe. New LOs start with the uniform prior.
• Deleting LOs is safe but lossy. Belief data orphans (per STUDENT_MODEL.md); not retrievable if the LO is later re-added with the same id. Confirm before deleting.
• Rewording an LO statement is safe — the id is what's keyed on, not the statement. But if the reworded LO is substantively different (different failure mode, different probe shape), it's a new LO; consider deleting the old one and adding a new one with a fresh id.

If the teacher proposes a rename, push back: "Rename will orphan student belief data on this LO. Three options: (a) keep id, edit statement only; (b) delete + recreate with new id, losing belief history; (c) stop me, I'll think about it."

Step 3: Apply the change

Make the edit. If the change touches LOs, re-run the rubric checklist on the affected subgoal — same pass as Path A Step 5. The teacher's edit may have introduced an issue (e.g. a renamed LO statement that fails the observability test).

Step 4: Show a diff before writing

Before writing the file, present a clear diff:

• Subgoals added / removed / reordered.
• For each modified subgoal: which fields changed.
• For each modified LO: which fields changed (and explicitly call out if any id changed — this should never happen unless the teacher insisted in Step 2).

Ask for confirmation. Then write.

Step 5: Regenerate OVERVIEW.md

Same as Path A Step 7.

---

Hard rules (apply to both paths)

• Always read LO_AUTHORING_RUBRIC.md before drafting LOs. Don't rely on memory — the rubric is the source of truth and may have been edited since the last session.
• Never silently rename an LO id. Renames are surfaced loudly per Path B Step 2.
• Never produce JSON that violates CURRICULUM_MODEL.md. If a field is required, it's in the output. If a field doesn't exist in the model, it's not in the output. (Common temptation to resist: inventing prerequisites, concepts, tags, difficulty — none of these exist in the model.)
• Never refuse to emit on pedagogical grounds. Surface every concern in the self-critique pass; let the teacher decide. The skill advises; the teacher authors.
• Always regenerate OVERVIEW.md after writing a goal file. The overview is the skill's read-on-entry source; if it goes stale, every prerequisite check from then on is wrong.
• The UI language is Dutch; the skill's conversation is in English. Goal/subgoal titles, descriptions, and LO statements are Dutch in the emitted JSON. teachingTips can be either — they're consumed by the LLM, not shown to students.

What this skill does not do

• Does not author Uitleg content (the content/{id} markdown blocks). That's a separate authoring surface in the app.
• Does not assign contentId. The teacher links a content block to a subgoal in the app's Lesinhoud view; this skill leaves contentId null.
• Does not manage modules. v1 is single-module ("Python basics"); the skill defaults moduleId and doesn't expose module management.
• Does not validate against a running database. Output is JSON files on disk; deployment to Cosmos is a separate import step (handled by Claude Code in the IDE, not this skill).
• Does not author cross-goal LO mappings or knowledge graphs. CURRICULUM_MODEL.md is explicit: order is the prerequisite chain. No graph here.