From 35154711139f74000d9513801c8bc02b355a5a85 Mon Sep 17 00:00:00 2001 From: Daniel Bejarano Date: Tue, 2 Jun 2026 08:03:10 -0600 Subject: [PATCH] DOJ-4810: give workbook-generate creative latitude (kit as vocabulary, not script) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Guidance-only rebalance (skill + command); no template/architecture change. V1 optimized for consistency/reliability — this leaves room for concept-specific creativity without touching the invariants (brand, a11y, nav, standalone). - content->component mapping reframed as heuristics + explicit anti-monotony - new "Invariant frame vs creative payload" section: lock brand/a11y/nav/ standalone; vary prose, what diagrams depict, component choice/composition - "kit is a floor, not a ceiling" — author bespoke inline SVG/CSS freely; narrow the JS anti-pattern to fragile *stateful* widgets only (not a ban on static/SVG/CSS creativity) - Phase 4.5 variety/fit self-check before saving - "monotony" added as an explicit anti-pattern No workbook-base.html change. CI lint green; voice-neutral. Created by Claude Code on behalf of @daniel Co-Authored-By: Claude Opus 4.8 (1M context) --- commands/workbook-generate.md | 30 ++++++++++++++++++-- skills/workbook-generate/SKILL.md | 47 +++++++++++++++++++++++++++++-- 2 files changed, 71 insertions(+), 6 deletions(-) diff --git a/commands/workbook-generate.md b/commands/workbook-generate.md index d970c11..646223b 100644 --- a/commands/workbook-generate.md +++ b/commands/workbook-generate.md @@ -98,9 +98,16 @@ Interactivity must either teach by being *felt* (knobs, diagrams, reveals) or *close the loop* (export). Never add a widget that captures an answer and does nothing with it — V1 persists nothing. -Only use a component the resolved spec's `workbooks.components` enables (or the -neutral defaults when that key is absent). Interactivity must earn its place — -prefer one well-chosen block per concept over decorative ones. +These mappings are **heuristics, not a lookup table** — pick the representation +that best illuminates each concept and **vary across the course** (don't render +the same component for every section). Honour the consumer spec's +`workbooks.components` toggles, but the kit is a **floor, not a ceiling**: when a +concept needs a visualization the kit lacks, **author it directly** (inline +SVG/CSS within the design tokens + a11y contract). Reserve the "compose from the +tested kit" discipline for fragile *stateful JS* — static/SVG/CSS creativity is +encouraged. Interactivity must earn its place; prefer one well-chosen block per +concept over decorative ones. See the skill's "Invariant frame vs. creative +payload" and "The kit is a floor, not a ceiling". ## Phase 4 — Generate the standalone HTML @@ -130,6 +137,23 @@ prefer one well-chosen block per concept over decorative ones. 7. **State is in-memory only** — wire the completion event as a fire-only hook; do NOT add `localStorage`, `postMessage`, or any persistence. +## Phase 4.5 — Variety / fit self-check (before saving) + +Before writing the file, review the draft against monotony — the goal is a +workbook tailored to *this* course, not a template fill: + +- Would **two different courses** produce visibly different workbooks, or the + same shell with the text swapped? If the latter, rework the weakest sections. +- Did you **default to the same component** for every section of a given type + (e.g. every comparison rendered identically)? Vary the representation. +- Is each visualization the **best for its concept**, or just the easy mapping? + If a concept would be clearer as a bespoke inline-SVG figure the kit doesn't + have, author it (within the design tokens + a11y contract). +- Did interactivity **earn its place**, or is it decorative? + +This is a quality pass on the *creative payload* only — the invariant frame +(brand, accessibility, navigation, standalone rules) stays exactly as generated. + ## Phase 5 — Save & report 1. **Save**: diff --git a/skills/workbook-generate/SKILL.md b/skills/workbook-generate/SKILL.md index cdeedf7..7c96a85 100644 --- a/skills/workbook-generate/SKILL.md +++ b/skills/workbook-generate/SKILL.md @@ -182,7 +182,13 @@ grammar is stable across a course (stable grammar = lower cognitive load). ## Content-shape -> component mapping (the pedagogical core) Read the reading's prose and promote it into the component whose shape fits. -There is no rigid formula; the content determines the form. Heuristics: +**These are heuristics — starting points, not a lookup table.** Don't map +mechanically (every table → the same chart). Pick the representation that best +illuminates *this* concept, and **deliberately vary across a course**: if three +sections each hold a comparison, they should not become three identical +diagrams — find the angle each one needs. Monotony (every workbook the same +shell with swapped text) is a failure mode, not a success criterion. With that +framing, the heuristics: - **Course** -> module **chapters** (ordered by module directory), with a **table of contents** and course-level **progress**. @@ -215,6 +221,35 @@ earn its place — one well-chosen interactive block per concept beats five decorative ones. Long readings get chaptered and made collapsible so the single-file artifact stays navigable. +## Invariant frame vs. creative payload (where the latitude is) + +The base constrains the **frame**, not the **ideas**. Keep one set of things +identical across every workbook; let the other set differ freely per concept and +course: + +- **Invariant (always the same):** brand tokens (palette/typography), the + accessibility contract, the navigation/flow shell (TOC, progress, module + chunking), and the standalone / no-CDN technical rules. Consistency here is the + point — don't reinvent it. +- **Creative (should differ — make it differ):** the prose and explanations, the + analogies and examples, **what each diagram actually depicts**, *which* + components appear and how they're composed, chart data, comparison axes, knob + parameters, simulation design. Two different courses should produce visibly + different workbooks — not the same skeleton with the text swapped. + +### The kit is a floor, not a ceiling + +The component kit is the reliable, tested baseline — **not the limit of what you +may build.** The biggest creative surface is **inline SVG**: the kit gives you +the styling shell (`.wb-figure`, brand colors, arrow markers), but *what the +figure depicts* — a hashing ring, a token-bucket, a state machine, a spatial +layout unique to the concept — is yours to author. When a concept needs a +visualization the kit doesn't have, **author it directly** with inline SVG/CSS, +honoring the design tokens + accessibility contract. Bespoke **static / SVG / CSS** +visualization is encouraged. The only thing to avoid is fragile, untested +**stateful JS** widgets — those should be added to the kit deliberately (and +tested), not improvised per page. + ## Consuming the consumer spec (`instruction-bundle-spec.yaml`) The workbook's brand + structural vocabulary comes from the consumer's @@ -281,8 +316,14 @@ never crash. template. Brand lives in the consumer spec. - Hardcoding the component catalog or step patterns here instead of reading them from the spec. -- Freeform per-concept JavaScript. Compose from the kit; extend the kit - deliberately (and test it) when a concept truly needs something new. +- Fragile, untested **stateful JS** widgets improvised per page. Compose + stateful interactivity from the tested kit, and extend the kit deliberately + (with tests) when a concept truly needs a new interaction. (This is *not* a + ban on creative static / SVG / CSS visualization — author those freely; see + "The kit is a floor, not a ceiling.") +- **Monotony.** Mapping every content type to the same component so every + workbook is one shell with swapped text. Vary the representation to fit each + concept; two different courses should look visibly different. - Decorative interactivity. Every widget must teach something the prose alone could not convey as well. - **Capture-to-nowhere widgets.** Do not add inputs that record a learner's