Reset Progress

  1. Overview
  2. Hand Off Documentation
  3. Player
  4. Reset Progress

Feature Owner: Joshua Uriel Tribiana
Module: Player
Priority: P2
Status: Implemented in Current Codebase
Date: 07-01-2026

EXECUTIVE SUMMARY

What is this feature?
Reset Progress allows a learner to clear their saved progress for a quest and restart the experience from the beginning. This is currently implemented as a confirmation-based action in the learner UI.

Why does it matter?
Learners may need to restart a quest after changing goals, revisiting content, or recovering from incorrect progression state. A reset action gives them a safe and explicit way to begin over without needing manual intervention.

What’s in scope today?

  • Learner-triggered reset from the quest player UI

  • Learner-triggered reset from the dashboard’s active quests list

  • API endpoint that resets the learner’s progress in the enrollment record

  • Confirmation dialog with a typed safety check

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

A learner who wants to restart a quest has no direct way to clear saved state except through manual intervention or unsupported workarounds.

Pain Point

  • Emotional: Frustration when a learner wants a fresh start but cannot easily recover the original state

  • Functional: Progress is sticky and cannot be cleared from the UI

  • Business Impact: Poor learner autonomy and support overhead

Future State (With Feature)

Learners can reset a quest from the UI, confirming the action, and the application will restore the progress record to a zeroed state so they can restart the quest.

Product Angle

“Give learners control over their learning journey with a simple, explicit reset option.”

2. CODEBASE ASSESSMENT

Current Implementation Status

The feature is implemented and available in the learner experience.

Primary Files

Current Behavior Summary

  • The reset flow is initiated by the learner from either:

    • the quest player UI, or

    • the dashboard’s active quests list

  • The confirmation modal is intentionally explicit and guarded

  • The API resets the enrollment progress payload to:

    • percentage: 0

    • visited_cards: []

    • last_visited_at: null

Strengths Already Present

  • Clear destructive-action warning

  • Typed confirmation reduces accidental resets

  • Server-side validation ensures only an enrolled learner can reset their own quest progress

Gaps / Hardening Opportunities

  • The reset action is currently only surfaced in a limited UI context

  • There is no explicit “reset complete” state transition beyond the dialog and toast

  • The feature does not currently expose a reset history or audit trail

3. 4D FRAMEWORK MAPPING

Diagnose

Learners need a safe way to restart quest progress when they want a fresh attempt.

Design

Use explicit confirmation plus a single server-side reset action tied to the learner’s existing enrollment record.

Develop

A dialog collects confirmation from the learner, then calls the reset API to zero the stored progress.

Deliver

The learner sees their quest progress reset and can begin again without manual support.

4. USER FLOWS

Entry Point

A learner is in either the quest player or the learner dashboard.

Success Criteria

  • The learner can reset the quest progress from the UI

  • The progress record is returned to zeroed state

  • The learner can immediately restart the quest

Happy Path

  1. Learner opens a quest or dashboard view containing the reset option

  2. Learner clicks Reset Progress

  3. A confirmation dialog appears

  4. Learner types RESET and confirms

  5. The frontend calls the reset endpoint

  6. The server updates the learner’s enrollment progress payload to zero

  7. The learner receives a success toast and can start over

Edge Cases

  • Learner is not enrolled in the quest → endpoint returns not found

  • Request body is invalid → endpoint returns validation error

  • Reset fails in the database → endpoint returns an internal error response

Decision Points

  • If the learner does not type RESET → the destructive action remains disabled

  • If the API fails → an error toast is shown and no state change occurs

5. INFORMATION ARCHITECTURE

Primary Information

  • Quest ID for the selected quest

  • Enrollment association for the authenticated learner

  • Current progress payload in the enrollment record

Actions

Primary CTA:

  • Reset Progress

Secondary CTA:

  • Cancel

State Changes

  • percentage resets to 0

  • visited_cards resets to an empty array

  • last_visited_at resets to null

6. WIREFRAMES

The reset experience is a lightweight modal-driven interaction.

Key Screen:

  • Confirmation dialog with warning text and a confirmation input

Annotations:

  • The destructive action is intentionally blocked until the learner confirms with the exact word RESET

  • A cancel action is always available

7. WIREFLOWS

Learner clicks reset → confirmation dialog appears → learner types RESET → request is sent → backend zeroes progress → success toast appears

8. PROTOTYPE

Figma prototype: Not currently available

How to test:

  1. Open a quest in the learner experience

  2. Trigger Reset Progress from the UI

  3. Confirm the dialog appears and the action stays disabled until RESET is typed

  4. Submit the reset and verify the progress becomes 0%

9. DATA MODEL

Core Table

The feature depends on the quest_enrollments table and specifically updates the progress field for the learner’s existing enrollment record.

Progress Reset Shape

The reset operation writes the following payload:

{
  "percentage": 0,
  "visited_cards": [],
  "last_visited_at": null
}

Relationship

This reset does not create a new enrollment record. It mutates the existing one for the authenticated learner and quest.

10. API CONTRACT

Endpoint

POST /api/learner/reset-quest

Request Body

{
  "quest_id": "uuid"
}

Validation Rules

  • quest_id must be a valid UUID

Server Behavior

  • Authenticates the learner

  • Verifies the learner is enrolled in the quest

  • Updates the enrollment progress payload to the reset shape

  • Returns the updated progress object

Expected Response

{
  "success": true,
  "data": {
    "progress": {
      "percentage": 0,
      "visited_cards": [],
      "last_visited_at": null
    }
  }
}

11. DATA REQUIREMENTS

Frontend Needs

  • The selected quest ID

  • A way to display the confirmation modal

  • A callback after successful reset to refresh the learner experience

Backend Needs

  • Authenticated learner identity

  • Enrollment lookup by quest + learner

  • Mutation access to the enrollment progress field

12. SECURITY & AUTHORIZATION

Who can access this feature?

  • Learner: ✓

  • Creator: ✗

  • Reviewer: ✗

Authorization Logic

  • The learner must be authenticated

  • The API confirms the learner is enrolled in the target quest before resetting progress

  • The reset is scoped to the learner’s own enrollment record

13. ERROR HANDLING

Common Errors

  • Invalid request body

  • No enrollment found for that learner and quest

  • Database update failure

Handling Guidance

  • Show a user-facing toast message on failure

  • Keep the dialog open unless the user cancels or the reset succeeds

14. TESTING CHECKLIST

Happy Path

  • Learner can open the reset dialog from the quest player

  • Learner can open the reset dialog from the dashboard

  • Typing RESET enables the destructive action

  • Reset clears progress and returns it to 0%

Edge Cases

  • Invalid request body is rejected

  • A learner that is not enrolled cannot reset the quest

  • Database failure surfaces an error to the UI

15. OPEN QUESTIONS

For Product

  • Should reset be available for all quest states, or only completed quests?

  • Should the UI show a different label or warning for partially completed vs completed progress?

For Engineering

  • Should reset also clear related activity answers or other state beyond the enrollment progress payload?

  • Should the system log reset events for analytics or support troubleshooting?

16. OUT OF SCOPE

Not currently implemented:

  • Reset history or audit log

  • Bulk reset across multiple quests

  • Reset of other learner artifacts beyond the progress payload

17. SUCCESS METRICS

How will we know this feature is working well?

  • Learners can restart quests independently

  • Support tickets related to progress issues decrease

  • Learners feel confident using the reset option when needed

18. DEPENDENCIES

This feature depends on:

  • Learner authentication

  • Enrollment records in quest_enrollments

  • The existing quest progress model

This feature supports:

  • Quest restarts

  • Learner self-service recovery

  • Re-engagement with incomplete content

20. TIMELINE & OWNERSHIP

Implementation Ownership

  • Owner: Joshua Uriel Tribiana

  • QA: Patrick

Written by Uriel Last updated June 30, 2026
Was this article helpful?