Skip to content

Typing Pedagogy

Jump to bottom
Egno edited this page Jul 28, 2026 · 1 revision

Typing pedagogy in Keystrike

Keystrike's lesson engine, curriculum progression, and practice UI are built on research-backed typing pedagogy. This page summarizes the principles, why they work, the sources behind them, and how they map to the current implementation.

For the full internal research note (including implementation gaps and fixes), see docs/research/typing-pedagogy.md in the repo.

Core principles

# Principle Why it works
1 Touch typing over hunt-and-peck Fixed finger-to-key mapping anchored on the home row builds procedural muscle memory. Visually guided typing does not transfer to automatic, eyes-free performance.
2 Accuracy first, speed follows Pushing speed before accuracy trains error-correction habits instead of automaticity. Speed drills pay off only once error rate is already low.
3 Spaced / distributed practice beats cramming Short, frequent sessions (~15–20 min/day) outperform long infrequent ones — the general spacing effect in motor learning.
4 Deliberate practice on weak points Practice concentrated on error-prone keys, bigrams, and finger transitions — with immediate feedback — beats generic full-keyboard drills.
5 Progressive key introduction Introduce keys in small groups (home row first, expanding outward). Advance only once the current group is mastered.
6 Chunking at word / bigram level Real typing speed is bottlenecked by common letter sequences and whole words. Practice that reinforces frequent bigrams, trigrams, and words transfers better than isolated keystroke drills.
7 Immediate, specific feedback Knowing which keystroke was wrong and correcting it right away accelerates learning more than aggregate end-of-session stats alone.
8 Plateaus need varied practice After initial rapid gains, progress slows. Overcoming plateaus generally requires varying practice (new text sources, mixed difficulty) rather than repeating the same drills.

Research backing key-increment design

These sources inform Keystrike's unlock thresholds, confidence scoring, and text generation — not just generic "type more" advice.

Keybr-style adaptive progression

Keybr unlocks one new letter at a time only after the learner clears both speed and accuracy thresholds on the current set, and weights per-letter frequency in generated text from personal error/latency history. This is the closest real-world analog to Keystrike's compute_unlocked logic.

SlimStampen (ACT-R adaptive scheduling)

SlimStampen uses reaction time as a primary mastery signal (a better proxy for motor-trace strength than accuracy alone) and re-tests items right before they would be forgotten — spacing effect, not a fixed timer. This motivates weighting speed alongside accuracy and surfacing stale keys for review.

Crump & Logan (Vanderbilt) — word-level control

Typing control is hierarchical at the word level, not per-keystroke. Scrambling letters within words slows skilled typists. Transfer experiments show fastest performance on trained words, then new words made of trained letters, slowest on words with untrained letters. New keys should appear embedded in real words and bigrams, not drilled in isolation.

Structured touch-typing programs (controlled study)

A higher-ed study (with and without learning disabilities) found structured touch-typing programs significantly improved speed while accuracy stayed above 95% — validating structured training over ad hoc practice.

Row order vs. finger order for unlock sequencing

Row-based ordering (distance from home position) is the literature- and convention-backed axis for which single key unlocks next — not finger identity.

  • Reach distance: Interkey-timing research shows that for within-hand keystrokes, timing is a function of distance between keys — the farther from the resting/home position, the longer the interval. Row-tiering (home → top → bottom) captures this biomechanical effect.
  • Curriculum convention: Standard typing curricula (typing.com, how-to-type.com, etc.) converge on row-based lesson structure rather than finger-grouped structure.
  • Finger identity affects sequences, not unlock difficulty: Hand-alternating keystrokes are faster than same-hand repetitions; letter pairs split across fingers/hands predict typing speed better than repeated-letter pairs. That argues for biasing generated practice text toward hand-alternating pairs — not reordering the unlock queue by finger.

Sources:

What Keystrike implements today

The adaptive engine lives mainly in src/keystrike/domain/ and src/keystrike/application/build_lesson.py. The practice screen surfaces it in the UI.

Progressive key introduction (principles 5, 1)

learn_order.py — keyboard_order()

  • Reorders each layout's letter unlock sequence by physical row: home row first, then top row, then bottom — frequency breaks ties within a row.
  • Mirrors Keybr's "sort letters in keyboard order" setting and standard row-based curricula.
  • Punctuation and space suffix are left in layout order; row weighting applies only to letters.

confidence.py — compute_unlocked()

  • The first N keys (configurable alphabet size) are always unlocked.
  • Each subsequent key in the learn order unlocks only when every currently unlocked key meets the confidence threshold (default 1.0 = at target speed with sufficient accuracy).
  • One key at a time — incremental introduction, gated on mastery of the current set.

Accuracy-first confidence (principles 2, 4)

confidence.py — confidence_of(), accuracy_of()

  • Speed confidence = target ms/char ÷ actual mean time.
  • Final confidence = speed confidence × accuracy (samples / (samples + error_count)).
  • A key typed fast but frequently wrong scores low and cannot unlock the next key prematurely.
  • Same accuracy weighting applies to transition (bigram) confidence.

Deliberate practice on weak keys and bigrams (principles 4, 6)

confidence.py — practice_weight(), select_focus(), select_focus_transition()

  • Weak keys (low confidence) get up to 4× sampling weight in generated text; mastered keys get baseline weight.
  • select_focus() picks the weakest unlocked key for the lesson emphasis.
  • select_focus_transition() picks the weakest unlocked bigram when transition stats exist.
  • Stale-but-mastered keys get review urgency so they still appear in practice (SlimStampen-inspired spacing; fixed day-scale ramp today).

generator.py + markov.py — AdaptiveGenerator

  • Practice text is Markov-sampled words filtered to the unlocked alphabet — not isolated letter drills.
  • Language-frequency bigram/trigram tables (markov.py) produce natural chunks within the unlocked set.
  • char_weights and transition_weights from live confidence bias sampling toward weak keys and weak transitions.
  • Focus key or focus bigram is guaranteed to appear at least once in each lesson.
  • Layout-aware ergonomics boost hand-alternating and different-finger transitions during sampling.

build_lesson.py — BuildLesson

  • Orchestrates unlock → focus selection → weighted text generation for each adaptive practice session.
  • Exposes focus reason (weak, review, or transition-specific) to the HUD.

Immediate feedback and weak-key visualization (principles 7, 4)

Practice screen (practice.py) + typing_area.py

  • Per-keystroke recording with immediate visual feedback on correct/incorrect input.
  • Session stats updated live via the HUD.

kb_heatmap.py

  • Keyboard heatmap colored by per-key confidence (green / yellow / red).
  • Lesson focus key highlighted; keys due for review get a magenta underline.
  • Used on the practice screen and stats views so learners see which keys are weak, not just aggregate WPM.

Spaced practice nudge (principle 3)

review_urgency() in confidence.py

  • Keys not practiced recently ramp toward full review urgency over ~3 days.
  • Urgency increases sampling weight and lowers focus score so stale keys resurface before they are forgotten.
  • Daily learn budget settings (settings.py) support short regular sessions.

What is not fully implemented yet

  • Principle 8 (plateau variety): Text comes from language Markov tables and adaptive weighting, but there is no explicit "plateau mode" that rotates text sources or difficulty profiles when progress stalls.
  • SlimStampen-grade spacing: Review urgency uses a fixed day-scale ramp, not per-key individualized forgetting curves.
  • Touch-typing enforcement: Keystrike assumes touch typing as the goal but does not physically enforce home-row anchoring or finger assignment during practice.

Quick reference: principle → code

Principle Primary modules
Touch typing / home row learn_order.py, layout definitions
Accuracy first confidence.py (accuracy_of, confidence_of)
Spaced practice confidence.py (review_urgency, practice_weight)
Weak-point targeting confidence.py, build_lesson.py, generator.py, markov.py
Progressive unlock learn_order.py, confidence.py (compute_unlocked)
Word/bigram chunking generator.py, markov.py, bundled language tables
Immediate feedback practice.py, typing_area.py, session_use_cases.py
Weak-key visualization kb_heatmap.py, stats screen

Clone this wiki locally