Temporal Awareness

temporal-awareness

Ground the session in the real clock before answering anything that could have changed.

Verified locally on April 9, 2026 in Pacific/Auckland (NZST, UTC+12). The motivating failure mode is real: OpenAI's official Help Center now documents GPT-5.3 and GPT-5.4 in ChatGPT, while stale assistants still default to GPT-4o-era wording from older memory.

Decision Tree

What is the time-sensitive failure mode?

• Need a clean session anchor before answering

  • Run python3 scripts/capture_temporal_context.py --format markdown
  • Read references/bootstrap.md

• Need to decide whether a prompt can be answered from stable knowledge or needs live verification

  • Run python3 scripts/recency_guard.py --prompt "..." --format markdown
  • Read references/recency-triage.md

• Need patterns for latest, today, yesterday, tomorrow, timezone math, or source selection

  • Read references/verification-patterns.md

• Need refresh rules for long-running sessions, day rollovers, or recurring work

  • Read references/long-horizon.md

• Need to debug stale assumptions, outdated model names, or relative-date mistakes

  • Read references/gotchas.md

Quick Reference

Reading Guide

Operational Rules

1. Run scripts/capture_temporal_context.py before answering any prompt that uses relative time language or depends on the current date, time, or timezone.
2. Run scripts/recency_guard.py on prompts containing latest, current, today, yesterday, tomorrow, recent, as of, or volatile domains such as models, prices, laws, schedules, weather, executives, or live events.
3. Treat the system clock as authoritative for local date and time, but treat external current facts as untrusted until verified against live sources.
4. Convert relative dates into absolute dates before answering whenever there is even a small chance the user is thinking in a different timezone.
5. Refresh the temporal anchor when the session crosses midnight, spans multiple hours, changes timezone context, or revisits rolling external data.

Verified Behaviors

1. scripts/capture_temporal_context.py emits local and UTC timestamps, timezone name candidates, UTC offset, locale, platform, and optional extra-zone snapshots.
2. scripts/recency_guard.py detects relative-date language and volatile domains, and distinguishes stable historical prompts from current-state prompts.
3. scripts/probe_temporal_awareness.py runs deterministic checks across smoke, edge, negative, and disclosure-style scenarios.
4. The skill explicitly treats model families and product versions as volatile; this prevents stale answers like defaulting to GPT-4o when the official docs have moved on.
5. Long-running sessions get explicit refresh rules instead of assuming the first temporal anchor stays valid forever.

Gotchas

1. Do not confuse clock grounding with live verification: the system clock can tell you what day it is locally, but it cannot tell you today's stock price or the current CEO.
2. Relative dates are timezone-dependent: today, yesterday, and tomorrow are wrong if you silently assume UTC while the user is thinking locally.
3. Historical facts are not the same as current-state facts: Who won the 2024 election? is usually stable; Who is president now? is not.
4. Model names drift faster than agents admit: treat model families, versions, limits, and availability as volatile unless you just verified them.
5. Long sessions go stale: if work spans a day boundary or a DST change, rerun the capture step and restate the new absolute date.

Helper Scripts

• scripts/capture_temporal_context.py prints a session-ready time anchor in JSON, text, or Markdown.
• scripts/recency_guard.py classifies a prompt as stable, system-clock-sensitive, or live-verification-required.
• scripts/probe_temporal_awareness.py runs deterministic regression checks across the core heuristics.
• scripts/validate.py validates structure, references, eval coverage, and Python syntax.
• scripts/test_skill.py validates the packaging and runs the temporal probe suite.