Product case study · November 16, 2026

Give Claude Code two clocks to catch a deadline bug

Use a small Python lab to teach Claude Code what a deadline means: compare UTC instants, reject missing offsets, and keep the exact cutoff explicit.

Reading time
6 min
Checked
Nov 16, 2026
Two paper clock discs converge on a charcoal timeline beside blue and ochre deadline cards
Different clock readings can describe the same instant. Make the agent prove it.
Bottom line

Define the instant and the cutoff rule before asking an agent to fix date handling.

A submission stamped 09:30 can arrive before an 08:00 deadline. The missing detail is the offset: 09:30 at +02:00 is 07:30 UTC. An agent that compares the strings can confidently reject an on-time submission.

This is a useful small job for Claude Code because “fix the timezone bug” leaves the most important decisions unstated. Does the exact deadline count? What happens when an input has no offset? Give the agent those answers before it writes the repair.

This authored lab uses fictional timestamps, Bash on macOS, Linux or WSL, Python 3.11 or later, and an installed, signed-in Claude Code. The reference code and checks were run locally; the prompts are a walkthrough, not a report of a live Claude session. Official sources were checked November 16, 2026.

Make the wrong answer easy to see

Create a disposable folder and a deliberately broken helper:

deadline_lab=$(mktemp -d /tmp/claude-deadline.XXXXXX)
cd "$deadline_lab"
python3 --version
cat > deadline.py <<'PY'
def on_time(submitted, cutoff):
    return submitted <= cutoff
PY
python3 -c 'from deadline import on_time; print(on_time("2026-11-16T09:30:00+02:00", "2026-11-16T08:00:00+00:00"))'

The original returns False. Read the pair as UTC instants and the answer should be True. String ordering has answered a different question.

Now write the contract:

cat > SPEC.md <<'SPEC'
on_time(submitted, cutoff) accepts two timestamp strings.
Use datetime.fromisoformat's accepted input syntax on Python 3.11+.
Both inputs must include an explicit UTC offset (Z is also accepted).
Return True when submitted is before or exactly at cutoff.
Return False when submitted is after cutoff.
Raise ValueError for malformed input or a missing offset on either input.
Compare instants, not the written clock times.
Do not read the current clock or assume the computer's local timezone.
Recurring schedules and named timezones are outside this exercise.
SPEC

Python’s datetime documentation distinguishes aware values, which carry timezone information, from naive values, which do not identify an unambiguous instant. It also documents fromisoformat and conversion with astimezone. This lab deliberately accepts that parser’s syntax; it does not claim to validate every external timestamp standard.

My preference is to reject missing offsets at this boundary. Quietly assuming the server’s local timezone makes the same input mean different things on different machines.

Give Claude the cases that settle the argument

Save this as test_deadline.py in the practice folder:

import unittest
from deadline import on_time


class DeadlineTests(unittest.TestCase):
    def test_instants(self):
        cutoff = "2026-11-16T08:00:00+00:00"
        cases = [
            ("2026-11-16T09:30:00+02:00", True),
            ("2026-11-16T03:30:00-05:00", False),
            ("2026-11-16T16:00:00+08:00", True),
            ("2026-11-16T08:00:01Z", False),
        ]
        for submitted, expected in cases:
            with self.subTest(submitted=submitted):
                self.assertIs(on_time(submitted, cutoff), expected)

    def test_rejects_missing_offsets(self):
        aware = "2026-11-16T08:00:00+00:00"
        naive = "2026-11-16T08:00:00"
        for pair in [(naive, aware), (aware, naive)]:
            with self.subTest(pair=pair):
                with self.assertRaises(ValueError):
                    on_time(*pair)

    def test_rejects_malformed_input(self):
        aware = "2026-11-16T08:00:00+00:00"
        for pair in [("not-a-date", aware), (aware, "not-a-date")]:
            with self.subTest(pair=pair):
                with self.assertRaises(ValueError):
                    on_time(*pair)

Run the baseline yourself:

python3 -m unittest -v test_deadline

There are six core cases: four comparisons and two missing-offset checks, plus two malformed-input checks. unittest reports three test methods; the loops use subtests. Python’s unittest reference documents this command and the assertion helpers.

The positive-offset example arrives early. The negative-offset example arrives late despite its smaller written hour. The Hong Kong offset example lands exactly on the cutoff, and the Z example misses it by one second. These fixed inputs are more useful than checking against the current time: they mean the same thing tomorrow.

Ask for a bounded repair

Start claude from the practice folder and paste:

Read SPEC.md, deadline.py and test_deadline.py.
Explain the UTC instant represented by each comparison case.
Run python3 -m unittest -v test_deadline and identify the behavioral failures.
Then change only deadline.py to satisfy SPEC.md, using the standard library.
Keep the specification and tests unchanged. Do not install packages.
Run the same command again and report its actual result.
Explain how you handle missing offsets and equality at the cutoff.
Do not add scheduling features, commit changes or delegate work.

Anthropic’s common workflows describes starting Claude in a project directory and giving it concrete debugging and testing tasks. Review tool permission requests against this small exercise; the prompt itself is not a filesystem sandbox.

A straightforward reference implementation is:

from datetime import datetime, timezone


def parse_instant(value):
    parsed = datetime.fromisoformat(value)
    if parsed.utcoffset() is None:
        raise ValueError("timestamp requires a UTC offset")
    return parsed.astimezone(timezone.utc)


def on_time(submitted, cutoff):
    return parse_instant(submitted) <= parse_instant(cutoff)

Both inputs are parsed, checked for offsets, and converted to UTC before comparison. Equality is deliberately allowed. The conversion changes the representation while preserving the instant. Calling replace(tzinfo=timezone.utc) on an existing offset timestamp would instead relabel its clock reading; that would not perform this conversion.

Exit Claude and rerun python3 -m unittest -v test_deadline yourself. Inspect the files as well: a passing run does not help if the agent changed the expected answers. In the local reference check, the original failed seven subtests; this implementation passed all three test methods.

Keep the boundary small

If Python rejects the Z example unexpectedly, check python3 --version against the stated 3.11+ prerequisite. If an import fails, confirm that both files are in the practice folder and the module is named deadline.py. Neither failure demonstrates a timezone defect.

Reject a repair that strips offsets, substitutes the current time, or catches every exception and returns False. Invalid input and a late submission deserve different outcomes.

This helper compares already-specified instants. A recurring “09:00 every Monday in London” task needs a named timezone and daylight-saving rules; it is a different job. Keep that distinction in the next brief you give an agent. The best fix here is small because the contract is precise.

Sources

Checked November 16, 2026:

Put this to work

Separate a timestamp's written clock time from the instant it represents.

Try

Repair a Python deadline helper in a disposable folder using only the standard library.

Prove it worked

Run six fixed cases covering offset changes, the exact cutoff and missing offsets.

Keep in view

  • Expose a deadline check that compares timestamp strings.
  • Give Claude Code explicit rules for offsets and equality.
  • Verify the repair with fixed inputs that never depend on today's date.
Learn the workflow: Set up your first Claude Code project session