Chore Status and Recurrence Handling - ad-ha/kidschores-ha GitHub Wiki
π Chore Status and Recurrence Handling
π Overview
Managing household chores effectively requires a clear system for tracking status, due dates, and recurrence. This guide outlines how chores progress through different states, how they reset, and how recurrence impacts chore availability.
β¨ Key Concepts:
β Chore Status Tracking β Ensuring tasks move from pending to completion and approval. π Due Date Handling β Understanding how chores become overdue and reset. π Recurrence Rules β How daily, weekly, bi-weekly, monthly and custom schedule chores reset and maintain their schedules. π Applicable Days β Restricting chores to specific days of the week and ensuring they are only scheduled on valid days. π Multiple Claims β Managing chores that can be completed multiple times per day.
This guide covers three main use cases: 1οΈβ£ Chores without due dates or recurrence β Simple ad-hoc tasks. 2οΈβ£ Chores with due dates but no recurrence β Single tasks that can become overdue. 3οΈβ£ Chores with both due dates and recurrence β Scheduled chores that can become overdue and reset at specific intervals.
π Use Case 1: Chore with No Due Date and No Recurrence
A non-recurring chore with no due date remains in a pending state until completed and approved. It will not become overdue. After approval, it resets to pending at midnight.
π Scenarios and Status Transitions
| πΉ Scenario | π Status Before | π Who Performs Action | β Action Taken | π Status After | π― Next Steps |
|---|---|---|---|---|---|
| β Chore completed | pending | User | Marks chore as completed | claimed | Approval needed |
| π Chore approved | claimed | User | Approval is given | approved | Remains approved until midnight |
| π Midnight passes | approved | System | Resets status | pending | Chore remains available for future assignment |
| β³ Chore not completed | pending | User/System | No action taken | Stays pending | Stays in list until completed |
π Key Points
β No due date, so it never becomes overdue. β Once approved, it remains approved until midnight. β At midnight, the system resets it to pending, making it available for the next cycle.
π Use Case 2: Chore with No Due Date and Recurrence (Only supports daily and weekly recurrence at this time.)
[!NOTE] > Context: With the introduction of Overdue Handling options (v0.5.0+), this use case is largely unnecessary now. You can achieve the same "never overdue" behavior by setting a due date with "Never Overdue" handling. However, this pattern still works if you prefer not to set any due date.
A recurring chore with no due date remains in a pending state until completed and approved. It will not become overdue. After approval, it will remain in the approved stated until it resets to pending at midnight of the recurrence period. For weekly, that is forced to Monday 00:00AM
π Scenarios and Status Transitions
| πΉ Scenario | π Status Before | π Who Performs Action | β Action Taken | π Status After | π― Next Steps |
|---|---|---|---|---|---|
| β Chore completed | pending | User | Marks chore as completed | claimed | Approval needed |
| π Chore approved | claimed | User | Approval is given | approved | Remains approved until midnight of recurrence period |
| π Midnight of recurrence period passes | approved | System | Resets status | pending | Chore remains available for future assignment |
| β³ Chore not completed | pending | User/System | No action taken | Stays pending | Stays in list until completed |
π Key Points
β This is ideal for chores you'd like the kids to be doing daily or weekly, but also don't want to ever show as overdue β No due date, so it never becomes overdue. β Once approved, it remains approved until midnight of the recurrence period β At midnight of the recurrence period, the system resets it to pending, making it available for the next cycle.
π Use Case 3: Chore with a Due Date and No Recurrence
A non-recurring chore with a due date can become overdue if not completed on time. Once approved, it resets to pending at midnight, with the due date cleared.
π Scenarios and Status Transitions
| πΉ Scenario | π Status Before | π Who Performs Action | β Action Taken | π Status After | π― Next Steps |
|---|---|---|---|---|---|
| β Chore completed before due date | pending | User | Marks chore as completed | claimed | Approval needed |
| β³ Due date missed | pending | System | Due date passes | overdue | Needs completion |
| β Completed after due date | overdue | User | Marks chore as completed | claimed | Approval needed |
| π Approved on/before due date | claimed | User | Approval is given | approved | Remains approved until midnight |
| π Approved after due date | claimed | User | Approval is given | pending, due_date = null | Due date is cleared immediately |
| π Midnight passes | approved | System | Resets status & clears due date | pending, due_date = null | Chore remains available for future assignment |
π Key Points
β A due date means the chore can become overdue. β Overdue chores must be completed and approved to reset. β At midnight, claimed or approved chores reset to pending, clearing the due date. β Approvals after the due date immediately reset the due date to null.
π Use Case 4: Chore with a Due Date and Recurrence (Biweekly, Monthly, Custom)
This use case applies to biweekly, monthly, and custom recurring chores - all of which require a due date. The system follows the same behavior across these frequencies, with the due date advancing at midnight based on the recurrence schedule.
[!IMPORTANT] > Due Date Required: Biweekly, Monthly, and Custom recurrence patterns require a due date to be set. The integration will enforce this during configuration.
Note: Daily and Weekly frequencies can optionally use a due date (see Use Case 2 for no-due-date behavior).
π Scenarios and Status Transitions
| πΉ Scenario | π Status Before | π Who Performs Action | β Action Taken | π Status After | π― Next Steps |
|---|---|---|---|---|---|
| β Completed before due date | pending | User | Marks chore as completed | claimed | Approval needed |
| β³ Due date missed | pending | System | Due date passes | overdue | Needs completion |
| β Completed after due date | overdue | User | Marks chore as completed | claimed | Approval needed |
| π Approved on/before due date | claimed | User | Approval is given | approved | Remains approved until midnight |
| π Approved after due date | overdue | User | Approval is given | approved | Remains approved until midnight |
| π Midnight passes | approved/claimed | System | Resets status, sets new due date for next recurrence | pending, due_date = next recurrence | Chore is ready for the next scheduled recurrence |
π Key Points
β All Recurring Chores in Approved or Claimed Status Reset at Midnight of Their Due Date πΉ Whether daily, weekly, or monthly, the system advances the due date at midnight to the next scheduled recurrence. πΉ If a kid claims a chore but doesnβt get approved before midnight, the chore resets to the next recurrence date. πΉ Workaround: Parents can manually grant points if they missed an approval before midnight.
β Late Approvals Do Not Immediately Reset the Chore
- If a chore is approved after its due date, it remains in the approved state until midnight, instead of resetting immediately.
- πΉ Daily recurring chores must be completed before midnight, or they cannot be claimed again the next day.
- πΉ Options: Parents can either manually grant points or use the Overdue Chore Reset Service to reset the chore manually.
π How Applicable Days Affect Scheduling
Applicable days ensure that chores only appear on designated days. If no applicable days are selected, the chore can be scheduled on any day. If a scheduled due date falls on an invalid day, the system automatically moves it forward to the next allowed day.
How It Works
- If the next due date is valid, it remains unchanged.
- If the next due date falls on an invalid day, it shifts forward until it lands on an applicable day.
- If no applicable days are set, the chore follows its normal recurrence pattern without skipping days.
Example 1: Custom Interval with Applicable Days
- A chore repeats every 3 days, but only on Mondays and Wednesdays.
- If today is Thursday, the next occurrence would normally be Sunday.
- Since Sunday isnβt allowed, it will move forward to Monday.
Example 2: Weekly Recurring Chore With Multiple Applicable Days
- A chore is weekly, allowed on Monday and Wednesday.
- If it starts on Monday, the system will always schedule it on Monday.
- If something reschedules it to Wednesday, it will stay on Wednesday until another event moves it again.
This means a weekly chore set for Monday and Wednesday will not automatically switch between daysβit will stay on the first applicable day it lands on until manually rescheduled or skipped.
π Multiple Claims Per Day Handling
Some chores allow multiple claims per day, meaning a user can claim and complete the same chore multiple times before midnight.
β If a chore allows multiple claims per day:
- It remains in the approved state, but the system still allows it to be claimed again within the same day.
- The approval status does not block further claims, and points are awarded for each successful claim.
β If a chore does NOT allow multiple claims per day:
- Once it is claimed and approved, no further claims can be made until midnight.
- If a user tries to claim it again, the system prevents the action and indicates the chore has already been completed for the day.
β Midnight Reset Behavior:
- All chores, regardless of multiple claims setting, reset at midnight to pending with the next scheduled due date (if applicable).
π Chore Global State Handling
Each chore has an individual state per kid, but there is also a global state that applies when a chore is assigned to multiple kids. The global state helps track progress and ensures proper handling of independent and shared chores.
There are four key scenarios for how the global state is determined:
Scenario 1: Single Kid, Single Chore
For chores assigned to only one kid, the global state always matches the kidβs individual chore state.
| Chore State | Global State (global_state) |
|---|---|
| pending | pending |
| claimed | claimed |
| approved | approved |
| overdue | overdue |
Scenario 2: Multiple Kids β Independent Completion
When a chore is assigned to multiple kids but completed individually, the global state is set to independent when kids have different chore states, including if at least one is overdue.
| Kids' Chore States | Global State (global_state) |
|---|---|
| All pending | pending |
| All claimed | claimed |
| All approved | approved |
| All overdue | overdue |
| Mixed states (including at least one overdue) | independent |
Scenario 3: Shared Chore β Completion Required for All Assigned Kids
For shared chores, all assigned kids must complete the task before it is fully approved. To reflect partial progress, two additional states are introduced:
- claimed-in-part β At least one kid has claimed it, but others have not.
- approved-in-part β At least one kid has received approval, but others have not.
| Kids' Chore States | Global State (global_state) |
|---|---|
| All pending | pending |
| At least one claimed, others pending | claimed-in-part |
| All claimed | claimed |
| At least one approved, others claimed/pending | approved-in-part |
| All approved | approved |
| At least one overdue | overdue |
Scenario 4: Shared First β First Kid to Complete Gets Credit
For shared-first chores, only the first kid to complete and get approved receives credit. Once approved, the chore is completed for all assigned kids. Other kids see the chore as completed_by_other.
| Kids' Chore States | Global State (global_state) |
|---|---|
| All pending | pending |
| First kid claimed, others pending | claimed |
| First kid approved, others see completed_by_other | approved |
| At least one overdue (before anyone claims) | overdue |
| First kid claimed after overdue | claimed |
| First kid approved after overdue, others completed_by_other | approved |
Key Points:
- Once the first kid gets approved, all other kids' individual states change to completed_by_other.
- The global state reflects the state of the first kid who claimed and completed the chore.
- If the chore becomes overdue before anyone claims it, the global state is overdue until someone claims it.
Summary
- Single-kid chores β Global state always matches individual state.
- Independent chores β Global state is "independent" if kids are at different states.
- Shared chores (all must complete) β Shows status of "in-part" when kids are at different states, except for overdue where one kid overdue makes the full chore overdue.
- Shared-first chores β Global state matches the first kid's state; others see completed_by_other after approval.