Owner Nikunj

Single Attempt Screen — Behavioural Spec

screen: Single Attempt Screen

when user opens the screen:
  cases:
  - when: questions are still loading
    then:
      - a loading spinner is shown in the centre of the screen
      - the header and all question content are hidden during loading
      - no question content is visible yet
  - when: no questions are available
    then:
      - a friendly message is shown (e.g. "No question available")
      - the screen does not crash or go blank
      - the error is critically logged with question ID and entry point
  - when: the user previously answered some questions in this session
    then:
      - those questions already show the selected option and explanation
      - the user is not asked to answer them again
  - when: questions finish loading
    then:
      - the header shows current question number and total (e.g. "3 of 5")
    cases:
      - when: the question is from a past year paper
        then:
          - the past-year icon and the exam year are shown next to the counter
      - when: the question is not from a past year paper
        then:
          - no year badge is shown
      - when: question has not been answered yet
        then:
          - the bottom navigation bar (Prev / Next) is not visible
          - the guess toggle ("Mark as Guessed") is visible and clickable
        cases:
          - when: user enables the guess toggle
            then:
              - the toggle shows as active
            cases:
              - when: user taps the active toggle again
                then:
                  - the toggle returns to inactive
      - when: user taps an answer option
        then:
          - the selected option immediately changes colour (green = correct, red = incorrect)
          - the circular indicator on all options fills to show % of users who selected each option
          - the explanation section appears after a brief moment
          - the bottom navigation bar becomes visible
          - the guess toggle is no longer visible
          - the answer is recorded with the "guessing" flag if the toggle was active
          - the answer is saved locally immediately and synced to backend in the background
          - duplicate submissions for the same question are guarded against at the data layer
        cases:
          - when: user tries to tap a different option
            then:
              - nothing changes — the original selection stays locked
              - the explanation remains visible
          - when: the explanation is long
            then:
              - the user can scroll down to read the full content
          - when: the question has subject or sub-topic tags
            then:
              - those tags are visible in the explanation section
            cases:
              - when: user taps the thumbs-up icon
                then:
                  - the thumbs-up is highlighted as selected
              - when: user taps the thumbs-down icon
                then:
                  - the thumbs-down becomes selected and thumbs-up is deselected
              - when: user navigates away and returns to the same question
                then:
                  - the previously selected reaction is still shown
          - when: user navigates to a different question
            then:
              - the scroll position resets back to the top
          - when: device has no internet connection
            then:
              - the answer is accepted and the explanation is shown normally
              - no connectivity error is shown to the user
            cases:
              - when: device reconnects to the internet
                then:
                  - the attempt is synced automatically in the background
      - when: user is on the first question
        then:
          - no "Prev" button is shown
      - when: user is on any question except the last
        then:
          - a "Next →" button is shown
          - when: user taps "Next"
            then:
              - the screen slides to the next question with an animation
              - the progress counter increments
      - when: user is on the last question
        then:
          - the button reads "Done" instead of "Next"
          - when: user taps "Done"
            cases:
            - when: session was opened from a topic listing and all questions are now answered
              then:
                - the user is taken to a "Topic Completed" screen with success animation
            - when: session was opened from a topic listing but some questions were skipped
              then:
                - the user is returned to the previous screen normally
                - no topic-completed screen is shown
            - when: session was not opened from a topic listing
              then:
                - the user is returned to the previous screen normally
            - when: user taps "Done" multiple times rapidly
              then:
                - only one navigation action is triggered
                - the screen closes only once with no errors
      - when: user taps on bookmark icon
        cases:
          - when: the question is not yet bookmarked
            then:
              - the question is bookmarked immediately
              - the icon changes to its filled state
              - the bookmark sheet opens
          - when: the question is already bookmarked
            then:
              - a bottom sheet opens to manage or remove the bookmark
            cases:
              - when: user dismisses the bookmark management sheet
                then:
                  - the sheet closes and the explanation view is shown normally
      - when: user taps the share icon
        then:
          - the device's native share sheet opens with a question link pre-filled
        cases:
          - when: user closes the share sheet and returns to the app
            then:
              - the screen is displayed normally with no stuck overlays
      - when: user taps the report issue icon
        then:
          - a "Report an issue" bottom sheet slides up
        cases:
          - when: description field is empty and user taps submit
            then:
              - nothing is submitted
              - an error or disabled state is shown
          - when: user types a description and taps submit
            then:
              - the report is sent
              - a success confirmation is shown
          - when: user dismisses the sheet without submitting
            then:
              - the sheet closes
              - if the sheet is reopened the description field is empty
      - when: user taps the X button in the header
        then:
          - the session screen closes
          - the user is returned to the previous screen
  - when: user presses the device back button or swipes back
    then:
      - the session screen closes
      - the user is returned to the previous screen