Skip to main content

Recurring Tasks

This document explains how recurring tasks work in tududi from a user behavior perspective. For technical implementation details, see the backend code in /backend/modules/tasks/recurringTaskService.js.

Basic Rules​

  1. A recurring task is a single task that automatically resets itself when completed

    • You mark it done, and it immediately reappears with a new due date

  2. The task doesn't create copies - it's the same task reusing itself

    • Same task ID, same title, same details
    • Only the due date changes

  3. Future occurrences are shown in your task list even though they don't exist yet

    • These are "virtual" - they're previews of what's coming
    • They become real when the previous occurrence is completed

Completion Behavior​

  1. When you complete a recurring task:

    • It records that you completed this occurrence
    • It immediately changes to "Not Started" again
    • It gets a new due date based on the pattern

  2. Two ways to calculate the next due date:

    • Due-date based (default): Next occurrence calculated from original due date
      • Example: Task due Monday, you complete it Wednesday → Next is still next Monday
    • Completion-based: Next occurrence calculated from when you actually completed it
      • Example: Task due Monday, you complete it Wednesday → Next is 7 days from Wednesday

Pattern Rules​

  1. Daily recurring:

    • Every N days from the due date (or completion date)

  2. Weekly recurring:

    • Every N weeks on specific day(s)
    • Can repeat on multiple days (e.g., every Mon+Wed+Fri)

  3. Monthly recurring:

    • Fixed day: Every N months on day 15
    • Weekday pattern: Every N months on "2nd Thursday"
    • Last day: Every N months on the last day of the month

  4. Recurring tasks can have an end date:

    • After that date, the task stops recurring
    • Without an end date, they repeat forever

Editing Rules​

  1. If you edit the recurrence pattern of a parent task:

    • Future occurrences update to match the new pattern
    • Past completed occurrences stay in the history unchanged

  2. You can edit individual details (title, priority, notes) on the parent:

    • Changes apply to future occurrences
    • Past completions keep their original details

  3. If you edit a future occurrence (a virtual instance):

    • You're actually editing the parent template
    • The change affects all future occurrences

Display Rules​

  1. Recurring tasks show up multiple times in your lists:

    • Today's occurrence (if due today)
    • Future occurrences (as previews)
    • Typically shows next 6-7 occurrences

  2. Each occurrence looks like a separate task in the UI:

    • But it's really the same task showing at different dates

  3. You can see completion history:

    • Records of when you completed past occurrences
    • Shows your pattern of completing the task

Special Cases​

  1. If a recurring task is overdue:

    • It doesn't pile up multiple occurrences
    • Shows the current/next occurrence only
    • Past-due occurrences are skipped automatically

  2. If you delete a recurring task:

    • The parent template is deleted
    • All future occurrences disappear
    • Past completion history is preserved

  3. Recurring tasks can belong to projects:

    • Every occurrence inherits the project
    • Changing the project changes it for all future occurrences

Key Concepts​

Virtual Instances​

Future occurrences that are generated on-the-fly for display purposes. They don't exist in the database as separate tasks - they're computed from the parent task's recurrence pattern.

Parent Task​

The original recurring task that acts as a template. It has recurring_parent_id = null and stores the recurrence pattern configuration.

In-Place Advancement​

When you complete a recurring task, the same task record is reused with an updated due date, rather than creating a new task instance.

Completion History​

All past completions are tracked in a separate table (recurring_completions) to preserve your completion record even though the task itself advances.

Analogy​

Think of it like a gym membership that auto-renews - it's one subscription that keeps coming back on a schedule, not multiple separate subscriptions.

Technical Implementation Files:

  • Recurrence calculation: /backend/modules/tasks/recurringTaskService.js
  • Completion handling: /backend/modules/tasks/routes.js
  • Task model: /backend/models/task.js
  • Completion tracking: /backend/models/recurringCompletion.js

Document Version: 1.0.0 Last Updated: 2026-03-14 Audience: Developers, AI assistants, and end users