quiz argument order: explanation before correctAnswer — reasoning precedes the pick (owner ruling, 2026-09-25)

src/agent/prompts/shared/20-question-tools.md

@@ -11,7 +11,7 @@
 - `quiz` is GRADED; `ask_user_question` is not. If the question has a correct answer, use `quiz`. If you just need a preference, decision, or open-ended input, use `ask_user_question`.
 - `correctAnswer` is REQUIRED and is the option value, not a position number. Single-select: one string (e.g. "mercury"). Multi-select: an array of strings (e.g. ["belize", "niue"]).
 - Always pass the option's `value` string as `correctAnswer` — it is self-checking and prevents miscounting positions. A value that matches no option is a hard error.
-- `explanation` is REQUIRED — always say why the correct answer is correct.
+- `explanation` is REQUIRED — always say why the correct answer is correct. It comes BEFORE `correctAnswer` in the call by design: reason it out first, then commit the answer the reasoning supports.
 - Multi-select is graded as an exact-set match: he is correct only if he selects every correct option and no incorrect ones.
 - There is no free-text mode. An "I don't know" choice is ALWAYS added automatically — provide ONLY the real, gradable options (at least two). Never add your own uncertainty/opt-out option like "I don't know", "I'm not sure", or "Not sure"; that is handled for you and a manual one would be redundant or gradable-as-wrong.
 - If a result comes back as dontKnow, he honestly did not know and did NOT guess — treat it as a genuine knowledge gap, not as a wrong answer.

src/core/question-core.ts

@@ -127,6 +127,17 @@ export const quizInputBase = z.object({
 		.boolean()
 		.optional()
 		.describe("Set to true when more than one option is correct and the learner must select all of them."),
+	// Argument-order ruling (owner, 2026-09-25): the explanation is REASONING,
+	// and reasoning happens BEFORE the answer is chosen — models emit tool
+	// args in schema order, so explanation sits immediately BEFORE correctAnswer.
+	// (All consumers read by key; the order is authoring guidance, nothing else.)
+	explanation: z
+		.string()
+		.describe(
+			"REQUIRED. Explanation revealed AFTER the learner answers (shown whether they got it right or wrong). " +
+				"Use it to reinforce why the correct answer is correct. It is written BEFORE correctAnswer by design: " +
+				"reason it out first, then commit the answer the reasoning supports.",
+		),
 	correctAnswer: z
 		.union([z.string(), z.array(z.string())])
 		.describe(
@@ -136,12 +147,6 @@ export const quizInputBase = z.object({
 				"Always pass the value, not a position number — this is self-checking and prevents miscounting. " +
 				"A value that matches no option fails validation and the call is returned to you to fix.",
 		),
-	explanation: z
-		.string()
-		.describe(
-			"REQUIRED. Explanation revealed AFTER the learner answers (shown whether they got it right or wrong). " +
-				"Use it to reinforce why the correct answer is correct.",
-		),
 	details: z.string().optional().describe("Optional extra context or instructions shown under the question."),
 });