AI Principles
How Peri's intelligence behaves
Ten principles that govern every engine, every card, and every sentence. Intelligence in Peri emerges from five domain engines reading one shared record — these principles are what make the result feel like one trustworthy mind.
Why principles, not features
01
Interpretation First
Why this exists
A score without meaning transfers the analytic burden to the user — the opposite of intelligence. Peri's user is a capable adult managing a noisy biological transition; she needs a conclusion she can act on in three seconds, with the evidence available underneath.
How it's implemented
Every engine returns a recommendation title and explanation alongside its scores. Card faces render the title; numbers render as evidence (the capacity bar) — never as the headline.
Before — generic wellness app
Recovery Score: 62. HRV: −12ms. Sleep debt: 1.8h. Strain: 71.
After — Peri
Train lighter — recovery strain is elevated after two hard sessions on short sleep.
02
Pattern versus Insight
Why this exists
Treating every correlation as wisdom destroys trust the first time a spurious one surfaces. Separating what the system noticed from what it knows lets users watch knowledge form — which is itself trust-building.
How it's implemented
Patterns require ≥3 observations at ≥60% rate to surface; only medium/high-confidence patterns (5+ observations) count as insights. The stats row reports both numbers honestly.
Before — generic wellness app
Insight: yoga improves your sleep! (observed twice)
After — Peri
Pattern (low confidence): yoga days are often followed by better sleep — seen 3 of 5 times. Logged more, this may become an insight.
03
Confidence Hedging
Why this exists
Perimenopause is defined by signal instability — cycles lengthen, vanish, return. A system that speaks with constant certainty over shifting data will be wrong loudly. Grammar that scales with evidence is the honest register.
How it's implemented
Three language levels keyed to pattern confidence: causal (high), observational (medium), hedged 'may be contributing' (low). Below data minimums, the system says it is learning.
Before — generic wellness app
Your luteal phase is causing low energy.
After — Peri
Low confidence: your cycle may be contributing to lower energy this week — two more cycles of data will sharpen this.
04
Provenance
Why this exists
“Trust me” is not a design strategy. Every conclusion that affects a training decision must show what fed it — and admit what didn't.
How it's implemented
Engines emit signalsUsed[] and missingInputs[]; cards render “based on…” lines from real output, never boilerplate.
Before — generic wellness app
We recommend resting today.
After — Peri
Recover first — based on: training load · sleep · symptoms. Not used: wearable (not connected).
05
Progressive Disclosure
Why this exists
Intelligence that explains itself all at once is noise. The four-layer ladder (face → detail → explain → act) lets a glance be a glance and an interrogation be an interrogation — same card, same gesture, everywhere.
How it's implemented
Structural, not stylistic: every intelligence card implements all four layers; no layer leaks upward.
Before — generic wellness app
A card showing recommendation + drivers + assumptions + confidence + sources simultaneously.
After — Peri
Face: “Train lighter” + capacity bar. Everything else one tap deeper, in priority order.
06
Explainability
Why this exists
The moment of surprise is the moment of learning. If “why?” is answered anywhere other than where the surprise happened, the answer arrives too late to build trust.
How it's implemented
Drivers, signals and assumptions render inside each card's own drawer. There is no global “How Peri works” surface standing in for contextual explanation.
Before — generic wellness app
See our Help Center to learn how recommendations are calculated.
After — Peri
Capacity ↓ 12 — mostly short sleep (5.1h), plus yesterday's HIIT. Cycle context unchanged.
07
Avoid False Precision
Why this exists
Decimal points imply measurement the system doesn't have. Estimates dressed as readings eventually get caught — and take the honest numbers down with them.
How it's implemented
Capacity reports in five named bands, not raw percentages on faces. Confidence is words, never percentages. Fueling needs are 1–3 dots, not grams.
Before — generic wellness app
Recovery: 62.4%. Confidence: 87%. Protein target: 1.6g/kg.
After — Peri
Recovery Capacity: Moderate. Protein: ●●● (raised — training load + short sleep).
08
Assumption to Action
Why this exists
Every gap the engine fills is a small lie until disclosed. Disclosing it with the button that fixes it turns the system's weakness into the user's fastest logging path.
How it's implemented
The red assumptions block lists actionable gaps only, each with a button that closes the sheet and opens the right log screen after 320ms.
Before — generic wellness app
Note: some data was estimated.
After — Peri
Assumed today: no sleep logged (assumed 6h) → [Log Sleep].
09
Trust Building
Why this exists
Trust in a health-adjacent AI is accrued in small honest moments and destroyed in one overreach. Peri's trust architecture: never punish missing data, never guess silently, never block, count knowledge honestly.
How it's implemented
Missing data reduces confidence rather than scores; assumptions are disclosed; errors degrade to local-save; the threshold ladder shows knowledge being earned; symptoms always outrank cycle optimism.
Before — generic wellness app
Streak broken! Log daily for accurate insights.
After — Peri
Learning your patterns — a few more days unlocks recovery estimates. (And the estimate arrives when promised.)
10
Human Tone
Why this exists
The user is an athlete in a hormonal transition that medicine routinely dismisses. The product's voice must be the opposite of both the cheerleading wellness app and the cold clinical chart: a knowledgeable, calm peer.
How it's implemented
Recommendation titles are permission-giving (“Rest guilt-free”), playbooks are framed as the user's own learning (“What has sleep taught me?”), and no exclamation marks, streaks, badges, or fire emoji exist anywhere.
Before — generic wellness app
Great job logging! 🔥 You're crushing your recovery goals!
After — Peri
Rest guilt-free — on days like this, your history says recovery now buys capacity later.
One mind, five engines
None of these principles lives in a single component. The daily focus, fueling, trends, what-next, and the four insight engines each apply the same contract — which is why six different cards built by different sessions still read as one intelligence. The forthcoming AI Architecture section maps how the engines compose.