5304e4da4e
docs: comprehensive problem generation documentation
...
Created three documentation files covering the problem generation system:
**1. PROBLEM_GENERATION_ARCHITECTURE.md** (Technical Deep Dive)
- Complete architecture overview for developers
- Two generation strategies: generate-all + shuffle vs retry-based
- Problem space estimation formulas (exact and heuristic)
- Edge cases: single-digit 100% regrouping (45 problems), mixed mastery, subtraction borrowing
- Performance considerations and trade-offs
- Logging patterns and debugging
- Testing checklist
- Future improvements
**2. .claude/PROBLEM_GENERATION.md** (Quick Reference for AI)
- Fast lookup for Claude Code and developers
- File locations and key functions
- Strategy selection logic with code examples
- Critical edge cases with explanations
- Debugging commands
- Common modifications guide
- Problem space estimation formulas
- Testing checklist
- Quick Q&A section
**3. USER_WARNING_IMPROVEMENTS.md** (UX Enhancement Plan)
- Current warning system review
- 7 recommended improvements with designs:
1. Config panel live indicator (HIGH PRIORITY)
2. Slider visual feedback (MEDIUM)
3. Smart Mode suggestion (MEDIUM)
4. Download confirmation (LOW)
5. Regrouping tooltip (LOW)
6. Digit range recommendations (MEDIUM)
7. Mixed mastery validation (LOW)
- Component structure suggestions
- Implementation phases
- Testing plan
- Analytics recommendations
**Enhanced Inline Comments:**
- Added comprehensive docstrings to `generateProblems()`
- Documented strategy selection logic with examples
- Explained cycling behavior for both modes
- Added section headers for generate-all and retry-based branches
- Documented progressive vs constant difficulty modes
- Added comments for mastery mixed mode differences
**Key Insights Documented:**
- Only 45 unique 1-digit 100% regrouping problems exist
- Cycling maintains order (non-interpolate) or clears seen set (interpolate)
- Retry limit reduced from 3000 to 100 for performance
- Mixed mastery skips validation due to separate configs
- Subtraction 2-digit can't have 2+ borrows (mathematical impossibility)
- Borrowing across zeros counts each zero as additional borrow
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-12 09:19:20 -06:00
Thomas Hallock