---
alwaysApply: true
---
# Time Handling in Development Workflow

**Author**: Matthew Raymer
**Date**: 2025-08-17
**Status**: 🎯 **ACTIVE** - Production Ready

## Overview

This guide establishes **how time should be referenced and used** across the
development workflow. It is not tied to any one project, but applies to **all
feature development, issue investigations, ADRs, and documentation**.

## General Principles

- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over
  relative references like "last week."
- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in
  docs, issues, ADRs, and commits.
- **Time zones**: Default to **UTC** unless explicitly tied to user-facing
  behavior.
- **Precision**: Only specify as much precision as needed (date vs. datetime vs.
  timestamp).
- **Consistency**: Align time references across ADRs, commits, and investigation
  reports.

## In Documentation & ADRs

- Record decision dates using **absolute ISO dates**.
- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` →
  `2025-08-17`).
- Avoid ambiguous terms like *recently*, *last month*, or *soon*.
- For time-based experiments (e.g., A/B tests), always include:

  - Start date
  - Expected duration
  - Review date checkpoint

## In Code & Commits

- Use **UTC timestamps** in logs, DB migrations, and serialized formats.
- In commits, link changes to **date-bound ADRs or investigation docs**.
- For migrations, include both **applied date** and **intended version window**.
- Use constants for known fixed dates; avoid hardcoding arbitrary strings.

## In Investigations & Research

- Capture **when** an issue occurred (absolute time or version tag).
- When describing failures: note whether they are **time-sensitive** (e.g., after
  migrations, cache expirations).
- Record diagnostic timelines in ISO format (not relative).
- For performance regressions, annotate both **baseline timeframe** and
  **measurement timeframe**.

## Collaboration Hooks

- During reviews, verify **time references are clear, absolute, and
  standardized**.
- In syncs, reframe relative terms ("this week") into shared absolute
  references.
- Tag ADRs with both **date created** and **review by** checkpoints.

## Self-Check Before Submitting

- [ ] Did I check the time using the **developer's actual system time and
      timezone**?
- [ ] Am I using absolute ISO dates?
- [ ] Is UTC assumed unless specified otherwise?
- [ ] Did I avoid ambiguous relative terms?
- [ ] If duration matters, did I specify both start and end?
- [ ] For future work, did I include a review/revisit date?

## Real-Time Context in Developer Interactions

- The model must always resolve **"current time"** using the **developer's
  actual system time and timezone**.
- When generating timestamps (e.g., in investigation logs, ADRs, or examples),
  the model should:

  - Use the **developer's current local time** by default.
  - Indicate the timezone explicitly (e.g., `2025-08-17T10:32-05:00`).
  - Optionally provide UTC alongside if context requires cross-team clarity.

- When interpreting relative terms like *now*, *today*, *last week*:

  - Resolve them against the **developer's current time**.
  - Convert them into **absolute ISO-8601 values** in the output.

## LLM Time Checking Instructions

**CRITICAL**: The LLM must actively query the system for current time rather
than assuming or inventing times.

### How to Check Current Time

#### 1. **Query System Time (Required)**

- **Always start** by querying the current system time using available tools
- **Never assume** what the current time is
- **Never use** placeholder values like "current time" or "now"

#### 2. **Available Time Query Methods**

- **System Clock**: Use `date` command or equivalent system time function
- **Programming Language**: Use language-specific time functions (e.g.,
  `Date.now()`, `datetime.now()`)
- **Environment Variables**: Check for time-related environment variables
- **API Calls**: Use time service APIs if available

#### 3. **Required Time Information**

When querying time, always obtain:

- **Current Date**: YYYY-MM-DD format
- **Current Time**: HH:MM:SS format (24-hour)
- **Timezone**: Current system timezone or UTC offset
- **UTC Equivalent**: Convert local time to UTC for cross-team clarity

#### 4. **Time Query Examples**

```bash
# Example: Query system time
$ date
# Expected output: Mon Aug 17 10:32:45 EDT 2025

# Example: Query UTC time
$ date -u
# Expected output: Mon Aug 17 14:32:45 UTC 2025
```

```python
# Example: Python time query
import datetime
current_time = datetime.datetime.now()
utc_time = datetime.datetime.utcnow()
print(f"Local: {current_time}")
print(f"UTC: {utc_time}")
```

```javascript
// Example: JavaScript time query
const now = new Date();
const utc = new Date().toISOString();
console.log(`Local: ${now}`);
console.log(`UTC: ${utc}`);
```

#### 5. **LLM Time Checking Workflow**

1. **Query**: Actively query system for current time
2. **Validate**: Confirm time data is reasonable and current
3. **Format**: Convert to ISO 8601 format
4. **Context**: Provide both local and UTC times when helpful
5. **Document**: Show the source of time information

#### 6. **Error Handling for Time Queries**

- **If time query fails**: Ask user for current time or use "unknown time"
  with explanation
- **If timezone unclear**: Default to UTC and ask for clarification
- **If time seems wrong**: Verify with user before proceeding
- **Always log**: Record when and how time was obtained

#### 7. **Time Query Verification**

Before using queried time, verify:

- [ ] Time is recent (within last few minutes)
- [ ] Timezone information is available
- [ ] UTC conversion is accurate
- [ ] Format follows ISO 8601 standard

## Model Behavior Rules

- **Never invent a "fake now"**: All "current time" references must come from
  the real system clock available at runtime.
- **Check developer time zone**: If ambiguous, ask for clarification (e.g.,
  "Should I use UTC or your local timezone?").
- **Format for clarity**:

  - Local time: `YYYY-MM-DDTHH:mm±hh:mm`
  - UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ`

## Examples

### Good

- "Feature flag rollout started on `2025-08-01` and will be reviewed on
  `2025-08-21`."
- "Migration applied on `2025-07-15T14:00Z`."
- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` /
  `2025-08-17T14:00Z (UTC)`."

### Bad

- "Feature flag rolled out last week."
- "Migration applied recently."
- "Now is August, so we assume this was last month."

### More Examples

#### Issue Reports

- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue
  persisted until `2025-08-17T15:45:00Z`."
- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a
  while."

#### Release Planning

- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing
  window: `2025-08-20` to `2025-08-24`."
- ❌ **Bad**: "Feature X will be released next week after testing."

#### Performance Monitoring

- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`.
  Regression detected on `2025-08-15T14:00:00Z`."
- ❌ **Bad**: "Performance was good last week but got worse this week."

## Technical Implementation Notes

### UTC Storage Principle

- **Store all timestamps in UTC** in databases, logs, and serialized formats
- **Convert to local time only for user display**
- **Use ISO 8601 format** for all storage: `YYYY-MM-DDTHH:mm:ss.sssZ`

### Common Implementation Patterns

#### Database Storage

```sql
-- ✅ Good: Store in UTC
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

-- ❌ Bad: Store in local time
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
```

#### API Responses

```json
// ✅ Good: Include both UTC and local time
{
  "eventTime": "2025-08-17T14:00:00Z",
  "localTime": "2025-08-17T10:00:00-04:00",
  "timezone": "America/New_York"
}

// ❌ Bad: Only local time
{
  "eventTime": "2025-08-17T10:00:00-04:00"
}
```

#### Logging

```python
# ✅ Good: Log in UTC with timezone info
logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)")

# ❌ Bad: Log in local time
logger.info(f"User action at {datetime.now()}")
```

### Timezone Handling Best Practices

#### 1. Always Store Timezone Information

- Include IANA timezone identifier (e.g., `America/New_York`)
- Store UTC offset at time of creation
- Handle daylight saving time transitions automatically

#### 2. User Display Considerations

- Convert UTC to user's preferred timezone
- Show timezone abbreviation when helpful
- Use relative time for recent events ("2 hours ago")

#### 3. Edge Case Handling

- **Daylight Saving Time**: Use timezone-aware libraries
- **Leap Seconds**: Handle gracefully (rare but important)
- **Invalid Times**: Validate before processing

### Common Mistakes to Avoid

#### 1. Timezone Confusion

- ❌ **Don't**: Assume server timezone is user timezone
- ✅ **Do**: Always convert UTC to user's local time for display

#### 2. Format Inconsistency

- ❌ **Don't**: Mix different time formats in the same system
- ✅ **Do**: Standardize on ISO 8601 for all storage

#### 3. Relative Time References

- ❌ **Don't**: Use relative terms in persistent storage
- ✅ **Do**: Convert relative terms to absolute timestamps immediately

## References

- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601)
- [IANA Timezone Database](https://www.iana.org/time-zones)
- [ADR Template](./adr_template.md)
- [Research & Diagnostic Workflow](./research_diagnostic.mdc)

---

**Rule of Thumb**: Every time reference in development artifacts should be
**clear in 6 months without context**, and aligned to the **developer's actual
current time**.

**Technical Rule of Thumb**: **Store in UTC, display in local time, always
include timezone context.**

---

**Status**: Active
**Version**: 1.0
**Maintainer**: Matthew Raymer
**Next Review**: 2025-09-17