staff-engineering-skills-clock-skew
Installation
SKILL.md
Clock Skew Trap
You used timestamps for ordering. Time disagreed. Before using Date.now() for anything other than logging or display, ask: does correctness depend on this timestamp being accurate relative to another machine's clock, or relative to a previous reading on this machine?
Two Kinds of Time
| Wall clock | Monotonic clock | |
|---|---|---|
| What it is | Current time of day (NTP-synchronized) | Counter that only moves forward |
| Can go backward? | Yes (NTP corrections, clock steps) | No, by definition |
| Comparable across machines? | Only within clock skew margin (typically 1-100ms) | No -- only meaningful within one process |
| Use for | Logging, display, human-readable timestamps | Durations, timeouts, elapsed time measurement |
| API | Date.now(), time.time(), System.currentTimeMillis() |
process.hrtime.bigint(), time.monotonic(), time.Since() |
The rule: Use wall clock for humans. Use monotonic clock for measurement. Use logical clocks for distributed ordering.
Detection: When You're Misusing Time
Stop and fix if you see: