🔎 PHASE 1 — UNDERSTAND THE REQUEST 🎯 Primary Objective Implement a complete password-reset flow for existing users. 👤 User-Facing Behavior The user should be able to: 1. Request a password reset using their email address. 2. Receive a password-reset email. 3. Open the reset flow from the email. 4. Enter a new password. 5. Successfully use the new password to log in. ⚙️ Technical Objective Connect the React frontend, Node.js backend, existing authentication system, PostgreSQL database, and existing email service to support password recovery. ✅ Expected Result A valid user can securely reset their password without changing the existing registration or login flow. 📌 Explicit Requirements Password reset must use the registered email address. Existing email service must be used. Reset tokens must be handled securely. Invalid or expired reset requests must fail. Existing authentication functionality must remain unchanged. Unit and integration/API tests are required. ⚠️ Ambiguities The following details are not specified: Exact reset-token expiration duration. Exact password-strength rules. Exact email template. Whether a reset token can be reused. Exact API endpoint names. These must not be invented by the coding agent. --- 📦 PHASE 2 — DEFINE THE SCOPE 🛠️ What MUST Be Implemented Password-reset request functionality. Reset-token generation and validation. Password-reset email integration using the existing email service. Password-reset interface in the React frontend. New-password submission flow. Backend persistence required for reset functionality. Appropriate validation and error handling. Relevant automated tests. 🎨 Frontend Changes Modify the relevant authentication UI to support: Password-reset request. New-password entry. Reset success/failure states. Invalid or expired reset-link handling. Do not modify unrelated authentication screens. 🖥️ Backend Changes Add the backend logic required to: Accept password-reset requests. Validate the supplied email. Generate and manage reset credentials/tokens. Send the reset email. Validate reset credentials. Accept and securely process the new password. 🗄️ Database Changes Modify the existing database structure only if required to securely support password-reset state. The exact schema should be determined from the existing project rather than invented beforehand. 📡 API Changes Add or extend authentication-related API functionality for: Requesting a password reset. Completing a password reset. Exact endpoint names should follow the existing project's conventions. 🚫 What Should Remain Unchanged Existing registration behavior. Existing login behavior. Existing email authentication behavior. Unrelated user functionality. --- 🔨 PHASE 3 — BREAK DOWN THE IMPLEMENTATION 1. 🔐 Password Reset Request Implement the password-reset request flow. What needs to change: Add the relevant frontend request interface. Add backend handling for reset requests. Connect the request to the existing email service. Why: Users need a way to initiate password recovery. Important consideration: The implementation must follow the existing authentication architecture instead of creating a separate authentication system. --- 2. 🎟️ Reset Credential/Token Handling Implement secure reset-token generation and validation. What needs to change: Generate a reset credential for a valid reset request. Associate the reset credential with the appropriate user. Validate the credential when the reset link is used. Reject invalid or expired credentials. Dependency: Existing user authentication/database system. Important consideration: The token must not contain or expose the user's password. --- 3. 📧 Password Reset Email Connect the reset flow to the existing email service. What needs to change: Generate the reset-link information. Pass the required reset information to the existing email mechanism. Constraint: Do not introduce a new email provider when the existing email service already supports the required behavior. --- 4. 🔑 New Password Flow Implement the frontend and backend behavior for setting the new password. What needs to change: Accept the reset credential. Validate the new password according to the project's existing password rules, if such rules already exist. Update the user's password securely. Prevent invalid reset credentials from changing the password. --- 5. 🧪 Testing Add tests covering: Valid reset request. Invalid reset request. Valid reset credential. Invalid reset credential. Expired reset credential. Valid password update. Invalid password submission. Existing login behavior after password reset. --- 👤 PHASE 4 — DEFINE FUNCTIONAL BEHAVIOR 🔄 User Flow 1. User opens the password-reset interface. 2. User enters their email address. 3. System processes the reset request. 4. For a valid account, the existing email service sends reset information. 5. User opens the reset link. 6. System validates the reset credential. 7. User enters a new password. 8. System validates and securely stores the new password. 9. User can authenticate using the new password. 📥 Inputs Reset Request User email address. Password Reset Reset credential/token. New password. Any confirmation field required by the existing UI design. ✅ Success Behavior A valid reset request should initiate the email-based reset flow. A valid reset credential combined with a valid new password should update the user's password. ❌ Failure Behavior The system should reject: Invalid reset credentials. Expired reset credentials. Invalid password input. Requests that violate the existing authentication rules. The frontend should provide an understandable error state without exposing sensitive implementation details. 🔒 Permissions Only the user possessing a valid reset credential should be able to complete the password-reset operation. The reset process must not allow one user to modify another user's password. --- ⚙️ PHASE 5 — TECHNICAL REQUIREMENTS 🔐 Authentication & Security MUST integrate with the existing authentication system. MUST NOT expose passwords through reset tokens, URLs, logs, or API responses. MUST validate reset credentials before changing a password. MUST reject invalid or expired reset credentials. SHOULD follow the project's existing password-storage mechanism. MUST avoid exposing sensitive internal errors to users. 🗃️ Data Flow The expected high-level flow is: React UI → Node.js backend → existing user/authentication system → PostgreSQL For email delivery: Node.js backend → existing email service → user's email The implementation should use existing project conventions wherever available. 🔄 Backward Compatibility Existing: Registration Login Email authentication User accounts must continue functioning after the password-reset feature is introduced. No unrelated authentication behavior should be changed. ⚠️ Unspecified Technical Details Do not invent: API endpoint names. Database column names. Token expiration duration. Email-provider implementation details. Password policy. File paths. Inspect the existing project and follow its established conventions. --- 🧩 PHASE 6 — EDGE CASES 📭 Missing Email If the email field is empty, the request should fail validation before attempting the reset operation. ✉️ Invalid Email Format Reject an incorrectly formatted email according to the application's existing validation approach. 👤 Unknown Account The implementation must follow the project's intended security behavior for an email that does not belong to an existing account. Do not invent a specific response strategy if one is not already established. 🎟️ Invalid Token A modified, malformed, or otherwise invalid reset credential must not allow a password change. ⏰ Expired Token An expired reset credential must be rejected. 🔁 Reused Token The implementation should prevent unintended reuse of a reset credential if the project's security model requires one-time reset credentials. If this behavior is not defined, mark it for clarification rather than silently inventing a rule. 🌐 Network Failure Frontend behavior should handle a failed API request without incorrectly displaying a successful password reset. 📧 Email-Service Failure If the existing email service fails, the backend must not report successful delivery as though the email was sent. 🔑 Invalid New Password The new password must be rejected when it violates the project's established password requirements. 🔄 Existing Login After a successful password reset, the existing login mechanism should continue working with the new password. --- 🔗 PHASE 7 — DEPENDENCY ANALYSIS Dependency Classification Reason Existing authentication system ✅ Confirmed Existing system handles user authentication React frontend ✅ Confirmed Existing project context Node.js backend ✅ Confirmed Existing project context PostgreSQL database ✅ Confirmed Existing project context Existing email service ✅ Confirmed Explicit requirement Existing users table ✅ Confirmed Existing system Existing password-validation rules 🟡 Mentioned but unspecified Requirements do not define exact rules Reset-token expiration duration ❓ Unknown No duration provided Exact API endpoints ❓ Unknown No endpoint structure provided Exact database reset-token schema ❓ Unknown Existing schema was not provided Email template ❓ Unknown No template specification provided Token reuse policy 🟡 Mentioned but unspecified Security behavior needs confirmation 🧠 Dependency Conclusion The implementation should first inspect the existing authentication, user-data, email-service, validation, and API conventions. The coding agent MUST reuse existing mechanisms where applicable and MUST NOT introduce new architecture merely to implement password reset. Sample Test 1 result: The prompt successfully converts a rough feature request into an implementation-ready instruction while explicitly separating confirmed requirements, unspecified details, dependencies, edge cases, and testing expectations.