| # exercise-screen Specification |
|
|
| ## Purpose |
| The screen where a student practices one skill with the exercise bank's questions: instant feedback that teaches from the mistake, help when stuck, and the board to work things out. |
|
|
| ## Requirements |
|
|
| ### Requirement: Layout |
| The exercise screen SHALL open as a sheet over the path. Its header SHALL show the lesson's name, the skill's name, a completed mark when the skill is mastered, a board button, a "?" help button and a close button, with the skill's short explanation under it. |
|
|
| #### Scenario: Opening a skill |
| - **WHEN** a student opens the skill "פירוק טרינום" |
| - **THEN** the sheet shows the lesson's name, "פירוק טרינום", the board, "?" and close buttons, and the explanation |
|
|
| ### Requirement: One question at a time |
| The sheet SHALL show one question: its text with formulas, its figure or graph if any, and its choices in a new random order each time it is shown, with "question n of N" and a row of N dots, one for each question of the round. A round SHALL be the skill's practice questions, at most 10, each shown once. A dot SHALL be filled for a right answer and marked "✗" for a wrong one, and empty for a question not yet answered. |
|
|
| #### Scenario: Same question again |
| - **WHEN** a question is shown a second time |
| - **THEN** its choices may be in a different order, and the server still grades by the bank's choice |
|
|
| #### Scenario: A skill with 30 questions |
| - **WHEN** a student opens a skill that has 30 questions in the bank |
| - **THEN** the sheet says "question n of 10" and shows 10 dots, and only the first 10 questions come up in the round |
|
|
| #### Scenario: Dots after a mistake |
| - **WHEN** a student answers the 1st question right and the 2nd wrongly |
| - **THEN** the first dot is filled, the second is marked wrong, and the sheet says "question 3 of 10" |
|
|
| ### Requirement: A right answer |
| A right answer SHALL get a short celebration and the count of right answers in a row. After a short countdown the next question SHALL appear; the student can skip or cancel the countdown. After the last question of the round there is no countdown: the sheet offers the round's result. |
|
|
| #### Scenario: Countdown |
| - **WHEN** a student answers correctly |
| - **THEN** a countdown to the next question starts, and pressing "next" shows it at once |
|
|
| ### Requirement: A wrong answer |
| A wrong answer SHALL be quiet and SHALL show the name and tip of the mistake attached to the chosen choice, about the mistake and not the student. The chosen choice SHALL be marked as wrong with a symbol and a word on the choice itself ("✗ לא נכון"), not by colour alone, and no other choice SHALL be marked. It MUST NOT reveal the correct answer, and the question MUST NOT come back in the same round. The sheet SHALL offer "לשאלה הבאה" (after the last question: the round's result). When the mistake names a skill to go back to, the feedback SHALL link to it. |
|
|
| #### Scenario: Sign mistake |
| - **WHEN** a student picks a choice tagged with "טעות סימן באיבר האמצעי" |
| - **THEN** the mistake's name and tip are shown and no choice is marked as correct |
|
|
| #### Scenario: The chosen choice is marked |
| - **WHEN** a student picks a wrong choice |
| - **THEN** that choice shows "✗ לא נכון" and a stronger border, and every other choice looks as it did |
|
|
| #### Scenario: A wrong question does not return |
| - **WHEN** a student answers the 3rd question wrongly |
| - **THEN** it is not shown again in the round, and the round ends after the 10th question |
|
|
| ### Requirement: A different next question |
| After any answer the next question SHALL be a question of the round that was not answered yet, picked at random. When every question of the round was answered, there is no next question and the sheet shows the round's result. A skill with one question has a round of one question. |
|
|
| #### Scenario: After a mistake |
| - **WHEN** a student answers a question wrongly |
| - **THEN** the next question is not the one just answered |
|
|
| #### Scenario: Never twice in a round |
| - **WHEN** a student answers all 10 questions of a skill |
| - **THEN** each question was shown exactly once, and none came back |
|
|
| ### Requirement: Help |
| The "?" button SHALL show the skill's explanation and, where the bank has one, a solved example. Opening it SHALL make the answer to the question on screen not count for mastery; that answer still counts for the daily goal. |
|
|
| #### Scenario: Help opened |
| - **WHEN** a student opens "?" and then answers correctly |
| - **THEN** the answer is stored as given with help and does not count toward mastery |
|
|
| ### Requirement: Related skills |
| The sheet SHALL show the skills this one requires and the skills it opens as tappable chips, which open those skills and never lock anything. |
|
|
| #### Scenario: Required skill |
| - **WHEN** a student taps a "requires" chip |
| - **THEN** that skill's exercise screen opens |
|
|
| ### Requirement: Resuming |
| Reopening a skill SHALL continue with the question that was on screen, and an answer to a question that is no longer on screen SHALL be refused. |
|
|
| #### Scenario: Two tabs |
| - **WHEN** a student answers in one tab a question that another tab already replaced |
| - **THEN** the answer is refused and the screen shows the current question |
|
|
| ### Requirement: Skill without questions |
| A skill with no questions SHALL say there is no practice for it yet, and cannot be mastered. |
|
|
| #### Scenario: Empty skill |
| - **WHEN** a student opens a skill with no questions |
| - **THEN** the sheet says there is no practice yet |
|
|
| ### Requirement: A round's result |
| After the last answer of a round the sheet SHALL show how many questions were answered right out of the round's questions ("N מתוך 10") and, for each wrong answer, the question, the mistake's name and tip and a link to the skill to go back to when the bank names one. It MUST NOT show the correct answers. The result SHALL be shown again after leaving and returning, until a new round is started. |
|
|
| #### Scenario: Result |
| - **WHEN** a student answers the 10th question of a round with 7 right |
| - **THEN** the sheet shows "7 מתוך 10" and the three mistakes with their names and tips |
|
|
| #### Scenario: Leaving in the middle |
| - **WHEN** a student leaves after the 4th question and comes back |
| - **THEN** the round continues with the 5th question, and the dots show the first four answers |
|
|
| ### Requirement: A new round |
| The result SHALL offer "סבב חדש", which starts a new round with all the skill's practice questions again in a new random order, and a way back to the path. Mastery SHALL be counted across rounds as before. |
|
|
| #### Scenario: Another round |
| - **WHEN** a student presses "סבב חדש" after a finished round |
| - **THEN** a round of the 10 questions starts again, with empty dots |
|
|
| #### Scenario: Coming back after a finished round |
| - **WHEN** a student leaves after finishing a round and opens the skill again |
| - **THEN** the result is shown, and "סבב חדש" starts a round of the 10 questions again |
|
|
| ### Requirement: Thinking indicator |
| As soon as a choice is tapped, the sheet SHALL show that the answer is being checked: the tapped choice shows a spinner, a status line says "בודקים…", and the other choices are dimmed and cannot be tapped. The indicator SHALL go away when the answer arrives or fails, and it MUST NOT depend on motion: with reduced motion the words are shown and the spinner is still. |
|
|
| #### Scenario: A slow answer |
| - **WHEN** a student taps a choice and the server takes two seconds |
| - **THEN** during those two seconds the tapped choice shows a spinner, "בודקים…" is shown and the other choices cannot be tapped, and the result replaces them when it arrives |
|
|
| #### Scenario: An error |
| - **WHEN** the answer cannot be sent |
| - **THEN** the indicator goes away, the choices can be tapped again and the error is shown |
|
|
