Milestone survey, mapping, and content distribution

1. Key findings

• The onboarding survey is age-filtered but not adaptive. Answers do not add, remove, or change later questions.
• The current screen uses every active corpus rung. A separate 8-Physical/5-other helper exists, but the rendered section path bypasses those limits.
• The questionnaire does not deduplicate staged rungs by skill. At one month, for example, it shows 34 distinct questions drawn from only 9 skill labels.
• No answer is required. “Blank = not sure” means leaving a question untouched; the onboarding buttons do not clear a previous answer.
• The four survey areas become five Portrait spokes because Physical is split by motorType into Gross Motor and Fine Motor.
• Milestone answers affect the Portrait star and bundled activity ordering. The Portrait “Next skills” list itself comes from the backend read model.
• Milestone writes are inconsistent across surfaces: the Portrait domain sheet persists fully; “Mark achieved” skips the local journal; Home Updates only changes a draft and can complete its queue item without writing the milestone API.

2. Milestone content model

3. How the onboarding questionnaire is selected

flowchart TD
  DOB[Birth date] --> AGE[Integer age in months]
  CORPUS[810 bundled milestone rungs] --> LOGIC[For each row: estimated band if present, otherwise usuallyAchievedAt]
  AGE --> FILTER[Keep rows where minMonths ≤ age ≤ maxMonths]
  LOGIC --> FILTER
  FILTER --> FIVE{Selected rows touch the 59–70 or 71–73 reference bands and exceed 25?}
  FIVE -- No --> POOL[Keep the full current-age pool]
  FIVE -- Yes --> BALANCE[Round-robin across the four areas to 25]
  POOL --> AREA[Split into four area screens]
  BALANCE --> AREA
  AREA --> QUESTION[Convert questionText to caregiver prompt]
  QUESTION --> UI[Yes / Not yet / untouched blank]
    

Exact selection rules

1. Age is calculated as an integer month count from the profile birth date.
2. Every parseable corpus row is converted to an assessment row.
3. The logic band is ageBandEstimate.estimatedAgeBand ?? usuallyAchievedAt.
4. A row is selected only when the child's month is inside that band, inclusive. The normal pool does not add earlier or later “nearby” rows.
5. Only the 59–73 month reference ranges have a question cap. When the pool exceeds 25, rows are taken round-robin in area order: Physical, Cognitive, Linguistic, Social Emotional.
6. The selected pool is split into four screens. Within the pool, sorting favors current-band midpoint proximity, area order, age, skill, then text.
7. All four screens can be advanced with zero answers.

4. Answer lifecycle

flowchart TD
  subgraph Onboarding
    OUI[Yes / Not yet / blank] --> STATE[React answers map keyed by corpus id]
    STATE --> MAP[yes→yes; not_yet→not_yet; not_sure→dont_know; unanswered omitted]
    MAP --> REG[Register request with onboarding payload or POST /v1/onboarding]
  end
  subgraph Server_hydration[Sign-in and child switch]
    GET[GET child milestones] --> STATUS[achieved→yes; not_started/regressed→not_yet; other statuses ignored]
    STATUS --> MATCH[Map server UUID/code/text to corpus id where possible]
    MATCH --> STATE
    STATUS --> REMOTE[Remote checks with server domain and age bounds]
  end
  subgraph Profile_edit[Portrait domain sheet]
    DRAFT[Draft answer] --> SAVE[Save]
    SAVE --> STATE
    SAVE --> JOURNAL[Append local timestamped journal]
    SAVE --> WRITE{Blank?}
    WRITE -- Yes --> DELETE[DELETE by corpus code]
    WRITE -- No --> PUT[PUT achieved or not_started by corpus code]
    PUT --> REFRESH[Refresh Portrait and milestone hydration]
    DELETE --> REFRESH
  end
    

Answer/status mapping

Persistence by entry point

5. Corpus, server, and domain mapping

flowchart LR
  C[Corpus milestone id/code] --> A[answers corpus-key entry]
  S[Server milestone UUID] --> B[answers UUID entry]
  S --> M{code matches corpus id?}
  M -- Yes --> A
  M -- No --> T{normalized caregiver prompt or title exactly matches corpus text/title?}
  T -- Yes --> A
  T -- No --> R[Keep only UUID answer and remote star check]
  AREA[Server area_code + motor_type] --> DOMAIN[Five-domain mapping]
  DOMAIN --> STAR[Portrait star]
    

On hydration, the app first stores the server UUID answer. It then tries to find the bundled row by server code, followed by exact normalized prompt/title matching. A failed corpus match still contributes to the star through a remote check if the server supplied domain and age bounds, but bundled checklists will not share that answer key.

6. Where milestone data is used

Portrait star formula

currentFill = currentYes / currentTotal
behind     = previousNotYet / previousTotal
progress   = clamp(currentFill - 0.25 × behind, 0, 1)

beyondProgress = min(1, futureYes / 5)
visual current spoke = 0.25 + 0.75 × progress

• Current: the child's month is inside the milestone's logic band.
• Previous: the band ended within the prior three months.
• Future: every later band can contribute once marked yes; five yes answers fill the outer “beyond” effect.
• A domain with no current rows gets currentFill = 1, although maxed remains false because its denominator is zero.

Bundled activity ranking formula

answer weight: yes = 0; not_yet = 1; blank/not_sure = 0.6

domainNeed = 2 × mean(current-band answer weights)
           + 1 × mean(next-three-month answer weights)

Activities are sorted by their domain's need score; ties preserve source order. The average is used so a domain with more milestone rows does not win merely because its corpus is denser.

7. Overall content distribution

Four survey areas

Five Portrait domains

Rows by logic-band starting window

Each corpus row is counted once, according to the start month of the logic band used by the app.

Content is concentrated at both ends: 19.5% of all rows start in the first year, while 43.0% start at 59–73 months. The middle 36–58 month range contains only 74 rows (9.1%).

Reliability/levelling flags by area

8. Questionnaire distribution by child age

These counts reproduce the implemented pool, including overlapping age bands and the 25-question five-plus cap.

Repeated skill ladders inside the survey

These are not duplicate question strings; they are distinct stage questions under the same skill label. The section-building path does not run the engine's skill-level deduplication helper.

9. Content-quality metadata in the active corpus

• All 810 rows have top-level contentStatus: generated_needs_vetting.
• All seven per-field review flags—title, age band, question text, why we ask, what counts, example, and examples—are marked vetted on all 810 rows.
• 284 rows have estimated logic bands. Confidence ranges from 65 to 75, average 66.2; none reaches the public-display threshold of 80.
• The corpus itself warns that the 59–70 and 71–73 month ranges contain most known defects and should be treated as unordered/reference rather than levelling signal.
• Despite those flags, the runtime selection functions include the rows. The special behavior is a 25-question balanced cap, not exclusion.

10. What the current logic means

11. Code map