chore/.github/specs/plan-achievements.md

Plan: Achievements Feature Design

Published to Gitea wiki page: Achievements

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

1. Phase 1: Define achievement taxonomy and product goals
2. Define families: points progression, consistency/streaks, reward habits, task diversity, check-in/engagement, social/funny outcomes.
3. Define unlock semantics: one-time unlocks vs repeatable milestones, per-child scope, optional parent aggregate view. Depends on step 2.
4. Define badge rarity tiers (common, rare, epic, legendary) and naming/tone guide so achievements feel playful, not punitive.
5. Phase 2: MVP achievement set (no new raw telemetry)
6. Use existing TrackingEvent and PendingConfirmation signals to launch 20-30 achievements immediately. Depends on phase 1.
7. Include serious progression set: first points earned, 100/500/1000 lifetime points, best day records, no-miss week, kindness count milestones.
8. 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).
9. 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).
10. Phase 3: Data model and evaluation architecture
11. Add achievement definition catalog (static or DB-backed) and child achievement progress/unlock records. Depends on phase 2.
12. Evaluate on mutation events (tracking event creation, chore confirmation, reward request/redeem), with idempotent unlock logic and timezone-aware daily boundaries.
13. Emit achievement unlocked SSE events for real-time UI celebration and maintain API for achievement list/progress.
14. Phase 4: UX and rollout
15. Parent view: child achievement timeline, rarity filters, and progress-to-next badge.
16. Child view: badge cabinet, streak flame, and lightweight celebration effects.
17. Roll out behind feature flag, start with read-only earned badges, then add near-miss/progress indicators. Depends on phase 3.
18. Phase 5: Validation and balancing
19. Add unit tests for each rule family and timezone edge cases.
20. Add end-to-end tests for unlock notifications and badge rendering.
21. Run a balancing pass using anonymized historical events to ensure unlock pacing feels rewarding (not too sparse, not too noisy).
22. 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

1. Rule correctness: seed deterministic tracking histories and verify each achievement unlock threshold exactly once.
2. Timezone correctness: validate day/week achievements for users in at least three timezones and around midnight boundaries.
3. Idempotency: replay the same event stream and verify no duplicate unlocks.
4. UX behavior: confirm unlocked badges appear in parent and child views without manual refresh via SSE.
5. 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

1. 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.
2. 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.
3. 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.
4. Progress UX recommendation: show top 3 near-unlock achievements to increase motivation without overwhelming the child dashboard.
5. Seasonal/event achievements recommendation: add limited-time badges after baseline system proves stable.
6. 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.
7. 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.
8. Backfill and migration recommendation: run one-time historical recompute job to award existing users fairly; mark job version so reruns are idempotent.
9. Observability recommendation: emit achievement engine metrics (rules evaluated, unlock count, rule errors, evaluation latency) and add dead-letter logging for malformed catalog entries.