# 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?

---

**See also**:

- `.cursor/rules/development/time_implementation.mdc` for

  detailed implementation instructions

- `.cursor/rules/development/time_examples.mdc` for practical examples and patterns

**Status**: Active time handling guidelines
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: None
**Stakeholders**: Development team, Documentation team

**Maintainer**: Matthew Raymer
**Next Review**: 2025-09-17

## Model Implementation Checklist

### Before Time-Related Work

- [ ] **Time Context**: Understand what time information is needed
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601)
- [ ] **Platform Check**: Identify platform-specific time requirements
- [ ] **User Context**: Consider user's timezone and preferences

### During Time Implementation

- [ ] **UTC Usage**: Use UTC for all system and log timestamps
- [ ] **Format Consistency**: Apply consistent time formatting patterns
- [ ] **Timezone Handling**: Properly handle timezone conversions
- [ ] **User Display**: Format times appropriately for user display

### After Time Implementation

- [ ] **Validation**: Verify time formats are correct and consistent
- [ ] **Testing**: Test time handling across different scenarios
- [ ] **Documentation**: Update relevant documentation with time patterns
- [ ] **Review**: Confirm implementation follows time standards