Recurring Tasks

How Recurring Tasks Work

Daylight treats recurring tasks as a single file with multiple tracked instances. You define a recurrence rule (standard RRULE format), and the app expands it into individual occurrences — each with its own date, status, and history. The task file is the source of truth; the instances are derived from the rule and stored in the frontmatter.

Instance Tracking vs Series

The Problem With Series-Based Recurrence

Most task apps treat recurrence as a template: complete today’s instance and the app generates the next one. This creates a chain where each occurrence depends on the previous one being resolved. If you miss an instance — you’re offline, you skip a day, the app misfires — the chain breaks. The missed instance disappears, and you don’t realize the gap until weeks later.

Instance-Based Approach

Daylight tracks each occurrence independently:

• Each occurrence is tracked individually
• Completing one doesn’t affect others
• Skipping preserves the pattern
• Rescheduling is safe

---
title: Weekly Review
recurrence:
  rule: FREQ=WEEKLY;BYDAY=FR
  instances:
    - date: 2026-01-24
      status: completed
    - date: 2026-01-31
      status: active
---

Skip vs Complete

Completing an Instance

Marks the specific occurrence as done. The instance stays in the record with a completed status and timestamp. Future instances are unaffected — they continue to expand from the rule as scheduled.

Skipping an Instance

Marks the occurrence as intentionally skipped without completing it. The instance record is preserved (so you can see what was skipped and when), but it no longer shows as overdue. The recurrence pattern continues normally.

Rescheduling Patterns

Moving a Single Instance

Rescheduling changes the date of one specific instance without touching the recurrence rule or any other instances. The original date stays in the record — only the display and grouping move.

Real example: Your dog’s monthly flea medication is due on the 1st, but the shipment won’t arrive until the 3rd. Reschedule that one instance to the 3rd. The February instance moves; the March 1st instance still generates on schedule. When you complete it on the 3rd, the original February 1st date is marked complete — so your records reflect both when it was supposed to happen and when it actually did.

This works through a rescheduled_instances map in the task’s frontmatter:

---
title: Dog Flea Meds
recurrence:
  rule: FREQ=MONTHLY;BYMONTHDAY=1
active_instances:
  - 2026-02-01
  - 2026-03-01
rescheduled_instances:
  "2026-02-01": "2026-02-03"
---

The rescheduled instance shows on its new date with a hint of where it came from. Completing, skipping, or re-rescheduling all work naturally — the mapping updates in place, and the series continues unaffected.

Modifying the Rule

Changing the recurrence rule (e.g., switching from weekly to biweekly) affects future instance generation. Past instances — completed, skipped, or overdue — are preserved as-is. The new rule applies from the next expansion forward.

Example Rules

Daily Task

recurrence:
  rule: FREQ=DAILY

Creates an instance for every day. Past uncompleted instances surface in the “Past” group so missed days are visible. Useful for habits or daily standups where skipping should be a conscious choice.

Weekly on Specific Days

recurrence:
  rule: FREQ=WEEKLY;BYDAY=MO,WE,FR

Generates instances on Monday, Wednesday, and Friday each week. Each day’s instance is independent — completing Monday doesn’t affect Wednesday’s status.

Monthly on the 15th

recurrence:
  rule: FREQ=MONTHLY;BYMONTHDAY=15

One instance per month on the 15th. Useful for recurring deadlines like expense reports, billing reviews, or monthly check-ins.

Edge Cases

• What if I miss an instance? It appears in the “Past” group as overdue. You can complete it, skip it, or reschedule it to a future date — the record is preserved either way.
• What if I reschedule an instance — does it break the series? No. Rescheduling maps the original date to a new date. The series rule is untouched; other instances generate normally. The original date is preserved for history.
• Can I complete future instances? Yes. Future instances are visible in the “Upcoming” group and can be completed early. This doesn’t affect other instances.
• How far ahead are instances generated? Instances are expanded on demand based on the view window. The recurrence rule is the source of truth; instances are derived, not pre-generated.