Guide: learner-first ledger order, example-swap framing, no-restating, Options tagging

[Carr1005]

Why

Reviewer feedback from a real build against the agent-memory course spec surfaced problems that trace back to the spec-generation guide:

1. Design/realization rows were asked before the learner's project/data/goal — the answers that give every later question its context ("rows 1-9 should be placed after the learner questions").
2. The knowledge-toolset row read as an irrelevant "arXiv tools?" question for learners building their own project — nothing said it's the course's example, expected to be swapped.
3. Two rows both read as "how many tools to retrieve, k=5" because one row restated the other's value.
4. A substituted default (SQLite+Chroma) could be presented as the course's choice because nothing marks, in the table itself, which Options entry the course actually used (Oracle).

What changed (all rules course-agnostic)

• Row order: learner → design → realization → contradicted (context first, dependents after); the §0 gate presents rows in table order, so project/data/goal answers exist before the rows that depend on them.
• Carry-forward framing: gate step 3 tells the build agent to use answers already given to frame later questions in the learner's own terms — with a guardrail: never skip a row, alter an Option, or move the "(course default)" label because of an earlier answer.
• Example-swap framing: any row whose Default is the course's example realization must say so and mark itself as expected to be swapped when the learner's project differs.
• No cross-row restating: a row never restates another row's decided value; it cross-references the owning row ("k: pinned in row N").
• Options tagging: on substitution rows, the course's own technology in Options carries the literal tag "(course default)", making build-time labeling deterministic.
• §14 pre-handoff checklist updated to audit all of the above.

(The express-lane gate and "(Recommended)"/"(course default)" labeling rules this builds on reached main earlier via #5.)

Validation

The updated guide was validated end-to-end: an isolated agent (fresh context, forbidden from reading the old spec) regenerated the agent-memory course spec from the guide + materials alone. The regenerated spec fixed every reviewer point — learner rows first, Oracle tagged "(course default)" in Options, the tool-suite row framed as a swappable course example, k cross-referenced instead of restated. The regenerated spec itself is not part of this PR; where it lands is still being decided.

🤖 Generated with Claude Code