gh-cadrianmae-claude-marketplace-plugins-datetime/skills/datetime/references/reference.md

# DateTime Natural - Technical Reference

## For Claude Code

**This reference is for technical details only.** When you need to work with dates/times:

1. **DO NOT** invoke slash commands (`/datetime:parse`, `/datetime:now`, `/datetime:calc`)
2. **DO** use the `date` command directly via Bash tool as shown in examples below

The slash commands are for users only. This reference provides the command patterns you should use directly.

## GNU date Command Reference

The `date` command is a native Linux utility that parses natural language date/time expressions without requiring external dependencies.

### Basic Syntax

```bash
date [OPTION]... [+FORMAT]
date -d STRING [+FORMAT]
```

- `-d STRING`: Display time described by STRING instead of 'now'
- `+FORMAT`: Control the output format

### Recommended Format String

Always use this format for consistency:
```bash
'+%Y-%m-%d %H:%M:%S (%A)'
```

Output: `2025-11-06 14:30:00 (Wednesday)`

## Natural Language Parsing Examples

### Current Time

```bash
date '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-06 14:30:00 (Wednesday)
```

### Relative Dates

```bash
# Tomorrow
date -d "tomorrow" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-07 14:30:00 (Thursday)

# Yesterday
date -d "yesterday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-05 14:30:00 (Tuesday)

# Next week
date -d "next week" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-13 14:30:00 (Wednesday)

# Last week
date -d "last week" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-10-30 14:30:00 (Wednesday)
```

### Offset Expressions

**Important**: Remove "in" prefix - user says "in 3 days" → use `"3 days"`

```bash
# User says "in 3 days" (remove "in")
date -d "3 days" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-09 14:30:00 (Saturday)

# 2 weeks
date -d "2 weeks" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-20 14:30:00 (Wednesday)

# 5 months
date -d "5 months" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-04-06 14:30:00 (Wednesday)

# Past dates
date -d "3 days ago" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-03 14:30:00 (Monday)

date -d "2 weeks ago" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-10-23 14:30:00 (Thursday)
```

### Named Days

```bash
# Next monday
date -d "next monday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-10 14:30:00 (Monday)

# This wednesday
date -d "this wednesday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-12 14:30:00 (Wednesday)

# Last friday
date -d "last friday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-10-31 14:30:00 (Friday)
```

### Complex Expressions with Times

```bash
# Tomorrow at specific time
date -d "tomorrow 3pm" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-07 15:00:00 (Thursday)

# Next monday at 9am
date -d "next monday 9am" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-10 09:00:00 (Monday)

# Tomorrow at 3:30pm
date -d "tomorrow 15:30" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-07 15:30:00 (Thursday)
```

## Relative Calculations

### Date Arithmetic

```bash
# Calculate deadline: 3 days from tomorrow
date -d "tomorrow + 3 days" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-10 14:30:00 (Sunday)

# Calculate 2 weeks before a date
date -d "2025-12-25 - 2 weeks" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-12-11 00:00:00 (Thursday)

# Add/subtract time units
date -d "now + 2 hours" '+%Y-%m-%d %H:%M:%S (%A)'
date -d "tomorrow - 3 hours" '+%Y-%m-%d %H:%M:%S (%A)'
date -d "next monday + 2 days" '+%Y-%m-%d %H:%M:%S (%A)'
```

### Calculate Days Between Dates

```bash
# Calculate days until deadline
DEADLINE=$(date -d "Nov 13" +%s)
NOW=$(date +%s)
DAYS=$(( ($DEADLINE - $NOW) / 86400 ))
echo "$DAYS days remaining"
# → 7 days remaining

# Time between two specific dates (in days)
DATE1=$(date -d "2025-11-06" +%s)
DATE2=$(date -d "2025-11-13" +%s)
DIFF=$(( ($DATE2 - $DATE1) / 86400 ))
echo "$DIFF days between dates"
# → 7 days between dates
```

**Note**: `+%s` format gives Unix timestamp (seconds since epoch), then divide difference by 86400 (seconds in a day).

## Week Number Calculations

### Get Current Week Number

```bash
# ISO week number (1-53)
date +%V
# → 45

# Get week number for a specific date
date -d "2025-12-25" +%V
# → 52
```

### Academic Week Mapping

Use in conjunction with project-specific week mapping scripts to translate calendar weeks to academic weeks:

```bash
# Get calendar week
CALENDAR_WEEK=$(date +%V)

# Map to academic week (example from tu856-4-claude)
ACADEMIC_WEEK=$(~/.claude/skills/week-mapping.sh)
```

## Common Use Cases

### Pattern 1: Verify Current Date Before Responding

```bash
# ALWAYS verify current date before responding with temporal information
date '+%Y-%m-%d %H:%M:%S (%A)'
```

**Why**: The `<env>` context may show incorrect dates, leading to wrong responses.

**Example**:
- User asks: "When is next Friday?"
- Action: Check current date first → Parse "next friday"

### Pattern 2: Parse Deadline Mentions

```bash
# User: "I have a deadline on Tuesday"
date -d "next tuesday" '+%Y-%m-%d %H:%M:%S (%A)'
```

### Pattern 3: Calculate Relative Dates

```bash
# User: "Is tomorrow a weekend?"
date -d "tomorrow" '+%Y-%m-%d %H:%M:%S (%A)'
# Check day name in output
```

### Pattern 4: Calculate Days Until Event

```bash
# User: "How many days until November 13?"
DEADLINE=$(date -d "Nov 13" +%s)
NOW=$(date +%s)
DAYS=$(( ($DEADLINE - $NOW) / 86400 ))
echo "$DAYS days remaining"
```

## Error Handling

### Fallback Pattern

If date parsing fails, fall back to current date/time:

```bash
date -d "invalid expression" '+%Y-%m-%d %H:%M:%S (%A)' 2>/dev/null || date '+%Y-%m-%d %H:%M:%S (%A)'
```

This pattern:
1. Attempts to parse the expression
2. Suppresses error messages with `2>/dev/null`
3. Falls back to current date with `|| date ...`

### Common Parsing Issues

1. **"in X days" doesn't work**: Remove "in" prefix
   - ❌ `date -d "in 3 days"`
   - ✅ `date -d "3 days"`

2. **Always quote expressions**: Prevents shell parsing issues
   - ❌ `date -d next monday`
   - ✅ `date -d "next monday"`

3. **Use consistent format**: Always use the recommended format string
   - ✅ `'+%Y-%m-%d %H:%M:%S (%A)'`

## Format String Reference

The recommended format string components:

- `%Y`: 4-digit year (2025)
- `%m`: 2-digit month (01-12)
- `%d`: 2-digit day (01-31)
- `%H`: 2-digit hour, 24-hour format (00-23)
- `%M`: 2-digit minute (00-59)
- `%S`: 2-digit second (00-59)
- `%A`: Full weekday name (Monday, Tuesday, etc.)

Other useful format codes:

- `%V`: ISO week number (01-53)
- `%s`: Unix timestamp (seconds since 1970-01-01 00:00:00 UTC)
- `%z`: Timezone offset (+0100)
- `%Z`: Timezone name (EST, PST, etc.)

## Configuration

The `date` command uses:
- **Language**: System locale (usually English)
- **Timezone**: System timezone
- **Date handling**: Correctly interprets "next" vs "this" for weekdays

## ADHD/Neurodivergent Support

This skill is particularly useful for:
- Track time meticulously for executive function support
- Parse time mentions in user messages automatically
- Verify temporal context when planning tasks
- Support deadline tracking with natural language
- Calculate available time between events

## Version History

- **v3.0.0** (2025-11-06): Native GNU date command
  - Removed Python dependency entirely
  - Uses native Linux `date` command with `-d` flag
  - Progressive disclosure: moved technical details to reference.md
  - Lean SKILL.md with reference to this file

- **v2.0.0** (2025-10-29): Switched to parsedatetime
  - Replaced dateparser with parsedatetime for better "next/this" handling
  - Added isolated virtual environment for dependency management

- **v1.0.0** (2024-10-29): Initial Python version with dateparser
  - Migrated from Node.js/chrono-node to Python/dateparser