8000 Implement sprint-based microstudying with study-ahead fill by jmahmood · Pull Request #20 · jmahmood/CardBrick · GitHub
[go: up one dir, main page]

Skip to content

Implement sprint-based microst 8000 udying with study-ahead fill - #20

Merged
jmahmood merged 3 commits into
masterfrom
claude/studying-ahead-plan-7cmij2
Jul 7, 2026
Merged

jmahmood merged 3 commits into
masterfrom
claude/studying-ahead-plan-7cmij2

Conversation

@jmahmood
@jmahmood jmahmood commented Jul 7, 2026
Copy link
Copy Markdown
Owner

Summary

Refactor CardBrick's study model from a single daily queue to a sprint-based microstudying system where children chip away at a daily card goal in short 5–10 minute sprints. When the due pool runs dry before the goal is met, sprints are topped up with soon-due cards pulled forward ("studying ahead"), and an optional bonus sprint is offered after the goal is reached.

Key Changes

Storage & Migration

  • Add three new profile columns: daily_goal_cards (default 150), study_ahead_days (default 1), study_ahead_enabled (default 1)
  • Bump schema version to 5 with migration that seeds daily_goal_cards from old daily_review_cards + daily_new_cards for existing profiles
  • Add ahead_candidates() query to fetch cards due soon (within the study-ahead horizon) for pull-forward fill
  • Add daily_answer_count() to track total answers logged today (not unique cards), which drives the goal budget

Service Layer

  • Replace daily_review_cards cap with daily_goal_cards in queue building; new cards still paced by daily_new_cards
  • Implement three-stage queue fill: due reviews → new cards → ahead cards (when enabled and budget permits)
  • Add sprint_status() helper returning {cards_done, cards_remaining, sprints_remaining, sprints_planned, next_sprint_cards, bonus_cards, goal} — all derived from the append-only review log
  • Update get_due_cards() to accept bonus=True flag (ignores goal budget for optional bonus sprints after goal is met)
  • Update counts_for_queue() to support bonus mode

UI (app.py)

  • Reframe screen_child_start from "X cards today" to "N sprints to go" with progress bar (cards_done / goal)
  • Show next sprint size and time estimate
  • After goal is met: celebrate and offer bonus sprint if ahead pool is non-empty; only show "Come back tomorrow" when both goal and ahead pool are empty
  • Add _sprint_label ("Sprint 3/8" or "Bonus sprint") displayed in review header
  • Update screen_review() to compute and display sprint number
  • Pass bonus=True to StudySession when starting a bonus sprint
  • Update screen_deck_select() to query counts with bonus flag

Session & CLI

  • Add bonus parameter to StudySession.__init__() (passed through to queue building)
  • Update CLI profile command: retire --daily-review, add --daily-goal, rename --session-cards/--session-minutes to --sprint-cards/--sprint-minutes, add --study-ahead-days and --study-ahead (on/off)
  • Update README with new profile examples and goal/sprint framing

Tests

  • Comprehensive test suite (test_study_ahead.py) covering:
    • Sprint accounting: status derives counts from log; partial sprints earn partial credit; undo restores counts
    • Going ahead: back-to-back sprints decrement sprints_remaining; caps never block while goal unmet
    • Ahead fill: kicks in when due+new can't fill budget; respects horizon, ordering, suspended/buried exclusion, filters; disabled cleanly
    • FSRS early review: ahead cards get valid state with due > now; Again requeues within sprint
    • Bonus sprints: offered after goal met; pool drains across repeated bonus sprints
    • Rollover: answers book to the day logged; tomorrow starts clean
    • Migration: existing profiles get sane daily_goal_cards

Notable Implementation Details

  • Log-derived accounting: All sprint math (cards_done, remaining, sprints_remaining) derives from the append-only review log, not in-memory counters — correct across undo, crashes, and restarts
  • Partial sprint credit: Quitting early only banks cards actually answered; remaining count stays honest
  • FSRS-safe early review: py-fsrs computes next state from elapsed time, so pulling a card

https://claude.ai/code/session_01BpqXQKjiwd3ogsmumtDe2j

claude added 3 commits July 7, 2026 13:41
When a child finishes their daily queue, offer an immediate follow-up
session drawing on soon-due cards (FSRS handles early reviews natively)
plus an optional bonus of new cards, gated by new per-profile parent
controls. The plan targets cardbrick-py and calls out the legacy Rust
app as out of scope.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BpqXQKjiwd3ogsmumtDe2j
The app is for microstudying: a daily card goal (e.g. 150) done in
5-10 minute sprints across the day. The plan now derives a visible
sprints-remaining count from the review log, lets back-to-back sprints
burn it down (going ahead), fills sprints from soon-due cards when the
due pool runs dry before the goal, and offers bonus sprints after the
goal is met.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BpqXQKjiwd3ogsmumtDe2j
The study day is now a card goal (daily_goal_cards, default 150)
chipped away in short sprints instead of one capped sitting:

- ReviewService.sprint_status derives cards done / sprints remaining
  from the review log; going ahead (back-to-back sprints) burns the
  count down the same as spacing them out.
- get_due_cards budgets each sprint by the goal, keeps daily_new_cards
  as new-card pacing, retires daily_review_cards from queue math, and
  tops sprints up with soon-due cards pulled forward (ahead_candidates,
  bounded by study_ahead_days) when the due pool runs dry.
- After the goal is met the start and summary screens offer an
  optional bonus sprint; the summary's bottom button rolls straight
  into the next sprint, and the review header shows Sprint n/N.
- Parent Mode's limits screen edits the goal and sprint size (with a
  live sprint count preview); the profile CLI gains --daily-goal,
  --sprint-cards/--sprint-minutes, --study-ahead-days, --study-ahead.
- Schema v5 adds daily_goal_cards, study_ahead_days,
  study_ahead_enabled, seeding the goal from the old review+new caps
  on migration.

Covered by tests/test_study_ahead.py (sprint math, ahead fill, FSRS
early review, bonus drain, migration) and a reworked test_limits.py;
verified end-to-end by driving the pygame UI headlessly through two
goal sprints, a bonus sprint, and the all-done screen.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BpqXQKjiwd3ogsmumtDe2j
@jmahmood
jmahmood merged commit 076a614 into master Jul 7, 2026
1 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

0