chore

ryan/chore

Table of Contents

Plan: Achievements Feature Design

Plan: Achievements Feature Design

Design an achievements system that starts with low-risk, high-fun rules using existing tracking data, then expands to streak and behavior achievements. This approach gives fast player-visible value without major schema risk, while leaving room for deeper gamification. Status: Approved by user for implementation kickoff.

Steps

Phase 1: Define achievement taxonomy and product goals
Define families: points progression, consistency/streaks, reward habits, task diversity, check-in/engagement, social/funny outcomes.
Define unlock semantics: one-time unlocks vs repeatable milestones, per-child scope, optional parent aggregate view. Depends on step 2.
Define badge rarity tiers (common, rare, epic, legendary) and naming/tone guide so achievements feel playful, not punitive.
Phase 2: MVP achievement set (no new raw telemetry)
Use existing TrackingEvent and PendingConfirmation signals to launch 20-30 achievements immediately. Depends on phase 1.
Include serious progression set: first points earned, 100/500/1000 lifetime points, best day records, no-miss week, kindness count milestones.
Include funny set: zero points 7 days, last-minute legend (frequent late confirmations), window shopper (many reward requests without redemption), tiny spender (chooses low-cost rewards repeatedly).
Include non-point set: reward loyalty (same reward redeemed N times), variety collector (N distinct chores completed), daily checker (opened/triggered chores on N consecutive days), comeback kid (returns after inactivity).
Phase 3: Data model and evaluation architecture
Add achievement definition catalog (static or DB-backed) and child achievement progress/unlock records. Depends on phase 2.
Evaluate on mutation events (tracking event creation, chore confirmation, reward request/redeem), with idempotent unlock logic and timezone-aware daily boundaries.
Emit achievement unlocked SSE events for real-time UI celebration and maintain API for achievement list/progress.
Phase 4: UX and rollout
Parent view: child achievement timeline, rarity filters, and progress-to-next badge.
Child view: badge cabinet, streak flame, and lightweight celebration effects.
Roll out behind feature flag, start with read-only earned badges, then add near-miss/progress indicators. Depends on phase 3.
Phase 5: Validation and balancing
Add unit tests for each rule family and timezone edge cases.
Add end-to-end tests for unlock notifications and badge rendering.
Run a balancing pass using anonymized historical events to ensure unlock pacing feels rewarding (not too sparse, not too noisy).
Documentation deliverable: publish the final approved achievements plan to a new Gitea wiki page for the chore project as part of implementation handoff.

Relevant files

/Users/ryan/Projects/chore/backend/models/tracking_event.py - existing event ledger for points/actions and occurred_at timestamps.
/Users/ryan/Projects/chore/backend/models/pending_confirmation.py - reward/chore confirmation states useful for request/approval achievements.
/Users/ryan/Projects/chore/backend/db/tracking.py - insertion/query leverage point for achievement evaluation trigger.
/Users/ryan/Projects/chore/backend/events/types/event_types.py - event taxonomy to extend with achievement unlock notifications.
/Users/ryan/Projects/chore/backend/api/child_api.py - existing child-facing data APIs to mirror for achievement endpoints.
/Users/ryan/Projects/chore/frontend/vue-app/src/common/models.ts - add Achievement interfaces (backend parity).
/Users/ryan/Projects/chore/frontend/vue-app/src/common/backendEvents.ts - frontend SSE subscriptions for unlock celebrations.
/Users/ryan/Projects/chore/frontend/vue-app/src/common/api.ts - API helpers for listing achievements and progress.

Verification

Rule correctness: seed deterministic tracking histories and verify each achievement unlock threshold exactly once.
Timezone correctness: validate day/week achievements for users in at least three timezones and around midnight boundaries.
Idempotency: replay the same event stream and verify no duplicate unlocks.
UX behavior: confirm unlocked badges appear in parent and child views without manual refresh via SSE.
Regression safety: run backend pytest suite and focused Playwright specs for parent/child dashboards.

Decisions

Included in MVP: achievements derivable from existing signals (tracking events, pending confirmations, child points, reward history).
Data schema decision for wave 1: no new fields required on task/chore/reward models (no complexity/category requirement for initial launch).
Deliberately excluded from MVP: complex streak rules requiring schedule reinterpretation across every task mode; these are phase 2+ enhancements.
Scope model: per-child achievements first, optional parent-level achievements later.
Tone model: include playful/funny achievements but avoid shaming language; treat low-performance badges as light easter eggs.

Further Considerations

Modularity architecture recommendation: isolate all achievement logic into an Achievement Engine module with a rule interface (evaluate(event, context) -> unlocks) and a central registry so no existing chore/reward/business logic needs branching changes.
Toggle recommendation: add a global feature flag plus optional per-user flag; when disabled, route through a no-op evaluator and suppress achievement APIs/SSE/UI sections without impacting core chore/reward flows.
Editability recommendation: store initial achievement definitions in a versioned JSON or YAML catalog with schema validation at startup, stable ids, enabled flag, and threshold params so add/remove/edit is config-only for most rules.
Progress UX recommendation: show top 3 near-unlock achievements to increase motivation without overwhelming the child dashboard.
Seasonal/event achievements recommendation: add limited-time badges after baseline system proves stable.
UI isolation recommendation: keep achievement state in a dedicated frontend store/module and render via isolated components; chore/reward screens should only publish domain events and never compute achievement rules directly.
UI kill-switch behavior: when feature flag is off, hide achievement routes/cards/listeners behind one composition helper so no scattered conditional logic across pages.
Backfill and migration recommendation: run one-time historical recompute job to award existing users fairly; mark job version so reruns are idempotent.
Observability recommendation: emit achievement engine metrics (rules evaluated, unlock count, rule errors, evaluation latency) and add dead-letter logging for malformed catalog entries.