temporal-awareness

temporal-awareness

Use a reliable time anchor and the user's timezone for time-sensitive answers; verify changing external facts separately.

Decision Tree

What is the time-sensitive failure mode?

• Need a clean session anchor before answering

  • Reuse a fresh, reliable session clock and known user timezone when sufficient.
  • If missing, stale, or boundary math matters, run python3 scripts/capture_temporal_context.py --format markdown (add --extra-zone <user-zone> when needed). Read references/bootstrap.md for details.

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

  • Reason from the claim's volatility and available evidence. scripts/recency_guard.py is an optional advisory heuristic, not a required command or a substitute for judgment.
  • Read references/recency-triage.md when the distinction is unclear.

• 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 missing or stale local and UTC time context	python3 scripts/capture_temporal_context.py --format markdown	Establish a reliable anchor when existing context is insufficient
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
Get an advisory recency classification	python3 scripts/recency_guard.py --prompt "What is the latest release?" --format markdown	Flag risks to assess, not a mandatory decision gate
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 outdated products, roles, or prices?"	references/gotchas.md

Operational Rules

1. Check whether the session already has a reliable clock fresh enough for the requested precision. Reuse it when sufficient; capture when missing or stale, or when midnight, DST, or cross-zone boundary calculations matter.
2. The user's known timezone governs user-relative dates, not the orb/server's local timezone. Use IANA zones for conversions. If a consequential timezone is unknown, ask or state the assumption instead of inferring it from the host.
3. Use live authoritative sources for truly volatile external claims: current models, versions, prices, laws, schedules, weather, executives, and live events. A clock does not verify these facts. If live verification is unavailable, state that limitation rather than asserting currentness.
4. Convert relative dates into explicit dates when ambiguity or a boundary matters. Do not add clock dumps, tool runs, or browsing solely because a prompt contains a time word.
5. Reassess freshness after long pauses, user-zone midnight, DST changes, or a timezone-context change. Refresh only what the answer needs; rolling external data may need a new source check even while the clock anchor remains sufficient.

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 treats model families and product versions as volatile rather than assuming remembered defaults remain current.
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 relevant day boundary or DST change, refresh the anchor and restate the date when needed.

Keeping Guidance Current

When a gap or suspected staleness affects the task, consult current official clock/timezone/tool documentation or trusted sources appropriate to the claim. Skip routine browsing when the evidence is sufficient. If sources are unavailable, state the gap; propose a sourced correction with an example or check in the canonical package, never an automatic edit to installed copies.

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.