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

Chore Configuration Guide

Prerequisites: Completed Quick Start Guide

[!NOTE] This guide explains the standard Chore setup flow for most families. For advanced scheduling, turn-based rotation, and due-window claim controls, see Chore Advanced Features.

Overview

Use this page to configure Chores that are clear, fair, and easy to manage.

You will make four key decisions:

  1. Who completes the Chore (completion_criteria)
  2. When the Chore is due and repeats (recurring_frequency, due_date, days)
  3. How approval boundaries behave (approval_reset_type, pending claim action)
  4. What happens when a Chore is late (overdue_handling_type)

Form Layout

The Add/Edit Chore form is organized into three sections.

Definition

  • Name
  • Description
  • Icon
  • Points
  • Assigned Kids
  • Completion Criteria

Schedule

  • Frequency
  • Due Date
  • Applicable Days
  • Due Window Offset
  • Claim Lock Until Window
  • Custom Interval fields (only when custom frequency is selected)

Advanced Configurations

  • Approval Reset Type
  • Pending Claim Action
  • Auto Approve
  • Overdue Handling
  • Due Reminder Offset
  • Notifications
  • Show on Calendar
  • Labels

Completion Criteria

Choose how completion is tracked.

Independent

Each assigned Kid gets an independent instance of the Chore.

  • Separate claim/approval state per Kid
  • Separate due/schedule behavior per Kid when per-kid helper fields are used
  • Best for personal routines

Shared (All)

All assigned Kids are expected to complete within the cycle.

  • Group progress can show partial completion states
  • Best for teamwork Chores

Shared (First)

One Kid completes for the group.

  • First successful claimer/completer wins the cycle
  • Other assigned Kids are blocked for that cycle
  • Best for “one person handles it” Chores

Rotation Simple

Strict turn order for assigned Kids.

  • Only the current turn-holder can claim before overdue (unless cycle override is used)
  • Turn advances in list order

Rotation Smart

Turn-based, fairness-weighted assignment.

  • Only the current turn-holder can claim before overdue (unless cycle override is used)
  • Next turn is selected by fairness logic: fewest approvals first, then oldest last-approved time, then assigned list order as tie-breaker

[!TIP] Rotation modes are best when you want consistent accountability across siblings.

Scheduling

Frequency

Common options:

  • None (one-time)
  • Daily / Weekly / Biweekly / Monthly
  • Custom interval
  • Custom from completion
  • Daily Multi (configured in helper step)

[!TIP] Important distinction:

  • Frequency determines how the next due date is calculated.
  • Approval reset type determines when approved state returns to pending.

Due Date

Sets the due boundary used by reminder, due-window, overdue, and approval-boundary behavior.

Applicable Days

Optional day filter for when a Chore is active.

  • Leave blank to allow all days
  • Use day restrictions only when needed

Due Window and Claim Lock

Use together to control early claiming behavior.

  • chore_due_window_offset: defines when the due window starts
  • chore_claim_lock_until_window: blocks claiming before the due window opens

When lock-until-window is enabled, Kids may see a waiting state until the window opens.

Approval and Late-Handling Controls

These settings answer a simple question: after a chore is approved, when does it become available again, and what happens if it is late or still waiting for approval?

Think of approval behavior as three independent lanes:

  1. Trigger lane (approval_reset_type): when the boundary fires
  2. Claim lane (approval_reset_pending_claim_action): what happens to unapproved claims at that boundary
  3. Overdue lane (overdue_handling_type): overdue behavior at due time and boundary

Use this model when combining settings so behavior stays predictable.

Approval Reset Type

Defines when approval boundaries occur:

  • Once per day
  • Multiple times per day
  • At due date (single or multi)
  • Upon completion (resets approval state immediately after completion; then reschedules using the chore's normal recurrence rules based on due-date/schedule logic)
  • Manual

[!TIP] Upon completion controls when approval reset happens. It does not switch recurrence to completion-time math. For recurrence that uses completion timestamp instead of due-date scheduling, use Custom from completion in Chore Advanced Features.

Pending Claim Action

Defines what happens if a claim is still pending at the boundary:

  • Hold pending
  • Clear pending
  • Auto-approve pending

Overdue Handling

Defines late behavior for the Chore.

Common options include:

  • Never overdue
  • Overdue at due date
  • Clear overdue at approval boundary
  • Clear overdue immediately on late completion
  • Clear and mark missed
  • Mark missed and lock
  • Allow steal until approval boundary (rotation only)

[!WARNING] Allow steal is rotation-only and requires compatible rotation + approval boundary settings. See Chore Advanced Features for exact compatibility.

Daily Multi and Per-Kid Helpers

Some settings are completed in helper steps after the main form:

  • daily_multi_times
  • Per-kid fields for independent chores with multiple Kids (such as per-kid applicable days, times, and due dates)

If you select a mode that needs these values, the flow routes you to the correct helper step automatically.

Practical Defaults

Start simple, then refine:

  • Completion criteria: independent
  • Frequency: daily or weekly
  • Approval reset: once-per-day style
  • Pending claim action: auto-approve or clear, based on household preference
  • Overdue handling: clear immediate on late (balanced default behavior)

Troubleshooting Quick Checks

  • Chore not visible today: check applicable_days, due window, and claim lock
  • Kid cannot claim: check current state and lock reason (waiting / not my turn / missed)
  • Daily Multi not prompting: ensure required base schedule fields are set before helper step
  • Rotation confusion: verify completion criteria is rotation mode and assigned Kids list order is correct