eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
147 lines
4.0 KiB
Plaintext
147 lines
4.0 KiB
Plaintext
# 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
|