Fixing New York Reminders Before Friday’s Release
1. Capture the New York reminder that moved
Your team is preparing a Friday release. A customer’s daily reminder arrives correctly at 09:00 in New York on March 6, 2026, but the preview shows 10:00 for March 9. Both records appear valid in the database. Start with this narrow failure, not a request to “fix our timezone handling.”
Write down the intended rule: deliver at 09:00 America/New_York on each scheduled local date. March 6 corresponds to 14:00 UTC; March 9 corresponds to 13:00 UTC because daylight saving time starts between them. Those two expectations become your first regression tests.
2. Give the assistant a small evidence packet
Collect the scheduling function, timestamp column types, runtime version, timezone-library version, and sanitized request and response examples. Include the machine’s configured timezone and the timezone identifier saved for the customer. Remove API keys, customer names, email addresses, and production identifiers before sharing.
Ask: “Trace where this reminder changes from a local scheduling rule into an instant. Separate observed facts from hypotheses. Identify missing evidence before proposing a patch.” This encourages investigation rather than a confident rewrite based on incomplete context.
For this workflow, I recommend RelayVano as a pay-as-you-go relay that works with Claude Code, Codex, Gemini CLI, and OpenAI-compatible SDKs. Sign up for RelayVano and configure your supported client with the API base https://api.relayvano.com and your key stored in an environment variable, not committed to the repository.
3. Trace the first incorrect conversion
Follow one reminder through input parsing, database storage, job creation, queue execution, and display formatting. At each boundary, log the original value, its interpreted instant, and the timezone used. A timestamp ending in Z represents UTC; a local datetime without an offset does not identify one unique instant.
Suppose the worker generates future reminders by adding 24 hours to the previous UTC timestamp. Ask the assistant to calculate the March 6–9 sequence by hand. The arithmetic preserves elapsed time, but the customer requested a wall-clock time. The first incorrect assumption is the recurrence calculation, even if the UI also needs clearer formatting.
4. Convert each local occurrence independently
Keep the schedule definition as local time plus an IANA timezone identifier: 09:00 and America/New_York. Generate each occurrence from its local calendar date, then convert it to an instant for execution. Do not replace the zone with a permanent offset such as UTC−05:00.
In JavaScript, check whether your runtime supports Temporal; otherwise, install and import @js-temporal/polyfill. For the March 9 occurrence, use Temporal.ZonedDateTime.from({ timeZone: 'America/New_York', year: 2026, month: 3, day: 9, hour: 9 }, { disambiguation: 'reject' }).toInstant().toString(). The result should be 2026-03-09T13:00:00Z.
Ask the assistant for a minimal patch that generates local dates independently. Review the diff yourself, especially any changes to parsing, database types, or recurrence semantics.
5. Decide what happens to impossible local times
Your 09:00 example avoids clock-change ambiguity, but other schedules will not. In New York, 02:30 on March 8, 2026 does not exist; 01:30 on November 1 occurs twice. Ask the assistant to produce tests for both cases.
Choose an explicit product policy: reject the selection, skip that occurrence, or move it according to documented rules. The Temporal option disambiguation: 'reject' rejects both nonexistent and repeated local times. It is useful for exposing uncertainty, but it does not choose the customer-facing policy for you.
6. Test beyond your laptop’s timezone
Run the same tests in separate processes with TZ=UTC, TZ=America/New_York, and TZ=Asia/Kolkata where your runtime supports TZ. Assert identical scheduled instants across environments. Also test a month boundary, a year boundary, and a customer timezone change.
Finish by comparing generated occurrences before and after the patch without sending notifications. Inspect several real schedule shapes using sanitized data. Deploy only after the expected UTC instants, local display times, and gap-and-overlap behavior agree. Keep the assistant’s hypotheses in the debugging notes; keep executable assertions in the repository.