Configuration: Chores Advanced - ad-ha/kidschores-ha GitHub Wiki

Chore Advanced Features

Prerequisites: Familiarity with Chore Configuration Guide

[!NOTE] This guide is for complex household workflows: per-kid schedules, multi-times-per-day chores, strict claim windows, and turn-based rotation.

Who This Is For

Use this page if you need one or more of these:

  • Different schedules per Kid for the same Chore
  • More than one completion window per day
  • Recurrence based on completion timing
  • Strict “not yet claimable” windows
  • Rotation with fairness and optional steal behavior

If you just need standard daily/weekly chores, use Chore Configuration Guide.

How To Read This Page

Advanced configuration is easiest when done in this order:

  1. Build the advanced schedule
  2. Configure claim timing and reminders
  3. Configure approval boundary behavior
  4. Apply rotation and overdue strategy

1) Advanced Scheduling

Daily Multi (multiple completions per day)

Use Daily (Multiple times per day) when one Chore should appear at multiple time slots.

  • Time format: HH:MM|HH:MM|HH:MM
  • Each slot is a separate completion opportunity
  • Use realistic slot counts to avoid overload

[!IMPORTANT] Daily Multi has compatibility validation. If a combination is not allowed, the flow blocks save with a clear error.

Where Daily Multi times are entered

  • Shared modes or single-kid independent: one shared daily_multi_times field in helper step
  • Independent with multiple Kids: per-kid daily times fields in the per-kid helper

Custom interval recurrence

Use Custom for interval-based recurrence from schedule boundaries.

Examples:

  • Every 3 days
  • Every 2 weeks
  • Every 6 hours (short-term workflows)

Custom from completion

Use Custom from completion when next due time should be calculated from when the Chore was actually completed.

Best for maintenance-style chores where interval-after-completion matters.

This is different from approval reset timing. Treat them as two independent controls:

  • Approval reset type (including Upon completion) controls when approved returns to pending.
  • Frequency (Custom interval vs Custom from completion) controls what timestamp recurrence uses for the next due date.

Clear behavior examples:

  • Upon completion + Custom interval: resets to pending immediately, then next due date still follows normal due-date-based recurrence scheduling.
  • Upon completion + Custom from completion: resets to pending immediately, and next due date is anchored to completion timestamp.

You can use either behavior alone, or combine both when needed.

[!TIP] Hour-based recurrence is powerful but can create alert fatigue. Keep it intentional.

2) Per-Kid Helper (Independent + Multiple Kids)

When completion criteria is Independent and multiple Kids are assigned, the flow can open per-kid helper fields.

Per-kid fields may include:

  • Applicable days per Kid
  • Daily Multi times per Kid
  • Due date per Kid
  • Clear due date per Kid

Use this to run one shared Chore definition with individualized schedules.

Common use cases

  • Split-week routines (Kid A early week, Kid B late week)
  • Different school-night/weekend schedules
  • Different Daily Multi slot times by Kid age/routine

3) Claim Timing, Locking, and Reminders

Due window offset

chore_due_window_offset controls when a Chore transitions into the due window before due date.

Format accepts duration strings like:

  • 30 (minutes)
  • 1d 6h 30m
  • 0 (disable)

If disabled (0), the chore stays in normal pending-style availability until other timing rules apply. Due window is an optional refinement layer, not a requirement.

Lock claim until due window opens

chore_claim_lock_until_window prevents kids from claiming before the due window starts.

When this lock is active, a Kid can see Waiting (Due Window Not Open).

4) Approval Cycle Controls

Think in three lanes:

  • Trigger lane: approval_reset_type
  • Pending-claim lane: approval_reset_pending_claim_action
  • Overdue lane: overdue_handling_type

Approval reset type

Controls when the approval boundary fires:

  • Once per day
  • Multiple times per day
  • At due date (single or multi)
  • Upon completion
  • Manual reset only

In plain terms: after a chore is approved, this setting controls when it becomes pending/claimable again.

Important: Upon completion changes reset timing only. It does not change recurrence anchor math by itself.

Pending claim action

Controls what happens to unapproved claims at the boundary:

  • hold_pending
  • clear_pending
  • auto_approve_pending

Auto approve

auto_approve can reduce parent overhead for trusted chores.

Use carefully when accountability or review is still important.

5) Visibility and Notification Controls

These controls are part of advanced tuning and are easy to miss if you only use defaults.

Chore notifications (chore_notifications)

Choose which workflow moments generate notifications. Available notification moments include:

  • claim
  • approval
  • disapproval
  • overdue
  • due-window start
  • due reminder

Use this to reduce noise while preserving high-value alerts.

Due reminder offset (chore_due_reminder_offset)

Controls when due reminder notifications fire before due date.

  • Uses duration format like 30m, 1h 20m, 1d 2h
  • Works with notification selections for due reminders

Show on calendar (show_on_calendar)

Controls whether the Chore appears in calendar-based views.

  • Enable for schedule-centric household planning
  • Disable for low-signal chores you do not want in calendar surfaces

Labels (chore_labels)

Labels support organization, grouping, and dashboard filtering.

Use labels when they improve sorting or filtering. Keep label taxonomy simple and consistent.

6) Rotation and Overdue Strategies

Rotation modes

Rotation Simple

  • Turn-holder only before overdue unlocks
  • Strict order advancement

Rotation Smart

  • Turn-holder only before overdue unlocks
  • Fairness-weighted advancement

Fairness selection uses completion history and recency so turns do not stay unbalanced.

Rotation lock states

Kids can encounter these valid blocked states:

  • Not My Turn (Rotation)
  • Missed (Locked)

Allow Steal (rotation-only overdue strategy)

Allow Steal Until Approval Reset (Rotation Only) changes claim behavior after due time.

  • Before due: only turn-holder claims
  • After due: other assigned Kids can claim (steal window)
  • If nobody completes before boundary: overdue policy resolves and turn advances

[!WARNING] Allow Steal is valid only when all are true:

  • Completion criteria is rotation_simple or rotation_smart
  • Approval reset type is once-per-day style
  • Due date is set

High-Value Patterns

Pattern A: Split-week independent household

  • Completion: independent
  • Per-kid applicable days
  • Optional per-kid due dates

Pattern B: Meal-based recurring chore

  • Frequency: Daily Multi
  • Times: morning/lunch/evening slots
  • Lower points per slot for balance

Pattern C: Fair sibling turn-taking

  • Completion: rotation simple or rotation smart
  • Due window lock enabled
  • Optional allow-steal for late-window flexibility

Pattern D: Low-noise, high-signal notifications

  • Configure chore_notifications for only overdue + due reminder + disapproval
  • Keep claim/approval notifications off for routine chores
  • Leave calendar visibility on only for chores that are schedule-critical

Troubleshooting

Per-kid helper did not appear

  • Confirm completion criteria is independent
  • Confirm multiple Kids are assigned

Daily Multi helper did not appear

  • Confirm frequency is Daily Multi
  • Confirm required schedule fields are set

Save blocked by compatibility error

  • Read validation message and adjust the incompatible pair
  • Common source: Daily Multi + incompatible approval-reset selection
  • Common source: Allow Steal + non-rotation completion mode

Kid cannot claim

  • Check state/lock reason on the chore status entity
  • Common lock reasons: waiting, not_my_turn, missed
  • Verify due window lock and rotation settings for that Chore