crowd-funder-for-time-pwa/.cursor/rules/development/time_implementation.mdc

# Time Implementation — Technical Instructions

> **Agent role**: Reference this file for detailed implementation instructions
  when working with time handling in development.

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

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

```

#### 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"
}

```

#### Logging

```python

# ✅ Good: Log in UTC with timezone info

logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)")

```

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

---

**See also**:

- `.cursor/rules/development/time.mdc` for core principles

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

**Status**: Active implementation guidelines
**Priority**: Medium
**Estimated Effort**: Ongoing reference
**Dependencies**: time.mdc
**Stakeholders**: Development team, DevOps team

## Model Implementation Checklist

### Before Time Implementation

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

### During Time Implementation

- [ ] **UTC Storage**: 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

- [ ] **Format Validation**: Verify time formats are correct and consistent
- [ ] **Cross-Platform Testing**: Test time handling across different platforms
- [ ] **Documentation**: Update relevant documentation with time patterns
- [ ] **User Experience**: Confirm time display is clear and user-friendly