Skip to main content

Adaptive chore decomposition — evidence-based, cache-first, on-device AI

Date: 2026-07-29 · Status: Proposed (design agreed; nothing built) · Epic: TBD Branch: claude/adaptive-chore-ai-platform-qkvd8a

Rewhaven should present each chore at the granularity a person actually needs — the same "strip the bed" is one line for one member and pillow off bed → blanket off bed → sheet off bed → sheet into hamper for another. This ADR records the design for producing and serving those breakdowns: an evidence-based, cache-first system with a small fine-tuned Gemma 4 model at the generation edge, running on-device for the free tier and server-side for the paid tier. It is forward-looking — no code exists yet — and it deliberately keeps per-person adaptation as data, not model weights.

North-Star fit: adjustable granularity is a fade lever. A member can be scaffolded with micro-steps and have the scaffold thinned as competence grows — intrinsic motivation is the destination, granularity the dial.

Core decision​

Decompose chores through four layers, cheapest-first, so a language model is invoked only at the genuine novelty edge:

  1. Canonical heads — a controlled vocabulary of chore intents (clean_bedroom, clean_kitchen, strip_bed, …). Free-text is reduced to a head before anything else.
  2. Cache — each head × granularity level has a stored, evidence-based, human-authored breakdown. Known chores are a database read: $0, offline, zero hallucination.
  3. Fine-tuned Gemma 4 E2B, on-device — generates a breakdown for a genuinely novel chore, for free-tier users, on their own device.
  4. Server-side Gemma 4 (larger variant) — the paid tier and all TV clients; higher-quality generation, hosted on scale-to-zero inference (never a dedicated always-on GPU).

Every generated breakdown is written back to the cache, so the taxonomy grows from real use and future phrasings of that chore become free reads. The seed content for layers 1–2 comes from a Phase 0 evidence-collection effort (below) — this is what makes the whole system accurate from day one rather than plausibly-guessed.

What this is not: not a per-user model, not training from scratch, not Vertex-on-edge. Those are rejected below.

Phase 0 — evidence-based data collection (the foundation)​

The cache is only as good as its seed content. Phase 0 grounds that seed in peer-reviewed literature, applied by a qualified domain expert. This is what makes "our breakdowns are evidence-based, with citations" a true and auditable claim.

Two axes, two bodies of literature​

AxisLiterature to mineWhat it gives us
Which chores, which ageDevelopmental psychology (age-appropriate responsibility research — e.g. Rossmann/U-Minnesota longitudinal chore work; developmental-milestone frameworks; Montessori practical-life sequences)The age_band → chore mapping
How much to break down, which cognitive profileTask analysis + chaining (special education / ABA — forward/backward chaining, step-size selection); Occupational-therapy activity analysis & grading (ADL/IADL taxonomy; grading task demand up/down); executive-function / cognitive-load frameworksThe granularity model and the cognitive_profile → step-size mapping

Task analysis is literally the science of the "pillow off bed → blanket off bed …" idea; OT activity-grading is literally the per-person granularity dial. The technique is well-established and peer-reviewed.

The method: extract rules, then instantiate them​

Papers give principles and parameters, not ready-made step lists. Phase 0 is therefore two moves:

  1. Extract the evidence-based rules — which chores at which ages, how to grade granularity by capability, which chaining method. (Literature review; no ethics approval needed.)
  2. A qualified expert instantiates them — an OT, special-ed specialist, or developmental psychologist authors the concrete breakdowns; the citation backs the rule they applied.

So the peer-reviewed data grounds the method; the expert produces the content. Budget for that expert-in-the-loop (university collaborator or clinician advisor) — it is what lets us truthfully say the breakdowns are evidence-based rather than model-generated and plausible.

Provenance is carried into the data​

Every recommendation and breakdown records its lineage, so a caregiver or clinician can see "this applies OT activity-grading principles, authored by [expert], citing [source]." See the data model below (evidence_source, authored_by, reviewed_by).

Phase 0 produces three assets at once​

  • Seed cache content (evidence-based, expert-authored heads + breakdowns).
  • The gold training set for the E2B fine-tune (the model learns from validated data, not scraped guesses).
  • The citation layer that makes the product auditable and trustworthy.

Runtime architecture​

The resolver — reducing free-text to a head (cheapest-first cascade)​

Do not hand the raw phrasing to the model; route it in stages and escalate only on failure:

  1. Exact / alias lookup — plain string match against a synonym table ("vacuum the lounge" → clean_living_room). Zero compute.
  2. Embedding similarity — embed each head's description once; at runtime embed the phrase and take the nearest head by cosine similarity. Supabase pgvector hosts this in the DB; the tiny embedding model can also run on-device to keep it free and offline.
  3. LLM fallback — only for low-confidence / ambiguous cases: hand the model the top candidate heads + the phrase and let it choose.
  4. Novel — nothing clears the threshold → generate (layer 3/4) → create a new head, embed it, cache the breakdown. Every future phrasing of that chore now hits the cache.

Mis-resolution safeguard: high-confidence matches proceed silently; borderline matches get a light confirmation ("Breaking this down as Clean the kitchen — that right?"). Wrong steps are disruptive for our users, so this UX guard is load-bearing, not cosmetic.

Two senses of "variant" — separated deliberately​

  • Phrasing variants → same head (infinite wordings, one intent). Build now. Pure upside; this is what lifts the cache hit rate to near-total.
  • Structural variants → shared schema (clean_bedroom / clean_kitchen share a shape but differ in subtasks). Keep heads flat — each is its own cached breakdown. A shared prompt scaffold may be used at authoring time for consistency, but no runtime parameterization; rooms diverge enough that a shared runtime template causes more edge cases than it saves.

Personalization stays in context, never in weights​

A member's granularity level (and sensory/EF notes) is an editable profile field passed at inference, so a caregiver can change it instantly and inspect it. The fine-tune bakes in the decomposition style/format only — never per-person behavior.

Model tiering​

SurfaceTierInferenceNotes
Web / mobileFreeGemma 4 E2B, on-device (MediaPipe .task)Offline, $0/call. .task covers Android + iOS + Web from one conversion.
Web / mobilePaidServer-side Gemma 4 (larger variant)Higher quality. Paid users may use both — on-device for offline/instant, server when online for best quality.
TVPaid (gated)Server-side Gemma 4 (cloud)TV silicon is RAM/GPU-starved and multi-device sync is harder → gate as premium, serve from cloud.

Consistency: same family keeps behavior aligned, but E2B and the server model differ. Fine-tune only E2B (its job is to punch above its weight); the server model likely needs only the same few-shot example set, not a second fine-tune to maintain. The cache equalizes both tiers on known chores, so tier differences only surface on novel chores — a small surface.

"Max context" is over-spec for this task. A breakdown needs a few thousand tokens; the paid win is quality + richer personalization, not context length. Don't provision the max-context config unless a future feature genuinely feeds large context (full household history/logs).

Hosting — scale-to-zero, not an always-on GPU​

Because of the cache, server generation fires only on novel chores: low-volume and spiky — the exact wrong shape for a dedicated 24/7 GPU (which would quietly reverse the "cheapest to run" goal). Use per-request / scale-to-zero managed inference (Vertex AI, Together, Fireworks, Baseten, HF Inference Endpoints). Own-GPU only if sustained volume ever justifies it.

Write-back is the sync mechanism​

The on-device model is a static asset shipped with the app — nothing to sync. Only results need to persist, and writing them back to Supabase makes them appear on every device: a breakdown generated on a phone shows up on the TV and web automatically. Two-layer cache:

  • Global cache — common chores, curated/shared.
  • Per-household cache — custom chores, household-scoped (matches RLS).

This softens the "TV sync is harder" problem: TV mostly reads cached content and only touches the cloud model for genuinely novel chores.

Data model sketch​

chore_head
  id, canonical_name, description, embedding vector,
  aliases[], scope (global | household), household_id (nullable)

chore_steps                       -- the cached breakdown
  head_id, granularity_level, steps[],
  authored_by, reviewed_by, evidence_source_id[]

evidence_source                   -- provenance / citations
  id, authors, title, journal, year, doi, url, license_note

chore_recommendation              -- which chores suit whom, and why
  head_id, age_band, cognitive_profile, evidence_source_id[]

Resolution: input → resolve to head_id → chore_steps at the member's granularity_level.

Common heads are scope = global; household-invented custom chores are scope = household under the existing household-scoped RLS.

Fit with the one data path (open architectural item)​

Decomposition is a Service concern (domain rule: reduce phrasing → head → serve/generate → cache). Cache reads/writes go through the existing adapter seam (Drift local + Supabase cloud), so presentation still touches only the facade — consistent with Bloc → Repository → Client (facade) → Service → Adapter.

Unresolved: on-device model inference is platform I/O (a Flutter/MediaPipe plugin) and cannot live in the pure-Dart client_sdk. How the on-device generator is wired — a config-driven "inference port" on ClientConfig, versus an app-layer capability — must be resolved against the load-bearing rule "SDK construction is config-driven — never inject an adapter." The resolver + cache clearly belong in the SDK; the generation fallback is the piece that needs a home. Flagged for a follow-up ADR before implementation.

Rejected alternatives​

AlternativeWhy not
Train a model from scratchNeeds millions of examples + serious compute + an ML team, to end up worse than a cheap API call. Non-starter.
Per-user fine-tune ("train it on each person's traits")Personalization must be an editable, inspectable profile field, not baked into weights. Wrong tool.
Vertex-on-edge as the "cheapest to run" pathVertex is a managed cloud platform; its edge story is heavyweight. The real edge lever is a small open model (Gemma 4 E2B) via MediaPipe.
LLM classifies every request → headPays for an inference call to do what embeddings do for free. Kept only as a low-confidence fallback.
Runtime-parameterized clean_room templateRooms diverge enough that a shared runtime schema causes more edge cases than it saves. Keep heads flat; use shared scaffolds only at authoring time.
Fine-tune the server model tooLikely unnecessary — the larger model + the same few-shot examples is already strong, and a second fine-tune is another artifact to retrain and keep in sync. Revisit only if evals show a gap.
Always-on GPU for server inferenceCache makes novel-chore volume low and spiky; an idle GPU burns money 24/7. Scale-to-zero fits the load shape.
Frontier model for generationOn a constrained, few-shot-anchored task the quality gap over a cheap/tuned small model collapses; not worth the per-call cost or the loss of on-device capability.

Accuracy & hallucination posture​

The task is inherently low-hallucination (a constrained decomposition, not open-ended recall), so every layer is already in a good regime. Ranked most-to-least reliable:

  1. Evidence-based, human-reviewed cached content — zero hallucination. The safety-critical core catalog. A wrong or missing micro-step genuinely disrupts our users, so this is where the guarantee must hold.
  2. Server-side Gemma 4 + few-shot — effectively no hallucination.
  3. Fine-tuned E2B + the same examples — very reliable; the fine-tune + few-shot close most of the gap to a larger model on this narrow task.
  4. Any small model without examples/fine-tune — the most variable; not used.

Few-shot examples in context are the single biggest accuracy lever: they anchor granularity and slash format drift, and the effect is largest on the small/on-device model — which is what lets us use the cheapest model and still be reliable.

Safeguards​

  • Mis-resolution → confirm borderline head matches (above).
  • Neurodiversity-affirming sourcing → the task-analysis technique is sound, but some older ABA literature is contested by autistic self-advocates and framed in deficit terms. Weight sources toward strengths-based, affirming, and autistic-led scholarship; use the decomposition method without importing deficit language. Given Rewhaven's mission this curation is load-bearing.
  • Copyright → extract facts/principles and cite; do not lift proprietary assessment instruments or published chore charts verbatim (several standardized OT/developmental instruments are licensed).
  • Ethics → literature review needs no IRB. If the project later collects data from real users — especially children — that crosses into IRB/consent territory and needs its own review.

Cost posture (summary)​

  • Known chores: $0 (cache read), every tier, offline-capable.
  • On-device novel generation (free tier): $0 marginal.
  • Server novel generation (paid/TV): sub-cent per call on scale-to-zero inference, and rare because the cache absorbs the common case; write-back means each novel chore is paid for once.
  • Filling the initial catalog via generation is a one-time few-dollars cost even at a high tier — but Phase 0 authors the safety-critical core by hand/expert instead.

Open items​

  • Inference-port wiring vs the "config-driven, never inject an adapter" rule (above) — needs a follow-up ADR before build.
  • Granularity-level vocabulary — enum (e.g. chunks / steps / micro-steps) vs 1–5 scale; must align with the OT activity-grading model chosen in Phase 0.
  • Head taxonomy scope — where the global/household cache boundary sits, and curation workflow for promoting a household custom chore to a reviewed global head.
  • Verify current Gemma 4 edge variant details (E2B vs E4B) and MediaPipe .task quantization quality on target devices — evaluate the quantized artifact, not the fp16 fine-tune (int4 can degrade a format-sensitive task).
  • TV runtime — Android TV rides the Android path; Apple TV / smart-TV OSes fall back to cache + cloud rather than embedding.
  • Expert-in-the-loop — identify the OT / special-ed / developmental-psychology collaborator for Phase 0.

Developer portal​

This design is surfaced in the developer portal (the hosted architecture reference) as a feature page: app/test-gallery/authored/developer/architecture/features/adaptive-chore-decomposition.md. It cross-links the adjacent Clinical OT framework page (the OT activity-analysis/grading evidence base), Today (chore surface) (where a resolved breakdown is rendered/completed), and Routines (a decomposed chore executes as an ordered step sequence). This ADR remains the full decision record; the portal page is the higher-level architecture summary. Keep the two in sync when a load-bearing decision here changes.

Relation to existing decisions​

  • Extends the chore/catalog domain; served through the existing one-data-path SDK seam.
  • Household-scoped custom heads honor the existing zero-trust RLS model.
  • Granularity-as-fade-dial supports the North Star ("fade to intrinsic motivation") and the self-governed-modes direction (a graduated member thins their own scaffolding).