01-projects/printables-product

recommended playsets spec

·spec·status: draft
printablesscribble-worksproductplaysetsspec

Recommended playsets — build spec

Founder ruling (2026-09-01 iMessage): "Games are our unit. Playsets are generated on demand. We could add premade recommended playsets that we roll up for parents. Particular themes, particular skills focus, etc." Replaces pack pages as the curated-collection surface (queue rulings block; R1 retires /packs/ as browsing).

One sentence: a recommended playset is 6 curated game slugs plus a parent-facing blurb, stored as a flat file in the repo, rendered as cards on Home and Browse, and tapping one seeds the existing playset-builder tray pre-filled — from where the parent can swap games and download the same 7-page PDF (title page + 6 games) the builder already produces.

1. Data shape

New file: src/data/recommended-playsets.yaml (flat file in git, no database — tier-1 rule "adding one is premature" holds; this is catalog metadata exactly like meta.yaml).

version: 1
playsets:
  - slug: back-to-school          # stable ID; URL-safe; never renamed, only retired
    title: "First Day of School"
    kind: theme                    # theme | skill — which roll-up axis this set sells
    blurb: >-                      # parent-facing, 2-3 sentences: what's inside and
      ...                          # what the child practices. The §3 title-page test
                                   # applies: if this can't be written without
                                   # hand-waving, the set doesn't ship.
    tags:
      themes: [everyday_life]      # taxonomy theme keys (may be empty)
      skills: [numbers_counting, writing_tracing, letters_phonics]  # taxonomy skill keys
    games:                         # EXACTLY 6 slugs, order = print order
      - count-school-supplies
      - trace-abc
      - first-sounds
      - star-dot-to-dot
      - trace-the-shapes
      - build-the-word
    status: live                   # draft | live — draft renders nowhere
    created: '2026-09-01'

Build-time validation (extend scripts/validate-taxonomy.mjs or a sibling validate-playsets.mjs, wired into the same prebuild):

Loader: loadRecommendedPlaysets() in src/lib/games.js (or a small playsets-recommended.js — do NOT touch the retiring packs.js), joining each slug to its full game record so cards render titles/previews without duplication.

2. Where they surface

3. Seeding the builder

Tap → the existing tray (src/scripts/playset.js, sw.playset.v1 localStorage state) is pre-filled with the 6 slugs and the playset title as the tray name.

4. Relation to on-demand playsets and the magic wand (item 19)

Three rungs of the same tray, no duplicated machinery:

Surface What fills the tray Mechanism
Hand-built (shipped, PR #4) Parent picks 6 games Browse + tray
Recommended (this spec) Editor curation, static data Flat file → seed the tray
Magic wand (item 19) Curriculum-aware auto-fill of EMPTY slots (age band + skill balance + kid's interests) Gen-AI, runtime

Recommended playsets are deterministic curation, zero gen-AI, zero credits — the trust-ladder rung below the wand (manual → Customize → wand). They compose rather than compete: seed a recommended set, remove two games, and the wand refills the holes. The wand spec should treat a seeded recommended set as ordinary tray state — nothing here needs to know the wand exists. (Later, curated sets are natural few-shot exemplars for the wand's balance logic — note for item 19's spec, not scope here.)

5. Authoring workflow

6. Launch candidates (real slugs, 14-game catalog as of 2026-09-01)

  1. First Day of School (theme) — count-school-supplies, trace-abc, first-sounds, star-dot-to-dot, trace-the-shapes, build-the-word. Seasonal NOW. Blocked on count-school-supplies clearing pending-review (PR #8); validator will hold it until then — correct behavior, not a bug.
  2. Primeros Pasos — bilingual reading (skill) — sonido-inicial, silabas-de-m, construye-la-palabra, une-la-palabra, first-sounds, word-and-picture. All 4 Spanish games plus two English mirrors. The true pairs are sonido-inicial/first-sounds and une-la-palabra/word-and-picture; silabas-de-m has no English mirror and construye-la-palabra's mirror (build-the-word) is not in this set, so the blurb sells the two real pairs, not blanket mirroring (the §5 blurb-honesty gate will hold it to that). Multilingual as engine property, not Spanish positioning.
  3. Learning to Read (skill: letters_phonics + reading_words, EN) — first-sounds, trace-abc, build-the-word, word-and-picture, trace-the-shapes, star-dot-to-dot. First 4 are the spine; last 2 are labeled stretch picks (pencil control + counting breather between reading games), and the blurb must say so honestly.
  4. Pencil Ready — fine motor (skill: writing_tracing + scissors_motor_skills) — trace-abc, trace-the-shapes, star-dot-to-dot, bunnys-snack-maze, color-the-dino, count-school-supplies (traces the number; same pending-review dependency, swap who-eats-what if launching before it clears). Note: color-the-dino carries neither claimed skill tag; it rides as an art/coloring breather, and the set's claimed tags stay validator-true because the honesty check requires each tag on at least one game, not on all six.
  5. Rainy-Day Low-Ink (practical roll-up) — bunnys-snack-maze, color-the-dino, star-dot-to-dot, trace-abc, trace-the-shapes, who-eats-what. Exactly the 6 low_ink games in the catalog: a real parent problem (printer ink) the flags facet was built for. Note: kind is neither theme nor skill; either allow kind: practical or drop this set (open question 3).

Sets the catalog CANNOT roll yet (a finding, not a failure): a numbers-focus set (only 2 numbers_counting games) and an animals theme set (only 3 animals/creature games). The recommended-playsets surface doubles as a gap detector for the P1 new-game lane: product should bias upcoming game picks toward completing the nearest unrollable set. That loop, curation demand pulling game production, is the cheapest version of the charter's named queue-prioritization gap.

7. Open questions for the founder

  1. Language facet. Taxonomy has no language facet (facet count frozen at 5, founder-locked). The bilingual set works by hand-curation, but Browse can't filter Spanish and the validator can't check language claims. Add language as facet 6 (founder decision by the freeze rule), or leave language as engine-property-only?
  2. Home card cap — is 4 recommended sets on Home right, and do seasonal sets always take slot 1?
  3. Is kind: practical allowed (the low-ink set), or do recommended sets stay strictly theme/skill per the ruling's wording?
  4. Shareable playset URLs — seed-only (this spec's default, avoids recreating pack pages), or does a recommended set deserve a stable URL for sharing/SEO? Growth may want the latter eventually; deferrable.
  5. Gap-driven game picks — greenlight product biasing the P1 lane toward completing the numbers and animals sets?

Build order

R2 (this spec) → R3 design round (card/row) + §1 data file & validator + §3 seed function in one engineering round → launch candidates 2, 3, 5 immediately; 1 and 4 when count-school-supplies goes live.

Related