sundog-calculator/docs/kaya-transition.md

# Feeding Transition Calculator — Implementation Guide (30 kg adult)

## 1) Purpose & principle

- The calculator **keeps energy intake continuous** while transitioning from kibble (current) to gently cooked (GC, target).
    
- Internally it uses the **kibble chart’s month-level precision**; externally it **communicates in GC phases** (<5 mo, 5–6 mo, 7–12 mo).
    

* * *

## 2) Fixed scope

- Dog profile: **30 kg adult** only.
    
- Supported ages: **2.0 to 12.0 months** inclusive.  
    If the user enters a value outside this range, **clamp** to the nearest bound and show a subtle note.
    
- Required configuration at runtime: **kibble energy density (kcal per 100 g)**.  
    If missing, show an error and do not compute.
    

* * *

## 3) Data you must hard-code

1.  **Kibble reference points (grams/day, 30 kg column):**  
    (2→250), (3→330), (4→365), (6→400), (8→410), (10→410), (12→405).
    
2.  **Interpolated monthly kibble (round to whole grams):**
    

- 2 mo: 250
    
- 3 mo: 330
    
- 4 mo: 365
    
- 5 mo: 382
    
- 6 mo: 400
    
- 7 mo: 405
    
- 8 mo: 410
    
- 9 mo: 410
    
- 10 mo: 410
    
- 11 mo: 408
    
- 12 mo: 405
    

3.  **GC communication buckets and ranges (g/day):**

- **< 5 months** (covers 2.0–4.999… mo): **950–1350**
    
- **5–6 months** (covers 5.0–6.999… mo): **1250–1550**
    
- **7–12 months** (covers 7.0–12.0 mo): **1300–1500**
    

**Boundary rule:** exact 5.0 and 7.0 belong to the **later** bucket (5.0 → “5–6”, 7.0 → “7–12”).

* * *

## 4) How to calculate results (conceptual, no code)

### A) Kibble grams/day at any age (2.0–12.0)

- Use **linear interpolation** between the nearest kibble reference points listed above.
    
- Round the resulting kibble grams/day to **whole grams** (or to the nearest **5 g** if the user enables a rounding toggle).
    

### B) GC bucket assignment

- Based on the **age**, assign the corresponding GC bucket and attach that bucket’s **low/high range** (g/day).

### C) Energy-matched GC grams/day (the backbone)

- Convert kibble grams/day to **kcal/day** using the **user-provided** kibble energy density (kcal/100 g).
    
- Convert kcal/day to **GC grams/day** using GC’s energy density **115 kcal per 100 g**.  
    (Equivalently, GC provides **1.15 kcal per gram**.)
    
- Round to **whole grams** (or to **nearest 5 g** if the user toggled it).
    

### D) Range status

- Compare the **energy-matched GC grams/day** to the GC bucket’s **low/high**:
    
    - “within” if inside \[low, high\]
        
    - “below” if under the low
        
    - “above” if over the high  
        (Do **not** alter the energy-matched amount; just flag it.)
        

### E) Transition schedule (blended days)

- Default to **7 days** (configurable).
    
- Linearly ramp daily fractions from **100% kibble / 0% GC** on Day 1 to **0% kibble / 100% GC** on the last day, in equal steps.
    
- Each day’s grams = (kibble grams/day × kibble fraction) + (GC grams/day × GC fraction).  
    Round after multiplying (whole grams or nearest 5 g per the user setting).
    

* * *

## 5) What to display (UX rules)

1.  **Primary number:** “Gently cooked (energy-matched): **X g/day**”.  
    Directly below, show the GC bucket label and its range (e.g., “7–12 months: 1300–1500 g/day”) plus a small **status chip** (within/below/above).
    
2.  **Context line:** “Based on your kibble energy density: **Y kcal / 100 g**” with an edit control.
    
3.  **Age input:** accept decimals (e.g., 5.5 months).  
    Add tick marks at 2, 3, 4, 6, 8, 10, 12 (the original kibble points).
    
4.  **Transition widget:** a simple 5–7 day table or bar chart that shows **kibble g** and **GC g** per day, plus the day total.  
    (Totals will typically increase during the transition because GC is less energy-dense; this is expected.)
    
5.  **Rounding toggle:** whole grams vs nearest 5 g.
    
6.  **Download/export:** CSV with columns:  
    age_months, kibble_g_per_day, kibble_kcal_per_100g, kcal_per_day, gc_energy_matched_g_per_day, gc_bucket_name, gc_low_g, gc_high_g, range_status, and per-day transition grams.
    

* * *

## 6) Validation & edge cases

- **Missing kibble kcal density:** block calculation and display a clear prompt to enter kcal/100 g.
    
- **Age outside 2–12 months:** clamp to the nearest bound; show a subtle informational note.
    
- **Energy-matched GC outside bucket range:** keep the energy-matched number; display the status chip and a short educational tooltip (growth varies; this tool prioritizes energy continuity).
    
- **Rounding:** perform all math in floating point; **round only for display** (and for the per-day plan after multiplying by fractions).
    

* * *

## 7) Acceptance checks (use these to verify)

- At **5.5 months** with **380 kcal/100 g** kibble:
    
    - Interpolated kibble ≈ **391 g/day**.
        
    - Kcal/day ≈ **1,486 kcal**.
        
    - Energy-matched GC ≈ **1,292 g/day**.
        
    - GC bucket “5–6 months” (1,250–1,550) → **within**.
        
- At **8.0 months** with **380 kcal/100 g** kibble:
    
    - Kibble ≈ **410 g/day** → ≈ **1,558 kcal/day** → GC ≈ **1,355 g/day**.
        
    - GC bucket “7–12 months” (1,300–1,500) → **within**.
        
- At **2.0 months** with **380 kcal/100 g** kibble:
    
    - Kibble **250 g/day** → **950 kcal/day** → GC **≈ 826 g/day**.
        
    - GC bucket “<5 months” (950–1,350) → **below** (expected for some formulas).
        

* * *

## 8) Deliverables checklist

- Precise monthly interpolation (ready values above).
    
- Age-aware GC bucket labelling and ranges.
    
- Energy-matched GC grams/day with status flag.
    
- Configurable transition length; per-day blend table.
    
- Rounding control.