Skip to content

Commit c41dc02

Browse files
jrollinjrollin
committed
docs: update missing feature task and requirements
1 parent 82d51ac commit c41dc02

File tree

4 files changed

+203
-229
lines changed

4 files changed

+203
-229
lines changed

‎docs/features/common-words/requirements.md‎

Lines changed: 70 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,72 @@
1-
# Common Word Training - Requirements
2-
3-
**Feature**: Common Word Training
4-
**Phase**: 3
5-
**Status**: ✅ Complete
6-
**Last Updated**: 2025-12-30
1+
# Common Words - Requirements
72

83
## Overview
9-
10-
Extends typing practice with the 500 most common words in French and English, enabling realistic vocabulary training with progressive difficulty levels.
11-
12-
## Requirements (EARS Format)
13-
14-
### US-1 Word Database
15-
16-
WHEN the system initializes common word training
17-
THE SYSTEM SHALL provide 500 most common words per language (French, English)
18-
19-
### US-2 Normalize Frequency Weights
20-
WHEN words are selected from corpus data
21-
THE SYSTEM SHALL normalize frequency weights to 0.70-1.00 range
22-
23-
### US-3 Sort Words by Frequency
24-
WHEN words are ordered in the database
25-
THE SYSTEM SHALL sort by descending frequency (most common first)
26-
27-
### US-4 Progressive Difficulty Levels
28-
29-
WHEN user selects Level 1
30-
THE SYSTEM SHALL provide practice with top 50 most common words
31-
32-
### US-5 Level 2 Word Selection
33-
WHEN user selects Level 2
34-
THE SYSTEM SHALL provide practice with top 100 most common words
35-
36-
### US-6 Level 3 Word Selection
37-
WHEN user selects Level 3
38-
THE SYSTEM SHALL provide practice with top 200 most common words
39-
40-
### US-7 Level 4 Word Selection
41-
WHEN user selects Level 4
42-
THE SYSTEM SHALL provide practice with all 500 most common words
43-
44-
### US-8 Drill Mode (Level 1)
45-
46-
WHEN user practices Level 1 common words
47-
THE SYSTEM SHALL generate word repetition drills (e.g., "the the be be to to")
48-
49-
### US-9 Repeat Each Word Twice
50-
WHEN generating drill content
51-
THE SYSTEM SHALL repeat each word exactly 2 times consecutively
52-
53-
### US-10 Sentence Mode (Levels 2-4)
54-
55-
WHEN user practices Levels 2-4 common words
56-
THE SYSTEM SHALL generate natural word sequences mimicking sentences
57-
58-
### US-11 Frequency-Weighted Selection
59-
WHEN selecting words for sentence mode
60-
THE SYSTEM SHALL use frequency-weighted random selection
61-
62-
### US-12 High-Frequency Bias
63-
WHEN applying frequency weighting
64-
THE SYSTEM SHALL select 70% of words from top 20% (high-frequency)
65-
66-
### US-13 Full Pool Selection
67-
WHEN applying frequency weighting
68-
THE SYSTEM SHALL select 30% of words from full pool (all levels)
69-
70-
### US-14 Lesson Integration
71-
72-
WHEN user views lesson menu
73-
THE SYSTEM SHALL display 4 French common word lessons
74-
75-
### US-15 English Lessons Display
76-
WHEN user views lesson menu
77-
THE SYSTEM SHALL display 4 English common word lessons
78-
79-
### US-16 Lesson Ordering
80-
WHEN lessons are displayed
81-
THE SYSTEM SHALL position common word lessons after trigram lessons
82-
83-
### US-17 Content Generation
84-
85-
WHEN generating practice content
86-
THE SYSTEM SHALL limit output to specified character length
87-
88-
### US-18 Truncate at Boundary
89-
WHEN character length is reached
90-
THE SYSTEM SHALL truncate content at exact character boundary
91-
92-
### US-19 UTF-8 Character Counting
93-
WHEN using multi-byte UTF-8 characters
94-
THE SYSTEM SHALL count characters (not bytes) for length constraints
95-
96-
### US-20 Data Sources
97-
98-
WHEN sourcing English word frequencies
99-
THE SYSTEM SHALL use COCA (Corpus of Contemporary American English) data
100-
101-
### US-21 French Word Database
102-
WHEN sourcing French word frequencies
103-
THE SYSTEM SHALL use Lexique 3.83 database
104-
105-
### US-22 Testing Requirements
106-
107-
WHEN testing word databases
108-
THE SYSTEM SHALL verify exactly 500 words per language
109-
110-
### US-23 Verify Frequency Order
111-
WHEN testing frequency ordering
112-
THE SYSTEM SHALL verify descending frequency order for all words
113-
114-
### US-24 Test Drill Mode
115-
WHEN testing content generation
116-
THE SYSTEM SHALL verify drill mode produces word repetition
117-
118-
### US-25 Test Sentence Mode
119-
WHEN testing content generation
120-
THE SYSTEM SHALL verify sentence mode produces word variety
121-
122-
### US-26 Test Level Counts
123-
WHEN testing level selection
124-
THE SYSTEM SHALL verify correct word counts (50/100/200/500)
125-
126-
## Success Criteria
127-
128-
- ✅ 8 new lessons in menu (French L1-4, English L1-4)
129-
- ✅ All 129 tests pass (+13 new tests)
130-
- ✅ 500 words per language with normalized frequencies
131-
- ✅ Drill mode shows repetition pattern
132-
- ✅ Sentence mode shows variety and frequency bias
133-
- ✅ Content respects character length constraints
134-
- ✅ UTF-8 character counting works correctly
135-
- ✅ No duplicate words in databases
136-
137-
## Dependencies
138-
139-
- **Phase 2 (Bigrams)**: Shares Language enum
140-
- **Phase 2 (Trigrams)**: Follows same architectural pattern
141-
- **rand crate**: Required for frequency-weighted random selection
142-
143-
## Non-Requirements
144-
145-
- ❌ No word metadata beyond frequency (no POS tags, difficulty ratings)
146-
- ❌ No language-specific grammar rules or sentence structure
147-
- ❌ No word definitions or translations
148-
- ❌ No adaptive word selection based on user performance (handled by Adaptive Mode)
4+
The Common Words feature generates typing drills using frequently used words in French and English. This helps users improve their typing speed and accuracy by practicing realistic and commonly encountered vocabulary.
5+
6+
## User Stories
7+
8+
### US-1 Generate Common Word Drills
9+
```
10+
WHEN a user selects the Common Words category
11+
THE SYSTEM SHALL generate drills using frequently used words
12+
AND ensure the drills are randomized for variety.
13+
```
14+
15+
### US-2 Support French and English Words
16+
```
17+
WHEN generating common word drills
18+
THE SYSTEM SHALL support both French and English word lists
19+
AND ensure the words are relevant to typing practice.
20+
```
21+
22+
### US-3 Validate Word Lists
23+
```
24+
WHEN generating common word drills
25+
THE SYSTEM SHALL ensure all words are valid for the AZERTY layout
26+
AND exclude invalid or unsupported words.
27+
```
28+
29+
### US-4 Progressive Difficulty
30+
```
31+
WHEN generating common word drills
32+
THE SYSTEM SHALL organize words into progressive difficulty levels
33+
TO ensure a smooth learning curve.
34+
```
35+
36+
### US-5 Contextual Sentences
37+
```
38+
WHEN generating common word drills at higher difficulty levels
39+
THE SYSTEM SHALL generate realistic sentences using the words
40+
TO improve contextual typing practice.
41+
```
42+
43+
## Integration Requirements
44+
45+
### US-6 Common Words Lesson Selection
46+
```
47+
THE SYSTEM SHALL add common words training options to the lesson selection menu
48+
- French Common Words - Level 1-4
49+
- English Common Words - Level 1-4
50+
```
51+
52+
### US-7 Common Words Statistics Tracking
53+
```
54+
WHEN a user completes a common words lesson
55+
THE SYSTEM SHALL track per-word accuracy and speed metrics
56+
AND integrate with the existing analytics system.
57+
```
58+
59+
## Future Phase Requirements
60+
61+
### US-8 Custom Word Lists (Phase 3+)
62+
```
63+
FUTURE: Allow users to create custom word lists for practice.
64+
FUTURE: Import words from user-provided text samples.
65+
```
66+
67+
### US-9 Word Mastery Tracking (Phase 3+)
68+
```
69+
FUTURE: Track mastery level for each word.
70+
FUTURE: Recommend practice based on weak words.
71+
FUTURE: Implement spaced repetition for word retention.
72+
```

‎docs/features/common-words/tasks.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Common Words - Tasks
2+
3+
## Overview
4+
This document outlines the tasks required to implement or verify the Common Words feature. The feature is **already complete**, but this file serves as a reference for future maintenance or extensions.
5+
6+
## Tasks
7+
8+
### 1. Data Preparation and Validation
9+
- [x] **Task 1.1**: Run `scripts/fetch_common_words.py` to generate word data for English and French.
10+
- [x] **Task 1.2**: Validate the generated word data for accuracy and completeness.
11+
- [x] **Task 1.3**: Normalize word frequencies to the 0.70-1.00 range.
12+
- [x] **Task 1.4**: Ensure exactly 500 words exist per language.
13+
- [x] **Task 1.5**: Verify that words are sorted by descending frequency.
14+
15+
### 2. Data Structures and Word Definition
16+
- [x] **Task 2.1**: Implement the `Word` struct in `src/content/common_word.rs`.
17+
- [x] **Task 2.2**: Define `french_words()` and `english_words()` functions in `src/content/common_word.rs`.
18+
- [x] **Task 2.3**: Ensure the `Word` struct includes `text`, `frequency`, and `length` fields.
19+
- [x] **Task 2.4**: Validate that all words are compatible with the AZERTY layout.
20+
21+
### 3. Common Word Generator
22+
- [x] **Task 3.1**: Implement the `CommonWordGenerator` struct in `src/content/common_word_generator.rs`.
23+
- [x] **Task 3.2**: Add `new()` method to initialize the generator with language-specific words.
24+
- [x] **Task 3.3**: Implement `generate()` method to support drill and sentence modes.
25+
- [x] **Task 3.4**: Add `select_words_for_level()` method to filter words by difficulty level.
26+
- [x] **Task 3.5**: Implement `generate_drill_mode()` and `generate_sentence_mode()` methods.
27+
- [x] **Task 3.6**: Ensure frequency-weighted random selection in sentence mode (70% top 20%, 30% full pool).
28+
- [x] **Task 3.7**: Implement UTF-8 character counting for length constraints.
29+
30+
### 4. Lesson Integration
31+
- [x] **Task 4.1**: Extend the `LessonType` enum in `src/content/lesson.rs` to include `CommonWords`.
32+
- [x] **Task 4.2**: Implement `common_word_lessons()` function in `src/content/lesson.rs` to generate lessons for all levels.
33+
- [x] **Task 4.3**: Add metadata (title, description) for common word lessons.
34+
35+
### 5. Menu Integration
36+
- [x] **Task 5.1**: Add common word lessons to the lesson selection menu in `src/app.rs`.
37+
- [x] **Task 5.2**: Ensure common word lessons are categorized under "French Common Words" and "English Common Words".
38+
- [x] **Task 5.3**: Position common word lessons after trigram lessons in the menu.
39+
40+
### 6. Testing
41+
- [x] **Task 6.1**: Write unit tests for the `Word` struct and data in `src/content/common_word.rs`.
42+
- [x] **Task 6.2**: Write unit tests for the `CommonWordGenerator` in `src/content/common_word_generator.rs`.
43+
- [x] **Task 6.3**: Verify that all words and their frequencies are valid.
44+
- [x] **Task 6.4**: Test drill mode for word repetition.
45+
- [x] **Task 6.5**: Test sentence mode for frequency-weighted random selection.
46+
- [x] **Task 6.6**: Test level selection for correct word counts (50/100/200/500).
47+
- [x] **Task 6.7**: Test UTF-8 character counting for multi-byte characters.
48+
49+
### 7. Documentation
50+
- [x] **Task 7.1**: Update `docs/features/common-words/requirements.md` with feature requirements.
51+
- [x] **Task 7.2**: Update `docs/features/common-words/design.md` with implementation details.
52+
- [x] **Task 7.3**: Ensure all tasks in this file are updated as completed.
53+
54+
### 8. Future Work
55+
- [ ] **Task 8.1**: Add support for custom word lists (user-provided words).
56+
- [ ] **Task 8.2**: Implement word mastery tracking and spaced repetition.
57+
- [ ] **Task 8.3**: Add support for additional languages (e.g., Spanish, German).
58+
- [ ] **Task 8.4**: Extend sentence mode with grammar rules for more natural sentences.

‎docs/features/trigram-training/requirements.md‎

Lines changed: 25 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,27 @@
11
# Trigram Training - Requirements
22

3-
> **Purpose**: Captures requirements for trigram (three-letter combination) practice
4-
> **Module**: `src/content/` (extension)
5-
> **Next Step**: See `design.md` for trigram generation strategy
6-
7-
## Trigram Practice Requirements
8-
9-
### US-1 Trigram Training Mode
10-
THE SYSTEM SHALL provide dedicated lessons for practicing common three-letter combinations (trigrams)
11-
12-
### US-2 French Trigram Support
13-
WHEN a user selects French trigram training
14-
THE SYSTEM SHALL generate practice content with the 20 most common French trigrams including:
15-
- "les" (les, lesquels)
16-
- "des" (des, depuis)
17-
- "ent" (ment, moment, parent)
18-
- "ion" (action, nation, question)
19-
- "que" (que, quelque, chaque)
20-
- "ons" (nous, sons, raisons)
21-
- "ant" (avant, pendant, durant)
22-
- "ait" (fait, avait, était)
23-
- "est" (est, ouest, reste)
24-
- "our" (pour, jour, toujours)
25-
- And 10 more high-frequency trigrams
26-
27-
### US-3 English Trigram Support
28-
WHEN a user selects English trigram training
29-
THE SYSTEM SHALL generate practice content with the 20 most common English trigrams including:
30-
- "the" (the, them, these)
31-
- "and" (and, hand, stand)
32-
- "ing" (ing, thing, going)
33-
- "ion" (tion, nation, action)
34-
- "ent" (ent, went, bent)
35-
- "for" (for, before, forget)
36-
- "her" (her, here, where)
37-
- "ter" (ter, after, water)
38-
- "hat" (that, what, chat)
39-
- "thi" (this, thing, think)
40-
- And 10 more high-frequency trigrams
41-
42-
### US-4 Trigram Difficulty Levels
43-
THE SYSTEM SHALL organize trigram lessons in progressive difficulty:
44-
- Level 1: 5 most common trigrams (drill mode)
45-
- Level 2: 10 most common trigrams (word mode)
46-
- Level 3: 15 most common trigrams (mixed mode)
47-
- Level 4: All 20 trigrams (full practice)
48-
49-
### US-5 Trigram Context Generation
50-
WHEN generating trigram practice content
51-
THE SYSTEM SHALL use three generation modes:
52-
- Level 1 (Drill): Pure repetition - "the the the and and and"
53-
- Level 2 (Word): Contextual words - "the them these and hand stand"
54-
- Level 3-4 (Mixed): Realistic sentences combining multiple trigram words
55-
56-
### US-6 Trigram Frequency Weighting
57-
THE SYSTEM SHALL order trigrams by real-world frequency based on corpus analysis
58-
- English: Based on Peter Norvig's English letter frequency data
59-
- French: Based on Lexique database trigram frequencies
60-
- Normalized to 0.70-1.00 range for typing practice
61-
62-
## Integration Requirements
63-
64-
### US-7 Trigram Lesson Selection
65-
THE SYSTEM SHALL add trigram training options to the lesson selection menu
66-
- French Trigrams - Level 1-4
67-
- English Trigrams - Level 1-4
68-
69-
### US-8 Trigram Statistics Tracking
70-
WHEN a user completes a trigram lesson
71-
THE SYSTEM SHALL track per-trigram accuracy and speed metrics
72-
- Integrated with existing analytics system
73-
- Per-trigram performance data for adaptive mode
74-
75-
## Future Phase Requirements
76-
77-
### US-9 Custom Trigram Sets (Phase 3+)
78-
FUTURE: Allow users to create custom trigram practice sets
79-
FUTURE: Import trigrams from user's own code/text samples
80-
FUTURE: Language-specific trigrams (Spanish, German, etc.)
81-
82-
### US-10 Trigram Mastery Tracking (Phase 3+)
83-
FUTURE: Track mastery level for each trigram
84-
FUTURE: Recommend practice based on weak trigrams
85-
FUTURE: Spaced repetition for trigram retention
3+
## Overview
4+
The Trigram Training feature generates typing drills based on triplets of characters (trigrams). This helps users improve their typing speed and accuracy by practicing common and challenging character sequences.
5+
6+
## User Stories
7+
8+
### US-1 Generate Trigram Drills
9+
```
10+
WHEN a user selects the Trigram Training category
11+
THE SYSTEM SHALL generate drills containing triplets of characters
12+
AND ensure the drills are randomized for variety.
13+
```
14+
15+
### US-2 Support Common and Rare Trigrams
16+
```
17+
WHEN generating trigram drills
18+
THE SYSTEM SHALL include both common and rare trigrams
19+
TO ensure comprehensive practice.
20+
```
21+
22+
### US-3 Validate Trigram Content
23+
```
24+
WHEN generating trigram drills
25+
THE SYSTEM SHALL ensure all trigrams are valid for the AZERTY layout
26+
AND exclude invalid or unsupported sequences.
27+
```

0 commit comments

Comments
 (0)