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
| Task | Command or file | Why |
|---|---|---|
| Capture local and UTC time context | python3 scripts/capture_temporal_context.py --format markdown | Load the real clock into the session before answering |
| Compare the current moment across zones | python3 scripts/capture_temporal_context.py --format markdown --extra-zone America/New_York --extra-zone Europe/London | Avoid silent timezone drift |
| Classify whether a prompt needs live verification | python3 scripts/recency_guard.py --prompt "What is the latest OpenAI model for coding?" --format markdown | Separate stable questions from volatile ones |
| Run the deterministic probe suite | python3 scripts/probe_temporal_awareness.py --format pretty | Verify the skill still behaves as designed |
| Learn the startup workflow | references/bootstrap.md | Session-load order and exact commands |
| Handle relative dates and volatile facts | references/verification-patterns.md | Absolute-date conversion and source selection |
Reading Guide
| If the user says... | Read |
|---|---|
| "Before you answer, what date is it here and what timezone are we using?" | references/bootstrap.md |
| "Do I need to browse for this or is it stable?" | references/recency-triage.md |
| "What does latest mean here?" | references/verification-patterns.md |
| "This session has been running for hours, should we refresh the date context?" | references/long-horizon.md |
| "Why are agents still mentioning GPT-4o / old CEOs / stale prices?" | references/gotchas.md |
Operational Rules
- Run
scripts/capture_temporal_context.pybefore answering any prompt that uses relative time language or depends on the current date, time, or timezone. - Run
scripts/recency_guard.pyon prompts containinglatest,current,today,yesterday,tomorrow,recent,as of, or volatile domains such as models, prices, laws, schedules, weather, executives, or live events. - Treat the system clock as authoritative for local date and time, but treat external current facts as untrusted until verified against live sources.
- Convert relative dates into absolute dates before answering whenever there is even a small chance the user is thinking in a different timezone.
- Refresh the temporal anchor when the session crosses midnight, spans multiple hours, changes timezone context, or revisits rolling external data.
Verified Behaviors
scripts/capture_temporal_context.pyemits local and UTC timestamps, timezone name candidates, UTC offset, locale, platform, and optional extra-zone snapshots.scripts/recency_guard.pydetects relative-date language and volatile domains, and distinguishes stable historical prompts from current-state prompts.scripts/probe_temporal_awareness.pyruns deterministic checks across smoke, edge, negative, and disclosure-style scenarios.- 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.
- Long-running sessions get explicit refresh rules instead of assuming the first temporal anchor stays valid forever.
Gotchas
- 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.
- Relative dates are timezone-dependent:
today,yesterday, andtomorroware wrong if you silently assume UTC while the user is thinking locally. - Historical facts are not the same as current-state facts:
Who won the 2024 election?is usually stable;Who is president now?is not. - Model names drift faster than agents admit: treat model families, versions, limits, and availability as volatile unless you just verified them.
- 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.pyprints a session-ready time anchor in JSON, text, or Markdown.scripts/recency_guard.pyclassifies a prompt as stable, system-clock-sensitive, or live-verification-required.scripts/probe_temporal_awareness.pyruns deterministic regression checks across the core heuristics.scripts/validate.pyvalidates structure, references, eval coverage, and Python syntax.scripts/test_skill.pyvalidates the packaging and runs the temporal probe suite.