Skip to main content
Home / Documentation / Product Definition & User Journeys
Product Vision

Product Definition & User Journeys

Core premise, target user personas, 5 core user journeys, functional requirements, and MVP boundaries.

Source in app repo: PRODUCT.md
Source in app repo: MVP.md
App version: v1.4.0
Licence: GPL-3.0

Product Definition

1. Vision & Core Value

Chess Repertoire SRS is a focused, local-first chess learning application for memorizing and retaining opening and middlegame repertoires through active spaced repetition.

The core premise:

Show the player a position from their own repertoire and ask them to play what they have learned.

The application is not a general tactics trainer, an engine analysis cockpit, or a social network. Its purpose is to turn a player's curated repertoire material into instant, reliable, retrievable memory.

2. Target Users

3. Core User Journeys

Journey 1: Daily Repertoire Review (Default)

  1. User opens the application.
  2. The app immediately presents the chessboard on the first due position across all active imported studies.
  3. User recalls and makes their prepared move on the board. (Crucial: move comments and annotations are strictly hidden during recall to prevent move spoilers).
  4. If correct: subtle positive feedback, automatic traversal through already-learned opponent/user continuations, and stopping at the next due decision. Any explanatory move comment is revealed post-move. (With Line continuity set to Full line instead: every line is played whole from its first move to its last, even when steps are not yet due, and a lapse acknowledged without retry continues down the same line.)
  5. If incorrect: non-blocking feedback indicating the expected repertoire continuation with an on-board arrow, recording a lapse, and keeping the board interactive so the user can immediately reguess and play the correct move.
  6. User reviews as long as they wish; when all items are up to date, a calm idle state is displayed with options to explore moves or start pre-match rehearsal.

Journey 2: First Launch & PGN Import

  1. User opens the app for the very first time (zero studies exist).
  2. The app presents a clean, focused import interface.
  3. User supplies a PGN file containing one or many games/chapters with variations, comments, and annotations.
  4. The system validates chess legality, preserves full variation trees, normalizes chapters, and derives scheduled decision points.
  5. User is immediately transitioned into Review of the newly imported material (active scope automatically switches to the new study).

Journey 3: Constrained Review Scope & Opening Hubs

  1. User is preparing for a specific opening (e.g. against 1.e4) and wants to focus on their Sicilian repertoire.
  2. User opens the lightweight study/opening filter drawer.
  3. User selects a target study or an Opening Hub (e.g. "Sicilian Defense" which aggregates lines across multiple studies automatically classified by standard opening name/ECO/FEN).
  4. The Review scene updates its active pool to only test due positions matching that filter.

Journey 4: Pre-Match Rehearsal / Cram Mode (Custom Review)

  1. User has an upcoming tournament or match in 20 minutes and wants to rehearse lines in a specific repertoire.
  2. The system indicates 0 positions are due for review.
  3. User enters Rehearsal Mode for the chosen repertoire.
  4. The app actively tests the user on the board through the lines, giving feedback and reguess opportunities.
  5. Invariant: Rehearsal Mode is non-destructive — it does not update SRS intervals, increment repetitions, or record lapses in the SRS database.

Journey 5: Active Review Pool Focus (Deck Suspension)

  1. User maintains multiple repertoires over time (e.g. alternate defenses against 1.e4 or experimental openings).
  2. User toggles specific studies active or inactive in their daily review pool.
  3. The "All Studies" review queue and due count only pull from active repertoires, preventing review fatigue from sidelines not currently in play.
  4. Inactive studies remain fully accessible for individual review, explore mode, or cram mode at any time.

4. Functional Requirements

  1. PGN Pipeline:

    • Accept standard and non-standard PGNs with single or multiple games/chapters.
    • Preserve recursive annotation variations (RAVs) as first-class branching trees.
    • Support arbitrary starting FEN positions.
    • Extract move comments and NAGs without corrupting tree structure.

  2. Repertoire Training Model:

    • Training evaluates whether the player remembered their repertoire, not whether the move is engine-optimal.
    • Opponent mistakes and prepared punishments are first-class repertoire content.
    • Player decision points are derived for the user's perspective.
    • Move comments and annotations are strictly hidden during recall to prevent giving away the move, and revealed post-guess or during explore mode.
    • Mistakes allow immediate reguess on the board without modal locking.

  3. Spaced Repetition System (SRS) & Review Modes:

    • Every repertoire decision maintains its own SRS state (repetition count, lapse count, stability/interval, next due timestamp).
    • Non-due (already learned) positions are automatically traversed during review so the user is only tested on what is currently due.
    • Previously learned moves return as active testable questions once their interval elapses.
    • Scheduler algorithm is replaceable behind an abstract contract.
    • Dual review modes: Standard SRS mode (updates intervals and logs recall events) and Pre-Match Rehearsal mode (trains positions on the board without altering SRS intervals or history).
    • Studies can be toggled active or inactive in the daily review pool.

  4. Opening Hubs & Classification:

    • Openings are automatically classified from standard PGN headers (Event, ECO, Opening) or position FEN.
    • Openings form lightweight virtual review scopes aggregating lines across multiple studies without data duplication.

  5. Offline & Performance:

    • The entire review and move-validation loop is 100% local and requires zero network access.
    • Perceived interaction latency must be effectively zero (<16ms on mobile and desktop).

5. Visual Identity

ChessSRS ships its own visual identity ("Diagram"), independent of Lichess Mobile's look. The full specification lives in design/: design/docs/01-identity.md (principles and voice), design/docs/02-tokens.md (colour, type, motion), design/docs/03-components.md (component specs), design/docs/04-screens-and-flows.md (screens and states). The visual identity is intentionally decoupled from Lichess Mobile's theme — see decision D016.

Lichess Mobile remains the technical foundation only (board rendering via chessground, chess rules via dartchess, the Riverpod/domain architecture). See CUT_PROPOSALS.md for what technical foundation is kept.

6. Non-Goals (Explicit Exclusions)

7. Future Horizons (Post-MVP)

5. MVP Scope Boundaries

MVP Scope & Specifications

1. MVP Goal

Deliver a functional, local-first Flutter application (built on the Lichess Mobile foundation) that executes the complete loop:

PGN Import → Normalized Repertoire Tree → Active Review Scene → Local SRS Persistence.

2. Included Capabilities

Capability Description Status
Local PGN Import Multi-game, multi-chapter PGN import (via dartchess PgnParser) supporting recursive variations (RAVs), comments, NAGs, and starting FENs. Phase 2
Repertoire Normalization Converts PGN trees into domain Study → Chapter → repertoire tree graphs with deterministic FEN keys. Phase 2
Decision Point Derivation Derives RepertoireDecision units for positions requiring user recall (player's perspective). Phase 2
Active Recall Review Lichess-quality interactive board scene where users input moves to answer due repertoire positions. Phase 2
Move Validation Immediate local validation against expected repertoire continuation moves (any valid branch accepted). Phase 2
Automatic Traversal Automated traversal through opponent replies and already-learned user moves until the next due decision (never a permanent exclusion). Phase 2
Replaceable SRS Scheduler Scheduler contract + SimpleScheduler exponential interval ladder with lapse recovery and deterministic testing support. Phase 2
Local Persistence sqflite-backed repository storing studies, decisions, review states, and review events. Phase 2
Lichess-derived UX foundation Lichess Mobile theme, board (chessground/dartchess), navigation, settings. Phase 1

3. Excluded Capabilities (unchanged)

PRODUCT SCOPE
├── Local PGN Import               [MVP / Phase 2]
├── Recursive Variation Trees      [MVP / Phase 2]
├── Review-First Active Recall     [MVP / Phase 2]
├── Automatic Traversal            [MVP / Phase 2]
├── Replaceable SRS Engine         [MVP / Phase 2]
├── Local Persistence              [MVP / Phase 2]
├── Listudy training behaviors     [Phase 4 — isolated module]
├── chessrs scheduler behaviors    [Phase 5 — isolated module]
├── Advisory Engine Health Check   [later, isolated at import]
├── Cross-Study Opening Filter     [later]
├── Lichess study import/sync      [EXCLUDED for MVP]
├── Cloud sync / accounts / social [EXCLUDED]
└── Tactics / Social / Gamify      [EXCLUDED]

4. Acceptance Criteria (unchanged product requirements)

  1. Clean Import: Importing a PGN containing multiple chapters and nested variations produces a fully intact hierarchy where no variation branch is discarded.
  2. Deterministic Correctness: Playing a move that matches an active repertoire branch is accepted immediately; playing any other move (even legal chess moves) is marked incorrect.
  3. SRS Interval Progression:
    • A position is due only after it has been presented. New items are not due; they are introduced gradually, after due work, and only then enter the SRS ladder (SPEC INV-068).
    • Successful recalls increase the interval (1 day → 2 days → 4 days → ...).
    • Failed recalls reset the repetition streak and schedule a short-interval retry.
  4. Zero-Lag Interaction: Move legality and repertoire lookup happen synchronously in memory without blocking UI rendering.
  5. No Modal Interruptions: Incorrect moves reveal the expected line and allow progression without requiring modal dismissals.
  6. Persistence Durability: Review states and study structures survive application restarts.
  7. Runtime-Verified UX: The review scene must look and feel like a coherent Lichess-derived mobile application (runtime validation, not just tests).

5. Known Limitations (MVP)