Debugging With an Assistant: Evidence, Not Guesses

The problem

A date filter returns no results for some users. You paste the function and ask "why doesn't this work?". The assistant suggests three plausible changes. None helps. You apply all three anyway, and now a different test fails.

Real-world analogy

A doctor asked "I feel bad, fix it" can only guess. A doctor given symptoms, test results and what you have already tried can diagnose. Assistants are the same: evidence in, diagnosis out.

The idea

• Reproduce the bug with the smallest possible input, ideally as a failing test.
• Give the evidence: exact error message and stack trace, input, expected versus actual output, environment (versions, time zone).
• Say what you already tried and what you ruled out.
• Ask for a hypothesis and a check, not a fix: "what could cause this, and how can we confirm it?"
• Change one thing at a time and re-run the reproduction.

The code

A minimal reproduction makes the cause obvious: the filter compares a time-zone-aware timestamp with a naive date range built in local time:

from datetime import datetime, timezone, timedelta

order_created = datetime(2026, 3, 2, 2, 30, tzinfo=timezone.utc)       # stored in UTC: 21:30 on 1 March in UTC-5
user_tz = timezone(timedelta(hours=-5))                                 # user in UTC-5

def in_day_buggy(ts, day):
    start = datetime(day.year, day.month, day.day)                      # naive, assumes UTC by accident
    return start <= ts.replace(tzinfo=None) < start + timedelta(days=1)

def in_day(ts, day, tz):
    start = datetime(day.year, day.month, day.day, tzinfo=tz)           # the user's local day
    return start <= ts < start + timedelta(days=1)

local_day = order_created.astimezone(user_tz).date()
print("order is on the user's local day:", local_day)
print("buggy filter finds it:", in_day_buggy(order_created, local_day))
print("fixed filter finds it:", in_day(order_created, local_day, user_tz))

order is on the user's local day: 2026-03-01
buggy filter finds it: False
fixed filter finds it: True

Common mistakes

• Asking for a fix without the error message or a reproduction.
• Applying several suggested changes at once, so nothing can be attributed.
• Accepting a fix that makes the symptom disappear without understanding the cause.
• Not adding the reproduction as a regression test after fixing.

Key points

• Debug from a minimal reproduction and the exact evidence.
• Ask for hypotheses and checks, and change one thing at a time.
• Keep the reproduction as a regression test.

Further reading: Claude Code common workflows: fix bugs · Python datetime: aware and naive objects