# Date Management Guidelines

**Last Updated:** 2026-02-07

## Purpose

This document establishes standards for date management in Ordio documentation to prevent AI agents from assigning inaccurate dates and ensure consistency across all documentation.

## Date Format Standard

### Standard Format
- **Format:** `YYYY-MM-DD` (ISO 8601)
- **Example:** `2026-02-07`
- **Use:** All dates in documentation

### Last Updated Dates
- **Format:** `**Last Updated:** YYYY-MM-DD`
- **Location:** Immediately after the H1 title or at the top of the document
- **Required:** All documentation files (except README files in subdirectories)

### Example
```markdown
# Document Title

**Last Updated:** 2026-02-07

Content here...
```

## Date Assignment Rules

### For New Documentation
1. **Use current date** when creating new documentation
2. **Never use placeholder dates** (e.g., "2026-01-20", "2026-01-20")
3. **Never use future dates** unless documenting scheduled events
4. **Use actual creation date**, not a guessed date

### For Updated Documentation
1. **Update "Last Updated" date** whenever content changes
2. **Keep original creation context** if relevant (can add "Created: YYYY-MM-DD")
3. **Update dates in examples** if they reference specific dates
4. **Don't update historical dates** - preserve them for context

### For AI Agents
**CRITICAL:** When creating or updating documentation:
- ✅ **DO:** Use the actual current date (2026-02-07)
- ✅ **DO:** Check file modification date if unsure
- ✅ **DO:** Use `date +%Y-%m-%d` command to get current date
- ❌ **DON'T:** Guess or use placeholder dates
- ❌ **DON'T:** Use dates from training data (e.g., 2026-01-20, 2026-01-20)
- ❌ **DON'T:** Use dates from other files without verification

## Date Validation

### Automated Checking
Run the date validation script:
```bash
python3 scripts/validate-dates.py
```

### Manual Checklist
When reviewing documentation:
- [ ] All files have "Last Updated" date
- [ ] Dates are in YYYY-MM-DD format
- [ ] No dates before 2023 (unless historical)
- [ ] No placeholder dates (2026-01-20, etc.)
- [ ] Dates match file modification dates (approximately)

## Common Mistakes to Avoid

### ❌ Wrong: Placeholder Dates
```markdown
P26-01-20  # Wrong - placeholder
P26-01-20  # Wrong - placeholder date (example only)
P26-01-20  # Wrong - future date
```

### ✅ Correct: Actual Dates
```markdown
**Last Updated:** 2026-02-07  # Correct - actual date
```

### ❌ Wrong: Inconsistent Formats
```markdown
Last Updated: January 27, 2025  # Wrong - not standardized
Last Updated: 27/01/2025        # Wrong - not ISO format
```

### ✅ Correct: Standardized Format
```markdown
**Last Updated:** 2026-02-07  # Correct - ISO format
```

## Updating Dates

### When to Update
- Content changes (additions, corrections, updates)
- File reorganization
- Reference updates
- Formatting improvements

### When NOT to Update
- Only whitespace changes
- Only link fixes (unless content changed)
- Historical documentation (preserve original dates)

## Date in Code Examples

When documentation includes code examples with dates:

```php
// Good: Use current year or relative dates
$year = date('Y');  // 2026
$date = '2026-02-07';  // Current date

// Avoid: Hardcoded old dates
$date = '2026-01-20';  // Bad - outdated
```

## Historical Dates

For historical context, preserve original dates but add context:

```markdown
**Created:** 2023-06-15  
**Last Updated:** 2026-02-07

This document was originally created in 2023 and has been updated...
```

## Integration with Cursor Rules

Cursor rules should enforce:
1. Always use current date for "Last Updated"
2. Never use placeholder dates
3. Standardize to YYYY-MM-DD format
4. Validate dates before committing

## Tools

### Date Validation Script
```bash
python3 scripts/validate-dates.py
```

### Date Fixing Script
```bash
python3 scripts/fix-dates-in-docs.py
```

## Questions?

- See [CONTRIBUTING.md](CONTRIBUTING.md) for general contribution guidelines
- Check existing documentation for examples
- When in doubt, use current date: `2025-11-20`