Alo/phaseflow
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document spec gaps: auth, phase scaling, observability, testing

Browse Source 
Address 21 previously undefined behaviors across specs:

- Authentication: Replace email/password with OIDC (Pocket-ID)
- Cycle tracking: Add fixed-luteal phase scaling formula with examples
- Calendar: Document period logging behavior (preserve predictions)
- Garmin: Clarify connection is required (no phase-only mode)
- Dashboard: Add UI states, dark mode, onboarding, accessibility
- Notifications: Document timezone batching approach
- New specs: observability.md (health, metrics, logging)
- New specs: testing.md (unit + integration strategy)
- Main spec: Add backup/recovery, known limitations, API updates

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Petru
2026-01-11 07:49:56 +00:00
parent 97a424e41d
commit 6a8d55c0b9
9 changed files with 596 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
specs/cycle-tracking.md
View File

@@ -19,15 +19,29 @@ Default cycle length: 31 days (configurable per user).
### Cycle Phases
Based on a 31-day cycle:
Phase boundaries scale based on cycle length using a **fixed luteal, variable follicular** approach. The luteal phase (14 days) is biologically consistent; the follicular phase expands or contracts with cycle length.
**Phase Calculation Formula:**
Given `cycleLength` (user-configurable, default 31):
| Phase | Days | Weekly Limit | Training Type |
|-------|------|--------------|---------------|
| MENSTRUAL | 1-3 | 30 min | Gentle rebounding only |
| FOLLICULAR | 4-14 | 120 min | Strength + rebounding |
| OVULATION | 15-16 | 80 min | Peak performance |
| EARLY_LUTEAL | 17-24 | 100 min | Moderate training |
| LATE_LUTEAL | 25-31 | 50 min | Gentle rebounding ONLY |
| FOLLICULAR | 4 to (cycleLength - 16) | 120 min | Strength + rebounding |
| OVULATION | (cycleLength - 15) to (cycleLength - 14) | 80 min | Peak performance |
| EARLY_LUTEAL | (cycleLength - 13) to (cycleLength - 7) | 100 min | Moderate training |
| LATE_LUTEAL | (cycleLength - 6) to cycleLength | 50 min | Gentle rebounding ONLY |
**Examples by Cycle Length:**
| Phase | 28-day | 31-day | 35-day |
|-------|--------|--------|--------|
| MENSTRUAL | 1-3 | 1-3 | 1-3 |
| FOLLICULAR | 4-12 | 4-15 | 4-19 |
| OVULATION | 13-14 | 16-17 | 20-21 |
| EARLY_LUTEAL | 15-21 | 18-24 | 22-28 |
| LATE_LUTEAL | 22-28 | 25-31 | 29-35 |
## API Endpoints
@@ -101,7 +115,18 @@ interface PeriodLog {
Users with irregular cycles can adjust:
- Default: 31 days
- Range: 21-45 days
- Affects phase day boundaries proportionally
- Affects phase day boundaries per formula above
## Known Limitations
The following scenarios are **out of scope** for MVP:
- **Pregnancy** - Cycle tracking pauses; app not designed for pregnancy
- **Menopause** - Irregular/absent cycles not supported
- **Hormonal birth control** - May suppress or alter natural cycle phases
- **Anovulatory cycles** - App assumes ovulation occurs; no detection for skipped ovulation
Users in these situations should consult healthcare providers for personalized guidance.
## Success Criteria
@@ -115,6 +140,8 @@ Users with irregular cycles can adjust:
- [ ] `getCycleDay` returns 1 on period start date
- [ ] `getCycleDay` handles cycle rollover correctly
- [ ] `getPhase` returns correct phase for each day range
- [ ] `getPhase` scales correctly for 28-day cycle
- [ ] `getPhase` scales correctly for 35-day cycle
- [ ] POST `/api/cycle/period` updates user record
- [ ] GET `/api/cycle/current` returns accurate phase info
- [ ] Days beyond cycle length default to LATE_LUTEAL