marketing-shibata50/tududi
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tududi/docs/00-tasks-behavior.md
Chris Veleris a0b769164c Add LLM docs
2026-03-15 09:01:38 +02:00

514 lines
No EOL
17 KiB
Markdown
Raw Blame History

# Tasks - Behavior Rules
This document explains how tasks work in tududi from a user behavior perspective (excluding recurring tasks, which are covered in [01-recurring-tasks-behavior.md](01-recurring-tasks-behavior.md)). For technical implementation details, see the backend code in `/backend/modules/tasks/` and `/backend/models/task.js`.
---
## **Task Creation**
### Basic Task Creation
1. **A task requires only a name to be created**
- All other fields (due date, priority, project, etc.) are optional
- Task name cannot be empty or just whitespace
- Tasks are created with "Not Started" status by default
2. **Every task gets a unique identifier (UID)**
- Used in URLs and API calls
- Never changes during the task's lifetime
- Example: `tsk_abc123def456`
3. **Tasks belong to a user**
- The creator becomes the owner
- Only the owner (or those with shared access) can view/modify the task
- Admins can access all tasks
### Quick Capture
4. **Tasks can be created from multiple places:**
- Main task list (+ button)
- Today page quick add
- Inbox (converted from inbox items)
- Quick capture modal (keyboard shortcut)
- Telegram bot
- API
---
## **Task Fields & Properties**
### Name & Description
5. **Task name is the primary identifier**
- Required field, maximum length varies by database
- Displayed in lists, calendars, and notifications
- Can be edited at any time
6. **Task note is for detailed information**
- Optional text field for longer descriptions
- Supports plain text (no markdown formatting)
- Useful for context, instructions, or reference materials
### Status Lifecycle
7. **Seven status states exist:**
- **Not Started (0):** Default state, task hasn't been worked on yet
- **In Progress (1):** Task is actively being worked on
- **Done (2):** Task is completed
- **Archived (3):** Task is finished and archived for historical record
- **Waiting (4):** Task is blocked or waiting on something/someone
- **Cancelled (5):** Task was abandoned or is no longer needed
- **Planned (6):** Task is scheduled to be worked on
8. **Status changes affect visibility:**
- "Done", "Archived", and "Cancelled" remove tasks from active views
- "In Progress", "Planned", and "Waiting" appear in Today page Planned section
- Status determines which section of the Today page shows the task
9. **Completion tracking is automatic:**
- Changing status to "Done" sets `completed_at` timestamp to current time
- Changing status from "Done" to anything else clears `completed_at`
- Completed tasks show in "Completed" section of Today page
### Priority Levels
10. **Three priority levels:**
- **Low (0):** Default priority, no special urgency
- **Medium (1):** Moderate importance
- **High (2):** Urgent or critical task
11. **Priority affects sorting:**
- In most views, tasks are sorted High → Medium → Low
- Priority is a visual indicator (colored flag icons)
- Does not affect task behavior, only display order
### Due Dates
12. **Due dates are optional:**
- Tasks without due dates are considered "someday/maybe"
- Due dates are stored with date and time
- Displayed in user's timezone
13. **Due date behavior:**
- Tasks become "overdue" if due date passes and status is not "Done"
- Overdue tasks appear in "Overdue" section on Today page
- Due today tasks appear in "Suggested" section (if not in Planned status)
- No automatic status changes when due date passes
### Defer Until
14. **Defer Until hides tasks until a specific time:**
- Set a date/time when you want the task to become visible
- Task is completely hidden from all views until defer time passes
- Useful for "start this task on Monday" or "remind me in 2 hours"
15. **Defer Until behavior:**
- System checks every 5 minutes for tasks whose defer time has passed
- When defer time is reached, task becomes visible in appropriate sections
- Optional notification sent when task becomes active (configurable)
- Defer time can be edited or cleared at any time
16. **Defer Until is different from due date:**
- Defer = "don't show me this until..."
- Due date = "this needs to be finished by..."
- A task can have both defer and due date
- If both exist: task hidden until defer time, then due date determines urgency
---
## **Subtasks**
### Subtask Hierarchy
17. **Tasks can have subtasks (one level deep)**
- Subtasks are full tasks with all properties (status, priority, due date, etc.)
- Maximum one level: tasks can have subtasks, but subtasks cannot have their own subtasks
- Parent-child relationship is tracked via `parent_task_id`
18. **Subtasks are displayed under their parent:**
- Parent task shows a summary (e.g., "2 of 5 completed")
- Subtasks can be collapsed/expanded in the UI
- Subtasks are ordered by `order` field, then creation date
19. **Subtasks have their own lifecycle:**
- Each subtask has independent status, priority, due date
- Completing all subtasks doesn't auto-complete the parent
- Completing the parent doesn't auto-complete subtasks
- Deleting the parent deletes all subtasks (cascade)
20. **Subtask visibility rules:**
- Subtasks don't appear in main task lists (only under parent)
- Subtasks don't show in Today page sections independently
- Searching for subtasks shows them with parent context
- Filtering applies to parent tasks, not individual subtasks
### Subtask Ordering
21. **Subtasks can be manually reordered:**
- Drag-and-drop in the UI updates the `order` field
- Order is sequential integers (1, 2, 3, etc.)
- New subtasks are added at the end (highest order + 1)
---
## **Attachments**
### File Uploads
22. **Tasks can have file attachments:**
- Multiple files can be attached to a single task
- File size limit: 10MB per file
- Stored in `/uploads/tasks/` directory
23. **Allowed file types:**
- Images: jpg, jpeg, png, gif, webp, svg
- Documents: pdf, doc, docx, xls, xlsx, ppt, pptx
- Text: txt, md, csv
- Archives: zip, tar, gz
- Other common formats
24. **Attachment metadata:**
- Original filename is preserved in database
- File is renamed on disk for uniqueness (task-[timestamp]-[random].[ext])
- Each attachment gets a unique UID
- Attachments track: filename, file size, MIME type, upload date
25. **Attachment management:**
- Uploaded by task owner or users with write access
- Can be downloaded by anyone with read access to the task
- Deleting attachment removes file from disk
- Deleting task removes all attachments and their files
---
## **Project Assignment**
### Linking to Projects
26. **Tasks can belong to a project:**
- Optional `project_id` field links task to project
- Tasks without a project are "standalone"
- Project assignment determines which project view shows the task
27. **Project assignment effects:**
- Task inherits project's sharing permissions
- If user has access to project, they have same access to project's tasks
- Deleting a project can orphan or delete tasks (depends on user choice)
- Task completion contributes to project's progress metrics
28. **Changing project assignment:**
- Can move task from one project to another
- Can remove task from project (makes it standalone)
- Subtasks inherit parent task's project
- Changing parent's project doesn't automatically update subtasks
---
## **Tags**
### Tagging System
29. **Tasks can have multiple tags:**
- Tags are flexible labels for categorization
- Same tag can be used across tasks, notes, and projects
- Tags are created automatically when first used
- Tags are case-insensitive and normalized
30. **Tag behavior:**
- Adding/removing tags doesn't affect task status or visibility
- Tags enable filtering: "show all tasks with #urgent"
- Tags appear as clickable chips in the UI
- Tag autocomplete suggests existing tags while typing
31. **Tag inheritance:**
- Subtasks have their own independent tags
- Tags are not inherited from parent task or project
- Deleting a tag removes it from all tasks (but doesn't delete tasks)
---
## **Task Completion**
### Marking Tasks as Done
32. **Completing a task:**
- Change status to "Done" (manually or via checkbox)
- `completed_at` timestamp is set to current time
- Task moves to "Completed" section on Today page
- Task disappears from active task lists
33. **Completion behavior for subtasks:**
- Parent can be completed even if subtasks are not done
- Subtasks can be completed independently
- Completing the parent doesn't complete subtasks
- Progress indicator shows "X of Y completed" for subtasks
34. **Un-completing a task:**
- Changing status from "Done" to any other status
- Clears the `completed_at` timestamp
- Task reappears in active views
- Task history preserves the completion event
### Completed Task Visibility
35. **Where completed tasks appear:**
- "Completed" section on Today page (if completed today)
- Project details page with "Show completed" filter
- Search results (if specifically queried)
- Task history and timeline views
36. **Completed tasks are excluded from:**
- Main task lists by default
- Today page "Planned" and "Suggested" sections
- Overdue calculations
- Upcoming view (future due dates)
---
## **Task Events & History**
### Activity Tracking
37. **Every task change is logged:**
- Task creation event
- Status changes
- Field updates (name, due date, priority, etc.)
- Assignment to project
- Tag additions/removals
- Attachment uploads/deletions
38. **Event data includes:**
- Event type (created, status_changed, field_updated, etc.)
- User who made the change
- Timestamp of the change
- Old value and new value (for field changes)
- Additional metadata (source: web, API, Telegram, etc.)
39. **Task timeline:**
- Events are displayed in chronological order
- Shows full audit trail of task's lifecycle
- Useful for understanding when and why changes occurred
- Cannot be edited or deleted (immutable history)
---
## **Habit Mode**
### Habit Tracking
40. **Tasks can be habit trackers:**
- `habit_mode` flag enables habit-specific features
- Different from recurring tasks (habits focus on streak tracking)
- Example: "Exercise 3 times per week"
41. **Habit properties:**
- **Target count:** How many times per period (e.g., 3 times)
- **Frequency period:** daily, weekly, or monthly
- **Streak mode:**
- Calendar: Count consecutive days
- Scheduled: Count consecutive completions on scheduled days
- **Flexibility mode:**
- Strict: Must complete on exact schedule
- Flexible: Can complete within the period
42. **Habit tracking:**
- `habit_current_streak`: Current consecutive completions
- `habit_best_streak`: Longest streak ever achieved
- `habit_total_completions`: Total times completed
- `habit_last_completion_at`: When last completed
43. **Habit completion:**
- Completing a habit increments counters
- Streak breaks if missed according to mode rules
- Habit widgets show progress toward target count
- Visual indicators for streak status (on track, at risk, broken)
---
## **Task Deletion**
### Deleting Tasks
44. **Deleting a task:**
- Removes the task from the database
- Cascade deletes all subtasks
- Removes all attachments (files deleted from disk)
- Removes task events/history
- Removes tag associations (tags themselves remain)
45. **Soft delete is not implemented:**
- Deletion is permanent (no trash/recycle bin)
- No undo operation
- Completed tasks can be archived instead of deleted
46. **Deleting a parent task:**
- All subtasks are deleted (cannot be orphaned)
- Warning shown if parent has subtasks
- User must confirm deletion
47. **Permission to delete:**
- Only task owner can delete their tasks
- Users with write access via project sharing can delete
- Admins can delete any task
---
## **Task Sharing & Permissions**
### Access Control
48. **Tasks inherit permissions from projects:**
- If a task belongs to a project, anyone with project access has same access to task
- Access levels: none, read-only (ro), read-write (rw), admin
- Owner always has full access
49. **Standalone tasks:**
- Tasks without a project are only visible to owner
- Cannot be shared directly (must assign to a project to share)
- Admins can view all tasks regardless of ownership
50. **Permission effects:**
- **Read-only:** Can view task, cannot edit or delete
- **Read-write:** Can edit task fields, add subtasks, upload attachments
- **Admin/Owner:** Can delete task, change project assignment, share
---
## **Task Ordering & Sorting**
### Default Sort Order
51. **Tasks are typically sorted by:**
1. Priority (High → Medium → Low)
2. Due date (earliest first, nulls last)
3. Created date (newest first for same priority/due date)
52. **Custom sorting options:**
- Name (alphabetical)
- Status
- Created date
- Updated date
- Manual order (drag-and-drop, for subtasks)
53. **Grouping options:**
- By project
- By status
- By priority
- By due date (today, tomorrow, this week, later)
- By tags
---
## **Task Notifications**
### Notification Types
54. **Tasks trigger notifications for:**
- Task due soon (based on due date)
- Task overdue
- Defer Until time reached
- Task assigned to you (shared via project)
55. **Notification channels:**
- In-app notifications (navbar indicator)
- Email (configurable per notification type)
- Telegram (configurable per notification type)
- Push notifications (configurable per notification type)
56. **Notification preferences:**
- User can enable/disable per notification type
- User can choose which channels for each type
- Notifications can be dismissed or marked as read
- Duplicate notifications are prevented (deduplication logic)
---
## **Special Behaviors**
### Task Visibility Rules
57. **A task is hidden from views if:**
- Defer Until time has not yet passed
- Status is "Done", "Archived", or "Cancelled" (unless showing completed)
- User doesn't have permission to view it
- It's a subtask (only shown under parent)
- It's a recurring parent template (only instances shown)
58. **Overdue detection:**
- Task is overdue if: `due_date < now` AND `status != Done/Archived/Cancelled`
- Overdue tasks appear in "Overdue" section on Today page
- Overdue count shows in navbar and project metrics
- No automatic status change occurs
### Task Intelligence
59. **Task intelligence features (optional, can be disabled):**
- Auto-suggest next actions based on task context
- Smart suggestions for tasks to work on (Today page "Suggested" section)
- Productivity insights and patterns
- Next task recommendation based on priority, due date, and context
60. **Suggestion algorithm considers:**
- Due dates (tasks due soon ranked higher)
- Priority level
- Project deadlines
- Task age (older tasks surfaced)
- Completion patterns (time of day you usually work on similar tasks)
---
## **Key Concepts**
### Task Instance
A single task record in the database with a unique ID and UID. Contains all task properties (name, status, priority, dates, etc.).
### Parent-Child Relationship
Hierarchical link between a parent task and its subtasks. One level deep only. Tracked via `parent_task_id` field.
### Completion Timestamp
The exact date and time when a task's status changed to "Done". Stored in `completed_at` field. Used for filtering "completed today" tasks.
### Task Events
Immutable audit log of all changes to a task. Each event records who changed what, when, and the before/after values.
### Defer Until
A feature that hides a task from all views until a specified date/time. Different from due dates - it's about when to START thinking about the task, not when to FINISH it.
### Task Ownership
The user who created the task owns it by default. Ownership can be transferred via project sharing, but the original `user_id` doesn't change.
### Habit Tracking
A mode that transforms a task into a habit tracker with streak counting, target counts, and flexible scheduling. Useful for building consistent behaviors.
---
## **Related Documentation**
- [Recurring Tasks Behavior](01-recurring-tasks-behavior.md) - How recurring tasks work
- [Today Page Sections](02-today-page-sections.md) - Task filtering and display on Today page
- [Upcoming View](03-upcoming-view.md) - 7-day task preview
- [Projects](06-projects.md) - Project assignment and task organization
- [Tags System](09-tags-system.md) - Tagging and categorization
- [User Management](08-user-management.md) - Permissions and sharing
**Technical Implementation Files:**
- Task model: `/backend/models/task.js`
- Task service: `/backend/modules/tasks/`
- Task completion: `/backend/modules/tasks/operations/completion.js`
- Subtasks: `/backend/modules/tasks/operations/subtasks.js`
- Attachments: `/backend/modules/tasks/attachments.js`
- Task events: `/backend/modules/tasks/taskEventService.js`
- Deferred tasks: `/backend/modules/tasks/deferredTaskService.js`
---
**Document Version:** 1.0.0
**Last Updated:** 2026-03-15
**Audience:** Developers, AI assistants, and end users
Reference in a new issue View git blame Copy permalink