docs(rules): apply markdown standards and streamline rulesets

- Apply markdown.mdc formatting to all ruleset files (80-char line length, proper spacing) - Update timesafari.mdc to reflect completed migration (remove triple migration pattern references) - Clean up corrupted logging_standards.mdc and restore proper content - Streamline architectural_decision_record.mdc for better readability - Update all file dates to 2025-08-19 for consistency - Add proper document headers and metadata to all ruleset files - Remove duplicate content and improve file organization - Maintain alwaysApply settings and glob patterns appropriately Files affected: 15 ruleset files across app/, database/, development/, features/, workflow/ directories
2025-08-19 13:14:25 +00:00
parent e733089bad
commit 1666e77aa5
15 changed files with 1328 additions and 666 deletions
--- a/.cursor/rules/time.mdc
+++ b/.cursor/rules/time.mdc
@@ -0,0 +1,329 @@
+---
+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