Source: instructional-designer pedagogy review, docs/reviews/2026-06-13-pedagogy-review.md (Part 2, item #2 — rated High impact / High feasibility, near-term).
User story
As a tutorial author, I want guidance — and gentle automated nudges — on writing narration that teaches, so my tutorials don't just demonstrate clicks but actually train people. Today narration is documented in a single sentence (docs/writing-tutorials.md:29) and the tool gives no help writing a line that teaches.
Two parts
A. Docs: "Writing narration that teaches" (documentation)
Add a section to docs/writing-tutorials.md (right after the one-line narration bullet at :29) covering the evidence-based principles the engine already supports but never names:
- One idea per step (segmenting).
- Explain the why, not only the what (the example already models this —
packages/example-app/tutorials/getting-started.tutorial.ts:30 — but the docs never extract it as a principle).
- Use signaling language ("notice…", "here…").
- Open with an objective, close with a recap.
- Write for the ear: short sentences, no on-screen-prose-style text (preserves the modality principle the tool honors silently).
- Name what and where, never bare "click here" (also serves sound-off / low-vision learners).
B. Optional germane lints (enhancement)
Extend the existing load-time validation in validateTutorial() (packages/core/src/spec.ts:21-60), which already runs before any browser launches and already emits logger.warn for suspicious narration. Add warning-level (never fatal) lints:
- Over-long narration for a single step (overload / segmenting) — warn above a configurable word/char threshold.
- Step bundling multiple unrelated instrumented actions in one
run() (segmenting) — best-effort; may be hard to detect statically, scope accordingly.
- Missing intro/recap step (advance-organizer / summary) — heuristic, low-confidence; consider gating behind an opt-in strict mode.
Acceptance criteria
Open decision (for maintainer)
Which lints are on by default vs. opt-in strict mode. Recommend: over-long-narration on by default (objective, high signal); intro/recap-missing behind opt-in (heuristic, noisy).
Source: instructional-designer pedagogy review,
docs/reviews/2026-06-13-pedagogy-review.md(Part 2, item #2 — rated High impact / High feasibility, near-term).User story
As a tutorial author, I want guidance — and gentle automated nudges — on writing narration that teaches, so my tutorials don't just demonstrate clicks but actually train people. Today narration is documented in a single sentence (
docs/writing-tutorials.md:29) and the tool gives no help writing a line that teaches.Two parts
A. Docs: "Writing narration that teaches" (documentation)
Add a section to
docs/writing-tutorials.md(right after the one-line narration bullet at :29) covering the evidence-based principles the engine already supports but never names:packages/example-app/tutorials/getting-started.tutorial.ts:30— but the docs never extract it as a principle).B. Optional germane lints (enhancement)
Extend the existing load-time validation in
validateTutorial()(packages/core/src/spec.ts:21-60), which already runs before any browser launches and already emitslogger.warnfor suspicious narration. Add warning-level (never fatal) lints:run()(segmenting) — best-effort; may be hard to detect statically, scope accordingly.Acceptance criteria
docs/writing-tutorials.md.validateTutorial(), with a documented, configurable threshold.validateTutorial().Open decision (for maintainer)
Which lints are on by default vs. opt-in strict mode. Recommend: over-long-narration on by default (objective, high signal); intro/recap-missing behind opt-in (heuristic, noisy).