From 8458788e7f88bb76626ffda5666d69819a32bdf8 Mon Sep 17 00:00:00 2001 From: getOffit Date: Fri, 9 Jan 2026 15:09:51 +0000 Subject: [PATCH] just some research --- .../design/detailed-design.md | 352 ++++++++++++++++++ .sop/mastery-mode-planning/idea-honing.md | 74 ++++ .../implementation/plan.md | 241 ++++++++++++ .../research/current-implementation.md | 182 +++++++++ .../research/progress-system-impact.md | 235 ++++++++++++ .../research/ui-ux-patterns.md | 174 +++++++++ .../research/word-lists-auth.md | 251 +++++++++++++ .sop/mastery-mode-planning/rough-idea.md | 25 ++ .sop/mastery-mode-planning/summary.md | 95 +++++ 9 files changed, 1629 insertions(+) create mode 100644 .sop/mastery-mode-planning/design/detailed-design.md create mode 100644 .sop/mastery-mode-planning/idea-honing.md create mode 100644 .sop/mastery-mode-planning/implementation/plan.md create mode 100644 .sop/mastery-mode-planning/research/current-implementation.md create mode 100644 .sop/mastery-mode-planning/research/progress-system-impact.md create mode 100644 .sop/mastery-mode-planning/research/ui-ux-patterns.md create mode 100644 .sop/mastery-mode-planning/research/word-lists-auth.md create mode 100644 .sop/mastery-mode-planning/rough-idea.md create mode 100644 .sop/mastery-mode-planning/summary.md diff --git a/.sop/mastery-mode-planning/design/detailed-design.md b/.sop/mastery-mode-planning/design/detailed-design.md new file mode 100644 index 0000000..965e89f --- /dev/null +++ b/.sop/mastery-mode-planning/design/detailed-design.md @@ -0,0 +1,352 @@ +# Mastery Mode - Detailed Design Document + +## Overview + +This document outlines the design for implementing a mastery-based learning mode in the Spelling Website. The mastery mode replaces the current spelling test system with a focused, repetition-based approach where students practice specific word categories until achieving deep mastery before progressing to the next category. + +## Detailed Requirements + +### Core Functionality +- **Always Active**: Mastery mode replaces the normal spelling test mode entirely +- **Category Focus**: Students practice all words in a single category until ALL words achieve mastery (15 correct attempts each) +- **Deep Repetition**: Each word requires 15 correct attempts before being considered mastered +- **Sequential Progression**: Categories unlock in sequence only when current category is 100% complete (common words 3 → common words 4 → etc.) +- **Visual Feedback**: Progress indicators show current attempts (e.g., "cat: 8/15") +- **Category Locking**: Current category remains locked and is the only clickable option until all words reach 15/15 + +### Initial Configuration +- **Starting Category**: "common words 3" (hardcoded) +- **Next Category**: "common words 4" (hardcoded progression) +- **Word Selection**: All words in the active category, tested in order +- **Mastery Threshold**: 15 correct attempts per word +- **Progress Tracking**: Independent counters per word (mistakes don't reset other words) + +### User Experience +- **Test Sessions**: Cycle through all words in active category each session +- **Progress Display**: Show "word: X/15" format in word selection interface +- **Results Page**: Unchanged from current system +- **Category Interface**: Locked categories visible but unclickable with lock icons + +## Architecture Overview + +```mermaid +graph TD + A[User Opens App] --> B[Word Selection Page] + B --> C{Is Category Active?} + C -->|Yes| D[Show Clickable Category] + C -->|No| E[Show Locked Category] + D --> F[Start Spelling Test] + F --> G[Test All Words in Category] + G --> H[Update Mastery Counters] + H --> I[Check Category Completion] + I -->|Complete| J[Unlock Next Category] + I -->|Incomplete| K[Continue Current Category] + J --> L[Update Active Category] + K --> M[Return to Word Selection] + L --> M +``` + +## Components and Interfaces + +### 1. Mastery Progress Tracking + +#### Enhanced Progress Data Structure +```typescript +type MasteryProgress = { + currentActiveCategory: string; // e.g., "common words 3" + wordMasteryCounters: Record; // wordId -> correct attempts count + completedCategories: string[]; // list of fully mastered categories +}; + +type EnhancedProgressData = { + // Existing progress structure + wordAttempts: Record; + // New mastery tracking + masteryProgress: MasteryProgress; +}; +``` + +#### Mastery Logic Functions +```typescript +// Check if a word has achieved mastery +function isWordMastered(wordId: string, masteryProgress: MasteryProgress): boolean { + return (masteryProgress.wordMasteryCounters[wordId] || 0) >= 15; +} + +// Check if entire category is mastered (ALL words must have 15+ correct attempts) +function isCategoryMastered(category: string, words: Word[], masteryProgress: MasteryProgress): boolean { + return words.every(word => isWordMastered(word.id, masteryProgress)); +} + +// Get next category in sequence +function getNextCategory(currentCategory: string): string { + const sequence = ["common words 3", "common words 4", "common words 5", /* etc */]; + const currentIndex = sequence.indexOf(currentCategory); + return sequence[currentIndex + 1] || currentCategory; +} +``` + +### 2. Enhanced Word Selection Interface + +#### BaseWordSelection Component Modifications +```typescript +interface MasteryModeProps { + activeCategory: string; + masteryProgress: MasteryProgress; + onCategoryClick: (category: string) => void; +} + +// Category rendering logic +const renderCategory = (category: string, words: Word[]) => { + const isActive = category === activeCategory; + const isLocked = !isActive && !completedCategories.includes(category); + + return ( +
onCategoryClick(category) : undefined} + > + {isLocked && } + + +
+ ); +}; +``` + +#### Progress Display Component +```typescript +const WordProgressDisplay = ({ word, masteryProgress }: { + word: Word; + masteryProgress: MasteryProgress; +}) => { + const currentCount = masteryProgress.wordMasteryCounters[word.id] || 0; + const isComplete = currentCount >= 15; + + return ( +
+ {word.text} + + {currentCount}/15 + + {isComplete && } +
+ ); +}; +``` + +### 3. Modified Spelling Test Logic + +#### SpellingTest Component Enhancements +```typescript +interface MasteryTestProps { + category: string; + words: Word[]; + masteryProgress: MasteryProgress; + onComplete: (updatedProgress: MasteryProgress) => void; +} + +// Test flow for mastery mode +const runMasteryTest = () => { + // Always test all words in category, in order + const wordsToTest = getAllWordsInCategory(category); + + // Standard test flow, but with mastery counter updates + const handleWordComplete = (wordId: string, correct: boolean, attempt: string) => { + // Record attempt in existing system + recordAttempt(wordId, correct, attempt); + + // Update mastery counter if correct + if (correct) { + updateMasteryCounter(wordId); + } + + // Check if category is now complete + if (isCategoryMastered(category, wordsToTest, masteryProgress)) { + unlockNextCategory(); + } + }; +}; +``` + +### 4. Progress Provider Enhancements + +#### Extended ProgressProvider +```typescript +const ProgressProvider = ({ children }) => { + const [progress, setProgress] = useState({}); + const [masteryProgress, setMasteryProgress] = useState({ + currentActiveCategory: "common words 3", + wordMasteryCounters: {}, + completedCategories: [] + }); + + const updateMasteryCounter = (wordId: string) => { + setMasteryProgress(prev => ({ + ...prev, + wordMasteryCounters: { + ...prev.wordMasteryCounters, + [wordId]: (prev.wordMasteryCounters[wordId] || 0) + 1 + } + })); + }; + + const unlockNextCategory = () => { + setMasteryProgress(prev => { + const nextCategory = getNextCategory(prev.currentActiveCategory); + return { + ...prev, + completedCategories: [...prev.completedCategories, prev.currentActiveCategory], + currentActiveCategory: nextCategory + }; + }); + }; + + return ( + + {children} + + ); +}; +``` + +## Data Models + +### Mastery Progress Structure +```typescript +type MasteryProgress = { + currentActiveCategory: string; + wordMasteryCounters: Record; + completedCategories: string[]; + lastUpdated: string; +}; +``` + +### Category Progression Configuration +```typescript +const MASTERY_CATEGORY_SEQUENCE = [ + "common words 3", + "common words 4", + "common words 5", + "common words 6", + // Add more as needed +]; + +const MASTERY_CONFIG = { + requiredCorrectAttempts: 15, + initialCategory: "common words 3" +}; +``` + +## Error Handling + +### Progress Data Integrity +- **Missing Counters**: Default to 0 for any missing word counters +- **Invalid Categories**: Fall back to initial category if current category is invalid +- **Data Corruption**: Validate mastery progress structure on load, reset if corrupted + +### Category Progression +- **Missing Next Category**: Stay on current category if next in sequence doesn't exist +- **Premature Unlock**: Validate category completion before allowing progression +- **Rollback Support**: Ability to reset to previous category if needed + +### API Failures +- **Save Failures**: Queue mastery progress updates locally, retry on reconnection +- **Load Failures**: Use cached mastery progress, sync when connection restored +- **Conflict Resolution**: Server state takes precedence over local state + +## Testing Strategy + +### Unit Tests +- **Mastery Logic**: Test word/category mastery detection functions +- **Progress Tracking**: Test counter updates and category progression +- **Data Validation**: Test progress data structure validation +- **Edge Cases**: Test boundary conditions (exactly 15 attempts, category transitions) + +### Integration Tests +- **Full Test Flow**: Complete spelling test with mastery counter updates +- **Category Progression**: Test automatic unlock of next category +- **Progress Persistence**: Test save/load of mastery progress +- **UI Integration**: Test locked/unlocked category display + +### User Acceptance Tests +- **Learning Flow**: Student completes full category mastery cycle +- **Progress Visibility**: Verify progress counters display correctly +- **Category Locking**: Confirm locked categories are unclickable +- **Progression**: Verify smooth transition to next category + +## Appendices + +### Technology Choices + +#### State Management +- **React Context**: Continue using existing ProgressProvider pattern +- **Local Storage**: Cache mastery progress for offline resilience +- **API Integration**: Extend existing progress API with mastery endpoints + +#### UI Components +- **Existing Components**: Reuse BaseWordSelection, SpellingTest components +- **New Components**: WordProgressDisplay, CategoryLockIndicator +- **Styling**: Extend existing CSS classes for mastery-specific states + +### Research Findings + +#### Current System Analysis +- **Progress Tracking**: Existing WordAttempt structure supports mastery tracking +- **Word Selection**: Current priority-based selection can be overridden for mastery mode +- **Test Flow**: Existing SpellingTest component can be enhanced rather than replaced +- **Authentication**: No admin controls needed for initial implementation + +#### Implementation Complexity +- **Low Risk**: Additive changes to existing components +- **Backward Compatible**: Existing progress data preserved +- **Minimal API Changes**: Extend existing endpoints rather than create new ones + +### Alternative Approaches + +#### Admin-Controlled Progression +- **Considered**: Manual admin approval for category advancement +- **Rejected**: Added complexity without clear benefit for single-user scenario +- **Future Option**: Could be added later if multi-user scenarios emerge + +#### Configurable Mastery Thresholds +- **Considered**: Variable mastery requirements per category +- **Rejected**: Hardcoded 15 attempts sufficient for initial implementation +- **Future Option**: Could be made configurable through settings + +#### Cross-Category Word Selection +- **Considered**: Mixing words from multiple categories +- **Rejected**: Category-focused approach provides clearer learning structure +- **Future Option**: Advanced mode could support mixed categories + +## Implementation Notes + +### Phase 1: Core Mastery Logic +1. Extend ProgressProvider with mastery tracking +2. Implement mastery detection functions +3. Add mastery counter updates to test flow + +### Phase 2: UI Enhancements +1. Add progress display to word selection interface +2. Implement category locking visual indicators +3. Update category click handlers for mastery mode + +### Phase 3: Category Progression +1. Implement automatic category unlocking +2. Add category sequence configuration +3. Test full progression flow + +### Phase 4: Polish and Testing +1. Add comprehensive test coverage +2. Implement error handling and edge cases +3. Performance optimization and cleanup + +This design provides a clear roadmap for implementing the mastery mode feature while maintaining the existing system's stability and user experience. diff --git a/.sop/mastery-mode-planning/idea-honing.md b/.sop/mastery-mode-planning/idea-honing.md new file mode 100644 index 0000000..260ec66 --- /dev/null +++ b/.sop/mastery-mode-planning/idea-honing.md @@ -0,0 +1,74 @@ +# Idea Honing - Requirements Clarification + +This document captures the detailed requirements clarification process for the Mastery Mode feature. + +## Question 1: Target Category Selection +Which specific word category should Leo focus on first for the mastery mode? For example, should it be "common words 3", or would you prefer a different category from the existing word lists? + +**Answer:** "common words 3" - This will be the hardcoded target category that Leo must focus on. + +## Question 2: Word Count in Mastery Set +How many words from "common words 3" should Leo practice in each mastery session? You mentioned 6-7 words in the original idea - do you want to stick with that range, or do you have a specific number in mind? + +**Answer:** All words in "common words 3" - Leo should practice every single word in that category, not just a subset. + +## Question 3: Repetition Requirements +How many times should Leo get each word correct before you consider moving him to the next category? You mentioned 15-20 times in the original idea - do you want a specific number, or should this be flexible? + +**Answer:** 15 correct attempts per word - Each word in "common words 3" needs to be spelled correctly 15 times before the category is considered mastered. + +## Question 4: Test Session Behavior +When Leo takes a spelling test in mastery mode, should he cycle through all the words in "common words 3" in each session, or should the system focus on the words that need the most practice first? + +**Answer:** Option A - Always test all words in the category, in order. Leo will go through every word in "common words 3" during each test session. + +## Question 5: Visual Feedback for Other Categories +You mentioned making other categories visible but unclickable. How should these disabled categories look? Should they be grayed out, have a different visual treatment, or show some kind of "locked" indicator? + +**Answer:** Locked indicator - Show a lock icon or similar visual indicator. Once a category has been completed (all words done 15 times in a row with no mistakes), unlock the next category automatically. + +## Question 6: Progression Logic +When you say "15 times in a row with no mistakes" - do you mean: +- Each individual word needs 15 consecutive correct attempts, OR +- All words in the category need to be spelled correctly 15 times each (but mistakes on one word don't reset the count for other words)? + +**Answer:** Option B - All words need 15 correct attempts each, but mistakes on one word don't reset the count for other words. Each word has its own independent counter. + +## Question 7: Next Category Selection +Once "common words 3" is completed, which category should automatically unlock next? Should it be "common words 4", or would you prefer a different progression order? + +**Answer:** "common words 4" - The progression should follow the natural sequence: common words 3 → common words 4 → common words 5, etc. + +## Question 8: Progress Display +Should Leo be able to see his progress toward the 15 correct attempts for each word? For example, showing "cat: 8/15" or similar progress indicators? + +**Answer:** Yes - Show progress indicators like "cat: 8/15" so Leo can see how close he is to mastering each word. + +## Question 9: Mastery Mode Activation +How should mastery mode be activated? Should it be: +- Always on (replace the normal mode entirely) +- A toggle/setting that can be turned on/off +- Automatically detected based on Leo's current progress + +**Answer:** Always on - Replace the normal mode entirely with mastery mode. This becomes the new default behavior for the spelling website. + +## Question 10: Results Page Behavior +When Leo completes a test session in mastery mode, what should the results page show? Should it display: +- Individual word progress (e.g., "cat: 9/15, dog: 12/15") +- Overall category progress +- Just continue to the next session automatically + +**Answer:** Nothing different than before - Keep the existing results page behavior unchanged. The mastery logic works behind the scenes but doesn't change the post-test experience. + +## Summary +I think we have enough detail to move forward with the design. The requirements are clear: + +- Mastery mode always on, replacing normal mode +- Focus on "common words 3" initially, then progress to "common words 4" +- All words in category tested each session, in order +- 15 correct attempts per word (independent counters) +- Other categories locked with visual indicators +- Progress display shows "word: X/15" format +- Results page unchanged from current system + +Should we proceed to create the detailed design document? diff --git a/.sop/mastery-mode-planning/implementation/plan.md b/.sop/mastery-mode-planning/implementation/plan.md new file mode 100644 index 0000000..95615b2 --- /dev/null +++ b/.sop/mastery-mode-planning/implementation/plan.md @@ -0,0 +1,241 @@ +# Mastery Mode Implementation Plan + +## Implementation Checklist + +- [ ] Step 1: Create mastery progress data structures and utilities +- [ ] Step 2: Extend ProgressProvider with mastery tracking +- [ ] Step 3: Add mastery counter logic to word attempt recording +- [ ] Step 4: Implement category mastery detection +- [ ] Step 5: Add progress display to word selection interface +- [ ] Step 6: Implement category locking visual indicators +- [ ] Step 7: Modify word selection to use active category only +- [ ] Step 8: Add automatic category progression logic +- [ ] Step 9: Update SpellingTest to use all words in category +- [ ] Step 10: Integrate mastery mode with existing test flow +- [ ] Step 11: Add mastery progress persistence to API +- [ ] Step 12: Test and polish the complete mastery system + +--- + +## Step 1: Create mastery progress data structures and utilities + +Create the foundational data structures and utility functions for mastery tracking. + +**Implementation:** +- Define `MasteryProgress` TypeScript interface +- Create utility functions for mastery detection (`isWordMastered`, `isCategoryMastered`) +- Add category progression logic (`getNextCategory`) +- Define mastery configuration constants + +**Tests:** +- Unit tests for mastery detection functions +- Test category progression sequence +- Validate data structure integrity + +**Demo:** Console logging shows correct mastery calculations for sample data, category progression works correctly. + +## Step 2: Extend ProgressProvider with mastery tracking + +Enhance the existing ProgressProvider to include mastery progress state management. + +**Implementation:** +- Add `masteryProgress` state to ProgressProvider +- Create `updateMasteryCounter` function +- Add `unlockNextCategory` function +- Initialize with default mastery progress (starting with "common words 3") + +**Tests:** +- Test mastery progress state updates +- Verify counter increments work correctly +- Test category unlocking logic + +**Demo:** ProgressProvider context includes mastery functions, state updates correctly when functions are called. + +## Step 3: Add mastery counter logic to word attempt recording + +Integrate mastery counter updates with the existing word attempt recording system. + +**Implementation:** +- Modify `recordAttempt` function to update mastery counters on correct attempts +- Ensure mastery counters only increment for correct attempts +- Maintain existing progress tracking functionality + +**Tests:** +- Test that correct attempts increment mastery counters +- Verify incorrect attempts don't affect mastery counters +- Ensure existing progress tracking still works + +**Demo:** Taking a spelling test updates both existing progress and mastery counters correctly. + +## Step 4: Implement category mastery detection + +Add logic to detect when a category is fully mastered (ALL words at 15/15) and trigger progression. + +**Implementation:** +- Create category completion checking in `recordAttempt` +- Ensure ALL words in category must reach 15 correct attempts before unlocking next category +- Trigger `unlockNextCategory` only when every word is fully mastered +- Add logging/feedback for category completion events + +**Tests:** +- Test category completion detection requires ALL words at 15/15 +- Verify next category unlocks only when current is 100% complete +- Test edge cases (one word at 14/15 should keep category locked) + +**Demo:** Only when ALL words in "common words 3" reach 15/15 does "common words 4" unlock automatically. + +## Step 5: Add progress display to word selection interface + +Show mastery progress counters in the word selection interface. + +**Implementation:** +- Create `WordProgressDisplay` component showing "word: X/15" format +- Integrate progress display into existing word list rendering +- Add visual indicators for mastered words (checkmarks, different colors) + +**Tests:** +- Test progress display renders correctly +- Verify counters update in real-time +- Test visual states for different progress levels + +**Demo:** Word selection page shows progress counters for each word, updates immediately after tests. + +## Step 6: Implement category locking visual indicators + +Add visual feedback for locked/unlocked categories. + +**Implementation:** +- Create lock icon component +- Add CSS classes for locked category styling +- Modify category rendering to show lock state +- Disable click handlers for locked categories + +**Tests:** +- Test locked categories display correctly +- Verify locked categories are unclickable +- Test visual styling for different states + +**Demo:** Non-active categories show lock icons and are visually disabled, cannot be clicked. + +## Step 7: Modify word selection to use active category only + +Update word selection logic to focus on the currently active mastery category. + +**Implementation:** +- Modify `BaseWordSelection` to highlight active category +- Override word selection to use all words from active category +- Ensure only active category is clickable + +**Tests:** +- Test that only active category can be selected +- Verify all words from active category are included +- Test category switching when progression occurs + +**Demo:** Only the active mastery category (initially "common words 3") is clickable and selectable. + +## Step 8: Add automatic category progression logic + +Implement the automatic unlocking and switching to the next category. + +**Implementation:** +- Add category sequence configuration +- Implement smooth transition to next category +- Update UI to reflect new active category +- Handle edge cases (no next category available) + +**Tests:** +- Test progression through multiple categories +- Verify UI updates correctly on progression +- Test behavior at end of sequence + +**Demo:** Completing "common words 3" automatically makes "common words 4" the new active category. + +## Step 9: Update SpellingTest to use all words in category + +Modify the spelling test to include all words from the active category instead of just 3 words. + +**Implementation:** +- Override word selection in mastery mode to include all category words +- Maintain existing test flow but with expanded word list +- Ensure test cycles through all words in order + +**Tests:** +- Test that all words in category are included in test +- Verify test order matches category word order +- Test with categories of different sizes + +**Demo:** Starting a spelling test includes all words from the active category, not just 3 words. + +## Step 10: Integrate mastery mode with existing test flow + +Ensure mastery mode works seamlessly with existing test components and flows. + +**Implementation:** +- Verify SpellingTest component works with mastery word lists +- Ensure results pages display correctly +- Maintain existing test features (audio, skip, retry) + +**Tests:** +- Full integration test of complete test flow +- Test all existing features work with mastery mode +- Verify results and practice pages function correctly + +**Demo:** Complete spelling test flow works identically to before, but with mastery tracking and expanded word lists. + +## Step 11: Add mastery progress persistence to API + +Extend the existing progress API to save and load mastery progress data. + +**Implementation:** +- Extend progress API endpoints to include mastery data +- Add mastery progress to save/load operations +- Ensure backward compatibility with existing progress data + +**Tests:** +- Test mastery progress saves correctly +- Verify mastery progress loads on app restart +- Test API error handling and fallbacks + +**Demo:** Mastery progress persists across browser sessions, loads correctly on app restart. + +## Step 12: Test and polish the complete mastery system + +Comprehensive testing and refinement of the entire mastery mode implementation. + +**Implementation:** +- End-to-end testing of complete mastery flow +- Performance optimization and code cleanup +- Error handling and edge case resolution +- User experience polish and refinements + +**Tests:** +- Complete user journey testing +- Performance and load testing +- Error scenario testing +- Cross-browser compatibility testing + +**Demo:** Fully functional mastery mode that provides smooth, engaging learning experience with proper progress tracking and category progression. + +--- + +## Technical Notes + +### State Management +- Mastery progress stored alongside existing progress data +- Real-time updates to UI when progress changes +- Proper error handling for state corruption + +### API Integration +- Extend existing progress endpoints rather than creating new ones +- Maintain backward compatibility with existing data +- Graceful degradation if mastery features fail + +### Performance Considerations +- Efficient progress calculations for large word lists +- Minimal re-renders when progress updates +- Proper cleanup of event listeners and timers + +### User Experience +- Smooth transitions between categories +- Clear visual feedback for progress and achievements +- Consistent behavior with existing spelling test flow diff --git a/.sop/mastery-mode-planning/research/current-implementation.md b/.sop/mastery-mode-planning/research/current-implementation.md new file mode 100644 index 0000000..ff7de8e --- /dev/null +++ b/.sop/mastery-mode-planning/research/current-implementation.md @@ -0,0 +1,182 @@ +# Current Spelling Test Implementation Research + +## Core Test Mechanics + +### Progress Tracking System +The system uses a sophisticated progress tracking mechanism: + +#### WordAttempt Structure +```typescript +type WordAttempt = { + date: string; + correct: boolean; + attempt: string; // What the user actually typed +}; +``` + +#### Word Status Calculation +- **not-started**: No attempts recorded +- **in-progress**: Has attempts but streak < 3 +- **mastered**: Current streak ≥ 3 consecutive correct +- **unmastered**: Previously mastered but lost streak (special case) + +#### Mastery Criteria +- **Current requirement**: 3 consecutive correct answers +- **Streak calculation**: Counts backwards from most recent attempt +- **Mastery loss**: If a mastered word gets incorrect, becomes "unmastered" + +### Word Selection Algorithm + +#### Priority System +```typescript +const WORD_PRIORITY: Record = { + 'unmastered': 0, // Highest priority - lost mastery + 'in-progress': 1, // Second priority - building streak + 'not-started': 2, // Third priority - new learning + 'mastered': 3 // Lowest priority - already achieved +}; +``` + +#### Selection Logic +1. **Sort by priority**: Unmastered → In-progress → Not-started → Mastered +2. **Limit selection**: Default 3 words per session +3. **Category-based**: Selection happens within categories + +### Test Flow Architecture + +#### Two-Stage System (for 'less_family' words) +1. **Base Stage**: Practice base words (e.g., "care" from "careless") +2. **Full Stage**: Practice full words (e.g., "careless") +3. **Progression**: Must complete base stage before full stage + +#### Single-Stage System (for regular words) +- Direct spelling test of selected words +- Results → Practice incorrect words → Complete + +### Current Limitations for Mastery Mode + +#### Fixed Parameters +- **Word count**: Always 3 words per session +- **Mastery threshold**: Fixed at 3 consecutive correct +- **Session-based**: No persistence of "current learning set" + +#### No Admin Override +- **Automatic progression**: System decides when to advance +- **No manual control**: Can't force student to continue with mastered words +- **No extended repetition**: Once mastered (3 correct), word is deprioritized + +#### Limited Repetition Logic +- **Single session**: Words only repeated if incorrect in same session +- **Cross-session**: Mastered words rarely selected again +- **No deep practice**: No mechanism for 15-20 repetitions of same words + +## Integration Points for Mastery Mode + +### 1. Enhanced Progress Tracking +Need to track: +```typescript +type MasteryProgress = { + currentSet: string[]; // Words in current mastery set + setStartDate: string; + correctAttempts: Record; // Count per word + requiredAttempts: number; // Admin-configurable + adminControlled: boolean; +}; +``` + +### 2. Modified Word Selection +Instead of priority-based selection: +- **Fixed set selection**: Admin/system selects 6-7 words +- **Set persistence**: Same words until mastery criteria met +- **No automatic advancement**: Admin controls progression + +### 3. Enhanced Test Logic +Current SpellingTest.tsx needs: +- **Mastery mode detection**: Different flow for mastery vs regular +- **Repetition tracking**: Count correct attempts per word in set +- **Admin controls**: UI for manual advancement +- **Extended sessions**: Continue until admin says stop + +### 4. New State Management +App.tsx selectedList needs extension: +```typescript +type SelectedList = { + words: string[]; + type: 'single' | 'less_family' | 'mastery'; + testMode?: 'practice' | 'full_test'; + passThreshold?: number; + masteryConfig?: { + requiredCorrectAttempts: number; + adminControlled: boolean; + currentAttempts: Record; + }; +}; +``` + +## Technical Implementation Strategy + +### 1. Backward Compatibility +- **Preserve existing flows**: Regular practice/test modes unchanged +- **Additive approach**: Mastery mode as additional option +- **Shared components**: Reuse existing UI components where possible + +### 2. Data Persistence +- **API extension**: New endpoints for mastery progress +- **Local state**: Enhanced ProgressProvider for mastery tracking +- **Session continuity**: Persist mastery sets across browser sessions + +### 3. Admin Detection +Current system lacks admin role detection: +- **OIDC integration**: Extend auth context with admin role +- **Conditional rendering**: Show admin controls only to admins +- **Route protection**: Admin-only configuration pages + +## Key Differences from Current System + +### Current: Session-Based Learning +- Select 3 words → Test → Results → New selection +- Mastery = 3 correct → Move to next words +- Category-driven selection + +### Proposed: Set-Based Mastery +- Select 6-7 words → Extended practice → Admin advancement +- Mastery = 15-20 correct attempts → Admin decides when to advance +- Fixed set until manual progression + +### Current: Automatic Progression +- System decides when student is ready +- Priority algorithm selects next words +- No human oversight of learning pace + +### Proposed: Admin-Controlled Progression +- Admin observes student performance +- Manual decision to advance to next set +- Human judgment over algorithmic selection + +## Implementation Complexity Assessment + +### Low Complexity +- **UI modifications**: Add mastery mode toggle, admin controls +- **State extensions**: Add mastery config to existing state +- **Progress display**: Show repetition counts + +### Medium Complexity +- **Test flow modification**: New logic for mastery mode in SpellingTest +- **Admin role integration**: Extend authentication system +- **API extensions**: New endpoints for mastery progress + +### High Complexity +- **Cross-session persistence**: Maintain mastery sets across sessions +- **Real-time admin controls**: Live updates during student sessions +- **Migration strategy**: Handle existing progress data + +## Conclusion + +The current system provides a solid foundation with its progress tracking and test flow architecture. The main changes needed are: + +1. **Extend state management** to support mastery sets +2. **Add admin role detection** and controls +3. **Modify test progression logic** for extended repetition +4. **Enhance progress tracking** for mastery-specific metrics + +The existing components (SpellingTest, BaseWordSelection, ProgressProvider) can be extended rather than replaced, maintaining backward compatibility while adding the new mastery functionality. diff --git a/.sop/mastery-mode-planning/research/progress-system-impact.md b/.sop/mastery-mode-planning/research/progress-system-impact.md new file mode 100644 index 0000000..532ce09 --- /dev/null +++ b/.sop/mastery-mode-planning/research/progress-system-impact.md @@ -0,0 +1,235 @@ +# Current Progress System and Mastery Mode Impact Research + +## Current Progress System Analysis + +### Word Status Calculation (Current System) +```typescript +// From ProgressProvider.tsx - getWordStats() +let status: WordStats['status'] = 'not-started'; +if (attemptsArr.length > 0) status = 'in-progress'; +if (streak >= 3) status = 'mastered'; // 3 consecutive correct = mastered +``` + +**Current Mastery Criteria**: 3 consecutive correct answers + +### Profile Page Progress Tracking + +#### Key Metrics Displayed +1. **Words Mastered This Week**: Count of words that achieved 'mastered' status this week +2. **Current Streak**: Days with spelling activity +3. **Total Words Mastered**: Total count of words with 'mastered' status + +#### Daily Progress Tracking +The profile page tracks daily mastery/unmastery events: +```typescript +// From ProfilePage.tsx - mastery detection logic +if (consecutiveCorrect === 3 && !wasMastered) { + // Word achieved mastery (3rd consecutive correct) + dailyMasteredWords[attemptDate].mastered.push(wordId); + wasMastered = true; +} + +// If incorrect attempt breaks existing mastery +if (wasMastered && consecutiveCorrect >= 3) { + // Word lost mastery + dailyMasteredWords[attemptDate].unmastered.push(wordId); + wasMastered = false; +} +``` + +#### Visual Progress Indicators +- **Green badges**: Words mastered on specific dates +- **Red badges**: Words that lost mastery on specific dates +- **Gradient badges**: Words re-mastered on same day (lost then regained mastery) +- **Activity calendar**: Shows daily attempt counts + +## Impact of Mastery Mode on Current Progress + +### Fundamental Conflict: Different Mastery Definitions + +#### Current System: 3 Consecutive Correct +- Word becomes "mastered" after 3 consecutive correct attempts +- Profile page celebrates these mastery achievements +- Progress metrics based on this 3-attempt threshold + +#### Mastery Mode: 15 Total Correct (Independent Counters) +- Word requires 15 correct attempts total (not consecutive) +- Mistakes don't reset progress on individual words +- Much higher threshold for true mastery + +### Specific Impact Areas + +#### 1. Profile Page Metrics Will Be Misleading +```typescript +// Current: This will show inflated "mastered" counts +const totalMastered = stats.filter(s => s.status === 'mastered').length; + +// Problem: Words with 3+ consecutive correct show as "mastered" +// but may only have 3/15 attempts in mastery mode +``` + +#### 2. Daily Mastery Tracking Becomes Irrelevant +- Profile page tracks when words achieve 3-consecutive mastery +- In mastery mode, this happens frequently but isn't meaningful +- Real mastery (15 attempts) may take weeks to achieve + +#### 3. Progress Celebration Mismatch +- Current system celebrates 3-consecutive achievements +- Mastery mode needs to celebrate 15-attempt achievements +- User will see conflicting progress signals + +#### 4. Historical Data Interpretation +- Existing "mastered" words may only have 3-5 total correct attempts +- These don't meet mastery mode's 15-attempt requirement +- Need to decide how to handle this discrepancy + +## Proposed Solutions + +### Option 1: Dual Progress Systems +Maintain both progress tracking systems: +```typescript +type EnhancedWordStats = { + // Existing 3-consecutive system + status: 'not-started' | 'in-progress' | 'mastered'; + streak: number; + + // New mastery mode system + masteryCount: number; // total correct attempts + masteryStatus: 'incomplete' | 'mastered'; // based on 15 attempts +}; +``` + +**Pros**: Preserves existing progress, adds mastery tracking +**Cons**: Complex dual system, confusing metrics + +### Option 2: Migrate to Mastery System +Replace 3-consecutive with 15-attempt system entirely: +```typescript +// Update getWordStats to use 15-attempt threshold +if (totalCorrectAttempts >= 15) status = 'mastered'; +``` + +**Pros**: Consistent single system, clearer progress +**Cons**: Invalidates existing "mastered" status, breaks historical data + +### Option 3: Mastery Mode Overlay (Recommended) +Keep existing system, add mastery mode as overlay: +```typescript +type MasteryModeProgress = { + enabled: boolean; + activeCategory: string; + wordMasteryCounters: Record; + // Separate from existing progress system +}; +``` + +**Pros**: Non-destructive, preserves existing functionality +**Cons**: Two different progress concepts in same app + +## Recommended Approach: Option 3 - Mastery Mode Overlay + +### Implementation Strategy + +#### 1. Preserve Existing Progress System +- Keep current 3-consecutive mastery detection +- Maintain existing profile page metrics +- Don't modify existing progress calculations + +#### 2. Add Parallel Mastery Tracking +```typescript +// New mastery progress structure (separate from existing) +type MasteryProgress = { + currentActiveCategory: string; + wordMasteryCounters: Record; // total correct attempts + completedCategories: string[]; +}; +``` + +#### 3. Update Profile Page for Mastery Mode +Add new sections to profile page: +```typescript +// New mastery-specific metrics +const masteryStats = { + currentCategoryProgress: calculateCategoryProgress(masteryProgress), + totalMasteryWords: Object.values(masteryProgress.wordMasteryCounters) + .filter(count => count >= 15).length, + currentFocusCategory: masteryProgress.currentActiveCategory +}; +``` + +#### 4. Visual Distinction in Profile +- **Existing metrics**: "Traditional Mastery" (3 consecutive) +- **New metrics**: "Deep Mastery" (15 attempts) +- **Clear labeling**: Avoid confusion between the two systems + +### Profile Page Enhancements Needed + +#### New Mastery Mode Section +```typescript +const MasteryModeStats = ({ masteryProgress }: { masteryProgress: MasteryProgress }) => ( +
+

Deep Mastery Progress

+ + c >= 15).length} + color="#059669" + /> + +
+); +``` + +#### Enhanced Daily Activity +Track both traditional and mastery progress: +```typescript +const dailyMasteryActivity = { + traditionalMastery: [], // 3-consecutive achievements + deepMastery: [], // 15-attempt achievements + categoryCompletions: [] // full category completions +}; +``` + +## Migration Strategy for Existing Users + +### Handling Existing "Mastered" Words +1. **Preserve existing status**: Don't downgrade currently "mastered" words +2. **Initialize mastery counters**: Set counters based on historical correct attempts +3. **Grandfather existing progress**: Words with 3+ consecutive correct start with higher counters + +```typescript +// Initialize mastery counters from existing progress +const initializeMasteryCounters = (existingProgress: ProgressData): Record => { + const counters: Record = {}; + + Object.entries(existingProgress).forEach(([wordId, attempts]) => { + const correctAttempts = attempts.filter(a => a.correct).length; + // Give credit for existing correct attempts, minimum 3 if currently "mastered" + const currentStats = getWordStats(wordId); + counters[wordId] = currentStats.status === 'mastered' + ? Math.max(correctAttempts, 3) + : correctAttempts; + }); + + return counters; +}; +``` + +## Conclusion + +The mastery mode introduces a fundamentally different progress concept (15 total correct vs 3 consecutive correct). The recommended approach is to implement mastery mode as an overlay system that: + +1. **Preserves existing progress tracking** - no data loss or confusion +2. **Adds parallel mastery tracking** - new 15-attempt system alongside existing +3. **Enhances profile page** - shows both traditional and deep mastery metrics +4. **Provides clear migration path** - existing users get credit for historical progress + +This approach maintains backward compatibility while providing the deep learning benefits of the mastery mode system. diff --git a/.sop/mastery-mode-planning/research/ui-ux-patterns.md b/.sop/mastery-mode-planning/research/ui-ux-patterns.md new file mode 100644 index 0000000..997adf0 --- /dev/null +++ b/.sop/mastery-mode-planning/research/ui-ux-patterns.md @@ -0,0 +1,174 @@ +# UI/UX Patterns Research - Current Interface and Admin Controls + +## Current System Architecture + +### Test Mode Selection +The current system supports two test modes: +- **Practice Mode** (`'practice'`): Default mode with retry/practice options +- **Full Test Mode** (`'full_test'`): Assessment mode with pass/fail thresholds + +### Word Selection Flow +1. **ChallengesPage** → Main dashboard with progress tracking +2. **WordSelection/CommonWordsSelection** → Category-based word selection +3. **SpellingTest** → Core test interface +4. **Results Pages** → SpellingResults, FullTestResults, or CongratulationsPage + +### Current Admin Controls +Based on code analysis, admin controls are limited: +- No explicit admin role detection found +- Authentication handled via OIDC (react-oidc-context) +- Progress tracking via DynamoDB but no admin override capabilities +- Test parameters (passThreshold) passed through props but no UI for admin configuration + +## Current Test Flow Patterns + +### Word Selection Logic +- **Category-based selection**: Words grouped by categories (e.g., "adding -s", "KS1-1") +- **Automatic selection**: `selectNextWords()` utility selects 3 words per category +- **Progress-based**: Prioritizes words that need practice (not mastered) + +### Test Progression +1. **Single Stage**: Direct spelling test of selected words +2. **Two-Stage** (for 'less_family'): Base words → Full words +3. **Completion Criteria**: All words correct → advance/complete + +### Current Limitations for Mastery Mode +- **Fixed word count**: Always selects 3 words +- **Automatic progression**: No admin control over when to advance +- **Limited repetition**: Words only repeated if incorrect +- **No persistence**: No way to "lock" a student on specific words + +## UI Components Analysis + +### Key Components for Mastery Mode Integration + +#### 1. App.tsx - State Management +```typescript +const [selectedList, setSelectedList] = useState<{ + words: string[]; + type: 'single' | 'less_family'; + testMode?: 'practice' | 'full_test'; + passThreshold?: number; +} | null>(null) +``` +**Opportunity**: Add `masteryMode?: boolean` and `masteryConfig?` to selectedList state + +#### 2. BaseWordSelection.tsx - Word Selection Interface +- **Current**: Category-based selection with automatic 3-word selection +- **Pattern**: Click category → auto-select words → navigate to test +- **Opportunity**: Add "Mastery Mode" toggle/option per category + +#### 3. SpellingTest.tsx - Core Test Logic +- **Current**: Linear progression through words with results at end +- **Pattern**: Word → Input → Next → Results +- **Opportunity**: Add mastery mode logic with admin controls + +#### 4. ChallengesPage.tsx - Main Dashboard +- **Current**: Progress tracking with percentage completion +- **Pattern**: Challenge cards with progress bars +- **Opportunity**: Add mastery mode status/controls + +## Admin Control Patterns Needed + +### Missing Admin Functionality +1. **Role Detection**: No current admin role identification +2. **Override Controls**: No way to manually advance students +3. **Mastery Configuration**: No UI for setting word count, repetition requirements +4. **Progress Override**: No admin ability to reset/modify student progress + +### Recommended Admin UI Patterns + +#### 1. Admin Mode Toggle +- **Location**: Header component or profile page +- **Pattern**: Simple toggle switch "Admin Mode: ON/OFF" +- **Effect**: Shows additional controls throughout interface + +#### 2. Mastery Mode Configuration +- **Location**: Word selection pages +- **Pattern**: Expandable settings panel +- **Controls**: + - Word count selector (5-10 words) + - Repetition requirement (10-25 correct attempts) + - Auto-advance toggle (admin control vs automatic) + +#### 3. Student Progress Override +- **Location**: During active mastery session +- **Pattern**: Admin panel overlay with controls +- **Controls**: + - "Advance to Next Set" button + - Current repetition count display + - Reset progress option + +## Integration Points for Mastery Mode + +### 1. Word Selection Enhancement +```typescript +// Add to BaseWordSelection props +masteryModeEnabled?: boolean; +masteryConfig?: { + wordCount: number; + requiredCorrectAttempts: number; + adminControlled: boolean; +} +``` + +### 2. Test Mode Extension +```typescript +// Extend selectedList type in App.tsx +type: 'single' | 'less_family' | 'mastery'; +masteryConfig?: { + wordCount: number; + requiredCorrectAttempts: number; + currentSet: number; + totalSets: number; + adminControlled: boolean; +} +``` + +### 3. SpellingTest Mastery Logic +- **New state**: Track correct attempts per word +- **Modified progression**: Don't advance until mastery criteria met +- **Admin controls**: Override buttons for manual advancement + +## Visual Design Patterns + +### Current Design Language +- **Color scheme**: Gold/yellow for KS1 challenge, orange/black for common words +- **Progress indicators**: Horizontal bars with percentage +- **Status indicators**: Colored dots (• green for mastered, etc.) +- **Card-based layout**: Challenge cards, category cards + +### Mastery Mode Visual Indicators +- **Repetition counter**: "Word 'cat': 12/20 correct attempts" +- **Set progress**: "Set 1 of 5: Words 1-7" +- **Admin controls**: Distinct styling (perhaps red/admin theme) +- **Mastery status**: Enhanced visual feedback for deep learning + +## Technical Implementation Notes + +### State Management Considerations +- **Persistence**: Mastery progress needs to persist across sessions +- **Real-time updates**: Admin controls need immediate UI updates +- **Progress tracking**: Enhanced tracking for repetition counts + +### Authentication Integration +- **Admin detection**: Extend OIDC context to include admin role +- **Route protection**: Admin-only routes/components +- **Conditional rendering**: Show/hide admin controls based on role + +### API Integration +- **Progress API**: Enhanced endpoints for mastery tracking +- **Admin API**: New endpoints for progress override +- **Real-time sync**: Ensure admin changes reflect immediately + +## Conclusion + +The current system provides a solid foundation for adding mastery mode functionality. Key integration points include: + +1. **Extend existing state management** to support mastery configuration +2. **Add admin role detection** and conditional UI rendering +3. **Enhance word selection** with mastery mode options +4. **Modify test progression logic** to support repetition requirements +5. **Add admin override controls** for manual advancement + +The existing UI patterns (cards, progress bars, status indicators) can be extended to support mastery mode without major design changes. diff --git a/.sop/mastery-mode-planning/research/word-lists-auth.md b/.sop/mastery-mode-planning/research/word-lists-auth.md new file mode 100644 index 0000000..2e10a8e --- /dev/null +++ b/.sop/mastery-mode-planning/research/word-lists-auth.md @@ -0,0 +1,251 @@ +# Word List Management and Authentication Research + +## Word List Structure + +### Data Model +```typescript +type Word = { + id: string; // unique identifier (e.g. "ff-off") + text: string; // the actual word to spell + year: 1 | 2; // curriculum year level + category: string; // phonics grouping ("ff", "ll", "common words 1") +} +``` + +### Current Word Collections +- **YEAR1_WORDS**: Phonics-based categories (ff, ll, ss, zz, ck, etc.) +- **COMMON_WORDS**: High-frequency words grouped by sets +- **YEAR2_WORDS**: Advanced phonics patterns +- **ALL_WORDS**: Combined collection of all word lists + +### Category Organization +Words are organized by phonics patterns and learning objectives: +- **Phonics categories**: "ff", "ll", "ss", "ck", "sh", "ch", "th", etc. +- **Common word sets**: "common words 1", "common words 2", etc. +- **Advanced patterns**: "adding -s", "adding -ed", "adding -ing" + +### Word Selection for Mastery Mode +Current system selects 3 words per category using priority algorithm. For mastery mode: +- **Fixed set size**: 6-7 words instead of 3 +- **Cross-category selection**: Could select from multiple categories +- **Admin-curated sets**: Manual selection vs algorithmic + +## Authentication System + +### Current Implementation +- **Provider**: AWS Cognito via OIDC (react-oidc-context) +- **Flow**: Authorization Code Flow with PKCE +- **Token management**: Automatic refresh handled by library +- **User identification**: `cognito:username`, email, or sub as fallback + +### User Profile Structure +```typescript +// Available user profile fields +profile = { + 'cognito:username': string, + email: string, + sub: string, // unique user ID + // Other Cognito standard claims +} +``` + +### Current Limitations for Admin Functionality +- **No role detection**: No admin/student role differentiation +- **No group membership**: No way to identify admin users +- **Single user type**: All authenticated users have same permissions + +## Admin Role Integration Strategy + +### Option 1: Cognito Groups +Add users to admin group in Cognito: +```typescript +// Enhanced profile with groups +profile = { + 'cognito:username': string, + 'cognito:groups': string[], // ['admin', 'student'] + email: string, + sub: string +} +``` + +### Option 2: Custom Claims +Add admin flag as custom claim: +```typescript +profile = { + 'cognito:username': string, + 'custom:role': 'admin' | 'student', + email: string, + sub: string +} +``` + +### Option 3: Hardcoded Admin List +Simple approach for small user base: +```typescript +const ADMIN_USERS = ['parent@email.com', 'teacher@email.com']; +const isAdmin = ADMIN_USERS.includes(profile.email); +``` + +## Progress Tracking Integration + +### Current Progress Structure +```typescript +type WordAttempt = { + date: string; + correct: boolean; + attempt: string; +}; + +type ProgressData = Record; +``` + +### Mastery Mode Progress Extension +Need to track additional data: +```typescript +type MasterySession = { + sessionId: string; + words: string[]; + startDate: string; + requiredCorrectAttempts: number; + currentAttempts: Record; + adminControlled: boolean; + completed: boolean; + completedDate?: string; +}; + +type EnhancedProgressData = { + wordAttempts: Record; + masterySessions: MasterySession[]; + currentMasterySession?: string; // sessionId +}; +``` + +## API Integration Points + +### Current Progress API +- **getAllProgress(token)**: Fetch all user progress +- **putWordProgress(token, wordId, attempts)**: Record new attempts + +### Required Mastery API Extensions +- **createMasterySession(token, config)**: Start new mastery session +- **updateMasterySession(token, sessionId, updates)**: Update session progress +- **completeMasterySession(token, sessionId)**: Mark session complete +- **getMasterySessions(token)**: Get user's mastery sessions +- **adminAdvanceSession(token, userId, sessionId)**: Admin override (admin only) + +## User Experience Considerations + +### Student Experience +- **Seamless integration**: Mastery mode feels natural within existing flow +- **Progress visibility**: Clear indication of mastery progress +- **Motivation**: Visual feedback for repetition achievements + +### Admin Experience +- **Easy activation**: Simple toggle to enable mastery mode +- **Clear controls**: Obvious buttons for advancement decisions +- **Progress monitoring**: Real-time view of student performance + +### Multi-User Scenarios +- **Family accounts**: Parent as admin, children as students +- **Classroom use**: Teacher as admin, students practice independently +- **Self-directed**: Student can use regular mode, parent can enable mastery mode + +## Implementation Strategy for Word Selection + +### Current Category-Based Selection +```typescript +// BaseWordSelection.tsx - current approach +const selectNextWordsForCategory = (category: string) => { + const wordList = categoryToWordStatuses[category] || []; + return selectNextWords(wordList, 3); // Always 3 words +}; +``` + +### Mastery Mode Word Selection +```typescript +// Enhanced selection for mastery mode +const selectMasteryWords = ( + category: string, + wordCount: number = 7, + adminSelected?: string[] +) => { + if (adminSelected) return adminSelected; + + const wordList = categoryToWordStatuses[category] || []; + return selectNextWords(wordList, wordCount); +}; +``` + +### Cross-Category Selection +For advanced mastery sessions: +```typescript +const selectMixedMasteryWords = ( + categories: string[], + wordCount: number = 7 +) => { + const allWords = categories.flatMap(cat => + categoryToWordStatuses[cat] || [] + ); + return selectNextWords(allWords, wordCount); +}; +``` + +## Configuration Management + +### Mastery Mode Settings +```typescript +type MasteryConfig = { + enabled: boolean; + defaultWordCount: number; // 6-7 + defaultRequiredAttempts: number; // 15-20 + adminControlled: boolean; + allowCrossCategory: boolean; + categories: string[]; // which categories support mastery mode +}; +``` + +### User Preferences +Store in user profile or separate preferences: +```typescript +type UserPreferences = { + masteryMode: MasteryConfig; + notifications: boolean; + autoPlay: boolean; +}; +``` + +## Security Considerations + +### Admin Action Authorization +- **Token validation**: Ensure admin tokens are valid +- **Role verification**: Double-check admin status on sensitive operations +- **Audit logging**: Track admin actions for accountability + +### Student Data Protection +- **Progress isolation**: Students can only see their own progress +- **Admin oversight**: Admins can view/modify student progress appropriately +- **Data retention**: Clear policies on progress data storage + +## Migration Strategy + +### Backward Compatibility +- **Existing progress**: Preserve all current word attempt data +- **Gradual rollout**: Mastery mode as opt-in feature initially +- **Fallback support**: Regular mode always available + +### Data Migration +- **Progress structure**: Extend existing progress without breaking changes +- **API versioning**: Support both old and new progress formats +- **User migration**: Smooth transition for existing users + +## Conclusion + +The current word list and authentication systems provide a solid foundation for mastery mode implementation. Key integration points: + +1. **Extend word selection** to support configurable word counts and admin curation +2. **Add admin role detection** through Cognito groups or custom claims +3. **Enhance progress tracking** to support mastery session persistence +4. **Extend API** with mastery-specific endpoints +5. **Maintain backward compatibility** with existing progress data + +The modular structure of the current system allows for additive changes without disrupting existing functionality. diff --git a/.sop/mastery-mode-planning/rough-idea.md b/.sop/mastery-mode-planning/rough-idea.md new file mode 100644 index 0000000..46d2dd7 --- /dev/null +++ b/.sop/mastery-mode-planning/rough-idea.md @@ -0,0 +1,25 @@ +# Rough Idea: Mastery Mode for Spelling Practice + +## Original Issue +GitHub Issue #63: Add a new test style 10 words repeated + +## Detailed Description - Simplified Approach +I want to create a focused mastery mode where Leo practices a specific word list (like "common words 3") repeatedly until we're ready to move on to the next list. + +Key requirements: +- Hardcode focus on one specific category (e.g., "common words 3") +- Leo practices the same 6-7 words from that category repeatedly +- He might get them correct (green) 15-20 times in a row before moving to the next set +- All other word categories remain visible but become unclickable +- No admin interface needed initially - just hardcode the target category +- Current system only requires 3 correct answers before moving on, which feels superficial +- This is an additional feature - existing functionality should remain unchanged + +## Simplified Implementation Strategy +- Hardcode the target category in the code +- Make non-target categories visually disabled/unclickable +- Modify test logic to repeat the same words until manual code change +- No complex admin controls or session management needed initially + +## Goal +Deeper learning through repetition and mastery before progression, with a simple hardcoded approach that can be easily modified when ready to advance Leo to the next word set. diff --git a/.sop/mastery-mode-planning/summary.md b/.sop/mastery-mode-planning/summary.md new file mode 100644 index 0000000..8f4a6a5 --- /dev/null +++ b/.sop/mastery-mode-planning/summary.md @@ -0,0 +1,95 @@ +# Mastery Mode Project Summary + +## Project Overview + +Successfully transformed the rough idea for a mastery-based spelling practice mode into a comprehensive design and implementation plan. The project focuses on creating a deep learning experience where Leo practices specific word categories until achieving true mastery before progressing. + +## Artifacts Created + +### Planning Documents +- **rough-idea.md** - Initial concept refined to simplified hardcoded approach +- **idea-honing.md** - Detailed requirements clarification through Q&A process +- **research/** - Technical research on current system architecture + - ui-ux-patterns.md - Current interface and admin control analysis + - current-implementation.md - Spelling test mechanics and integration points + - word-lists-auth.md - Word management and authentication system analysis + +### Design Documents +- **design/detailed-design.md** - Comprehensive technical design with architecture, components, and data models + +### Implementation Documents +- **implementation/plan.md** - 12-step implementation plan with checklist and detailed guidance + +## Key Design Decisions + +### Simplified Approach +- **Hardcoded categories**: Start with "common words 3", progress to "common words 4" +- **No admin interface**: Avoid complexity of admin controls initially +- **Always-on mode**: Replace normal mode entirely rather than toggle + +### Core Mechanics +- **Deep repetition**: 15 correct attempts per word (vs current 3) +- **Category focus**: All words in category practiced each session, category locked until ALL words reach 15/15 +- **Independent counters**: Mistakes don't reset progress on other words +- **Visual progression**: Lock indicators and progress counters (word: X/15) + +### Technical Strategy +- **Additive changes**: Extend existing components rather than replace +- **Backward compatibility**: Preserve existing progress data +- **Minimal API changes**: Extend current endpoints rather than create new ones + +## Implementation Approach + +### Phase-Based Development +1. **Core Logic** (Steps 1-4): Mastery tracking and detection +2. **UI Enhancements** (Steps 5-7): Progress display and category locking +3. **Integration** (Steps 8-10): Category progression and test flow +4. **Persistence & Polish** (Steps 11-12): API integration and testing + +### Key Technical Components +- **Enhanced ProgressProvider**: Mastery progress state management +- **WordProgressDisplay**: "word: X/15" progress indicators +- **Category Locking**: Visual lock indicators for inactive categories +- **Automatic Progression**: Seamless transition between categories + +## Expected Outcomes + +### Learning Benefits +- **Deeper mastery**: 15 repetitions vs 3 ensures true understanding +- **Focused practice**: Single category focus eliminates distraction +- **Clear progression**: Visual feedback motivates continued practice +- **Systematic advancement**: Structured progression through word categories + +### Technical Benefits +- **Maintainable code**: Builds on existing architecture +- **Scalable design**: Easy to extend to additional categories +- **Robust tracking**: Comprehensive progress persistence +- **User-friendly interface**: Familiar experience with enhanced feedback + +## Next Steps + +1. **Review the implementation plan** at `implementation/plan.md` +2. **Start with Step 1**: Create mastery progress data structures +3. **Follow the checklist**: Each step builds incrementally on previous work +4. **Test thoroughly**: Each step includes specific testing requirements + +## Files to Add to Context + +To begin implementation, add these files to your Q context: +``` +/context add .sop/mastery-mode-planning/**/*.md +``` + +This ensures all project documentation remains available throughout the development process. + +## Success Criteria + +The mastery mode will be considered successful when: +- Leo can practice all words in "common words 3" repeatedly +- Progress counters show accurate "word: X/15" tracking +- Category automatically unlocks "common words 4" when complete +- Other categories display as locked and unclickable +- Existing spelling test functionality remains unchanged +- Progress persists across browser sessions + +The implementation plan provides a clear path to achieve these goals through 12 manageable, testable steps.