docs(product): weekly review reframe spec 추가

docs/12_core_loop_execution_roadmap.md

@@ -174,7 +174,12 @@ VibeRoom은 아래 방식으로 진행한다.
 
 상태:
 
-- 아직 본격 기획 전
+- 상세 기획 문서 작성 완료
+- 구현 전
+
+문서:
+
+- `14_weekly_review_reframe_spec.md`
 
 ### Phase 6. Premium Ambience System
 

docs/14_weekly_review_reframe_spec.md

@@ -0,0 +1,626 @@
+# 14. Weekly Review Reframe Spec
+
+Last Updated: 2026-03-14
+
+이 문서는 VibeRoom의 `Weekly Review`를 단순 통계 화면이 아니라
+**다음 세션의 성공률을 높이는 행동 시스템**으로 재정의하는 상세 기획 문서다.
+
+관련 문서:
+
+- `09_app_entry_detailed_spec.md`
+- `10_refocus_system_spec.md`
+- `11_away_return_recovery_spec.md`
+- `12_core_loop_execution_roadmap.md`
+- `13_space_intent_card_collapsed_expanded_spec.md`
+- `../../product_principles.md`
+- `../../current_context.md`
+
+---
+
+## 1. 문제 정의
+
+현재 `/stats`는 factual summary 중심으로 정리되어 있다.
+
+좋은 점:
+
+- 과한 해석을 줄였다
+- mock insight와 가짜 코칭을 제거했다
+- started / completed / carried over / focus minutes 같은 실제 수치만 남겼다
+
+부족한 점:
+
+- 사용자가 `그래서 다음 주에 뭘 바꾸면 되는지`를 알 수 없다
+- 총 시간은 보여주지만 `왜 잘 되었는지 / 왜 무너졌는지`는 행동 수준에서 연결되지 않는다
+- Pro 가치가 `review`라는 이름에 비해 아직 약하다
+- 현재 구조는 여전히 `summary dashboard`에 가깝고, `behavior change surface`로는 약하다
+
+핵심 문제는 이거다.
+
+> 지금의 `/stats`는 지난 시간을 보여주지만, 다음 집중의 성공률을 높이지는 못한다.
+
+---
+
+## 2. 한 줄 정의
+
+> Weekly Review는 지난 7일의 집중 기록을 예쁘게 보여주는 화면이 아니라, 다음 주의 첫 세션을 더 잘 시작하게 만드는 주간 정리 ritual이다.
+
+---
+
+## 3. 제품 목표
+
+Weekly Review가 해야 할 일은 4개뿐이다.
+
+1. 내가 `시작`을 잘하는 조건을 보여준다
+2. 내가 `흔들린 뒤 복귀`를 잘하는 조건을 보여준다
+3. 내가 `완료`까지 가는 패턴을 보여준다
+4. 다음 주에 바꿀 것을 1~2개만 남긴다
+
+하지 말아야 할 일도 분명하다.
+
+- 예쁜 그래프 전시장 되기
+- 생산성 점수 놀이
+- 성격 분석처럼 보이는 과한 해석
+- planner / habit tracker / life dashboard로 확장
+
+---
+
+## 4. 시장 신호와 포지셔닝
+
+2026-03-14 기준 공식 포지셔닝을 보면:
+
+- [LifeAt pricing](https://lifeat.io/pricing)는 `daily planner`, `multiple calendars`, `unlimited todos and notes`, `advanced analytics`를 함께 판다.
+- [Focusmate pricing](https://www.focusmate.com/pricing/)는 무료 주 3회, 유료 무제한으로 `accountability access`를 판다.
+- [Portal](https://portal.app/)은 `immersive spatial audio`와 감각 품질을 전면에 둔다.
+- [Endel ADHD](https://endel.io/adhd)는 `Focus Timer`, `Task Headline`, `App Blocker`, active exercises를 ADHD 친화적 도구로 묶는다.
+- [Brain.fm pricing](https://www.brain.fm/pricing)는 `science-backed music` 자체를 프리미엄 가치로 판다.
+
+VibeRoom의 Weekly Review는 LifeAt처럼 planner analytics로 가면 안 된다.
+또 Focusmate처럼 외부 accountability를 핵심으로 가도 안 된다.
+
+VibeRoom의 review는 아래처럼 포지셔닝해야 한다.
+
+- planner review가 아니다
+- performance dashboard도 아니다
+- `내가 어떤 조건에서 실제로 시작하고 복귀하는지`를 보여주는 focus quality review다
+
+즉, review는 Pro에서 이렇게 팔아야 한다.
+
+> 더 많은 일을 관리하는 리뷰가 아니라, 덜 흔들리고 더 빨리 다시 시작하게 해주는 리뷰
+
+---
+
+## 5. 사용자 정의
+
+### Primary User
+
+- ADHD 성향이 있거나 시작 마찰이 큰 프리랜서
+- 해야 할 일은 알지만 시작과 복귀가 어렵다
+- 감각 환경이 집중 품질에 영향을 준다
+- 통계는 싫지 않지만, 너무 많은 정보는 오히려 회피를 만든다
+
+### Weekly Review에서의 실제 질문
+
+- 나는 언제 시작이 잘 되었지?
+- 어떤 배경/사운드/길이에서 덜 무너졌지?
+- pause 후에 잘 돌아온 편인가?
+- 다음 주에는 뭘 하나만 바꾸면 될까?
+
+---
+
+## 6. Weekly Review 경험 원칙
+
+### 1. Review는 지난 주를 닫고 다음 주를 여는 ritual이어야 한다
+
+- 회고는 회고로 끝나면 안 된다
+- 반드시 다음 주의 첫 세션과 연결되어야 한다
+
+### 2. 총 시간보다 행동 전환을 우선한다
+
+- focus minutes는 보조 지표다
+- 핵심은 `start`, `recovery`, `completion`
+
+### 3. 모든 해석은 근거가 있는 factual summary여야 한다
+
+- “당신은 밤형 인간입니다” 같은 해석 금지
+- “최근 7일 중 오전 9시~12시 시작 세션의 완료율이 가장 높았어요”처럼
+  raw metric에 직접 연결되는 문장만 허용
+
+### 4. 한 화면에서 바꾸는 제안은 최대 2개만
+
+- insight가 많아 보이는 것은 premium이 아니다
+- `다음 주엔 이 두 가지만 바꿔보자`가 더 premium하다
+
+### 5. Review는 planner가 아니라 focus optimizer여야 한다
+
+- todo completion analytics 금지
+- calendar productivity reporting 금지
+- session quality와 ritual fit만 본다
+
+### 6. Free도 충분히 가치 있어야 하고, Pro는 더 깊어야 한다
+
+- Free는 `기본적인 self-awareness`
+- Pro는 `행동 변화에 쓸 수 있는 pattern visibility`
+
+---
+
+## 7. 정보 구조
+
+Weekly Review는 `/stats` 안에서 아래 5개 구역으로 재구성한다.
+
+### Section A. Weekly Snapshot
+
+목적:
+
+- 이번 주를 한눈에 닫아주는 첫 문장
+
+구성:
+
+- title: `이번 주 집중 리듬`
+- subline: `시작 9회 · 복귀 5회 · 완료 4회`
+- short summary 1줄
+
+예시:
+
+- `이번 주에는 시작은 자주 했고, pause 뒤 복귀는 절반 정도 이어졌어요.`
+- `짧은 세션보다 45분 이상 세션에서 완료율이 더 높았어요.`
+
+규칙:
+
+- summary는 1줄만
+- 과장 금지
+- 반드시 실제 수치에서 바로 읽히는 문장만 허용
+
+### Section B. Start Quality
+
+목적:
+
+- 사용자가 `들어가는 힘`을 얼마나 잘 만들었는지 보여준다
+
+노출 지표:
+
+- started sessions
+- start days
+- first start consistency
+- planned start vs ad-hoc start ratio
+
+핵심 질문:
+
+- 이번 주에 시작 자체를 자주 했는가?
+- 특정 요일/시간대에서 시작이 잘 되었는가?
+
+추천 카드:
+
+- `시작 횟수`
+- `가장 잘 시작된 시간대`
+- `첫 세션 평균 시작 시각`
+
+### Section C. Recovery Quality
+
+목적:
+
+- pause / away 이후 얼마나 다시 올라탔는지 보여준다
+
+노출 지표:
+
+- paused sessions
+- returned after pause
+- returned after away
+- recovery rate
+- avg time to recovery
+
+핵심 질문:
+
+- 흔들린 뒤에도 다시 돌아왔는가?
+- pause와 away 중 어디서 더 많이 끊겼는가?
+
+추천 카드:
+
+- `복귀율`
+- `pause 뒤 복귀`
+- `자리 비움 뒤 복귀`
+
+### Section D. Completion Quality
+
+목적:
+
+- 끝까지 간 세션과 goal closure를 보여준다
+
+노출 지표:
+
+- completed sessions
+- completed goals
+- break started after completion
+- carry-over count
+
+핵심 질문:
+
+- 마무리까지 가는 흐름이 있었는가?
+- 목표를 닫지 못하고 다음 날로 밀린 경우가 많았는가?
+
+추천 카드:
+
+- `완료한 블록`
+- `끝까지 간 세션 비율`
+- `이월된 블록`
+
+### Section E. Ritual Fit
+
+목적:
+
+- 어떤 scene / sound / timer 조합이 더 잘 맞는지 보여준다
+
+노출 원칙:
+
+- Free는 단일 best-fit hint 1개만
+- Pro는 ritual 비교까지 허용
+
+예시:
+
+- `Forest · 50/10에서 가장 오래 이어졌어요.`
+- `Rain 계열에서는 pause 후 복귀가 더 높았어요.`
+
+중요:
+
+- 이것도 “추천”이지 “정답 판정”이 아니다
+- 적은 샘플 수에서는 확정적 문장 금지
+
+### Section F. Next Week Carry Forward
+
+목적:
+
+- review를 다음 세션 행동으로 연결
+
+구성:
+
+- `다음 주에 유지할 것`
+- `다음 주에 바꿔볼 것`
+- CTA: `이 ritual로 다음 세션 시작`
+
+이 섹션이 없으면 review는 예쁜 요약으로 끝난다.
+
+---
+
+## 8. 핵심 지표 정의
+
+### Base Metrics
+
+- `startedSessions`
+- `completedSessions`
+- `completedGoals`
+- `pausedSessions`
+- `returnedAfterPause`
+- `awayCandidates`
+- `returnedAfterAway`
+- `focusMinutes`
+- `breakSessions`
+- `carriedOverCount`
+
+### Derived Metrics
+
+- `startSuccessRate`
+  - started days / active days
+- `completionRate`
+  - completed sessions / started sessions
+- `pauseRecoveryRate`
+  - returned after pause / paused sessions
+- `awayRecoveryRate`
+  - returned after away / away candidates
+- `carryOverRate`
+  - carried over goals / created goals
+- `ritualFitScore`
+  - completion + recovery + avg session depth를 조합한 비교용 내부 점수
+
+중요:
+
+- `ritualFitScore`는 내부 계산용이다
+- 사용자에게 raw score를 그대로 보여주지 않는다
+- 사용자에게는 `이번 주 가장 잘 맞은 조합`처럼 문장으로만 보여준다
+
+---
+
+## 9. 허용되는 해석과 금지되는 해석
+
+### 허용
+
+- `최근 7일 중 오전 시작 세션의 완료율이 가장 높았어요.`
+- `25분보다 50분 세션에서 복귀율이 높았어요.`
+- `Forest + Birds에서 pause 뒤 복귀가 가장 높았어요.`
+
+### 금지
+
+- `당신은 밤형 인간이에요.`
+- `의지가 부족했어요.`
+- `이번 주 생산성이 낮았어요.`
+- `당신은 긴 세션에 맞지 않아요.`
+
+원칙:
+
+- 행동 데이터 -> 짧은 문장
+- 심리 진단 -> 금지
+
+---
+
+## 10. UI/UX 방향
+
+### 전체 톤
+
+- stats dashboard가 아니라 calm review desk
+- 라이트 팔레트는 유지하되, 문서성과 감정적 안정감이 있어야 한다
+- 차트는 줄이고, 문장과 비교를 늘린다
+
+### 시각 원칙
+
+- 큰 숫자 카드 남발 금지
+- 한 줄 summary와 2~3개 핵심 비교를 우선
+- “이번 주 / 시작 / 복귀 / 완료 / 다음 주” 순서로 읽히게 한다
+- 회고가 무거운 분석처럼 보이면 안 된다
+
+### 좋은 흐름
+
+1. 이번 주 한 줄 요약
+2. 시작은 어땠나
+3. 흔들린 뒤 돌아왔나
+4. 끝까지 갔나
+5. 다음 주엔 뭘 유지/변경할까
+
+### 나쁜 흐름
+
+1. 카드 12개
+2. 차트 4개
+3. 해석 7개
+4. 추천 9개
+
+이건 LifeAt식 dashboard로 읽히고, VibeRoom과 맞지 않는다.
+
+---
+
+## 11. Free / Pro 재정의
+
+### Free Weekly Review
+
+Free는 다음만 보여준다.
+
+- 이번 주 snapshot 1개
+- Start Quality 핵심 카드 1~2개
+- Recovery Quality 핵심 카드 1개
+- Completion Quality 핵심 카드 1개
+- Next Week Carry Forward 한 줄 제안 1개
+
+Free에서 하지 않는 것:
+
+- multi-week trend
+- ritual 비교표
+- scene/sound/timer 조합 비교
+- archive 기반 long-term pattern
+
+Free 가치:
+
+- `내가 이번 주에 어떻게 집중했는지`를 짧게 이해
+- 다음 세션에 바로 적용할 한 줄 얻기
+
+### Pro Weekly Review
+
+Pro는 아래까지 연다.
+
+- 4주 trend
+- ritual fit comparison
+- start window pattern
+- recovery pattern split
+  - pause recovery
+  - away recovery
+- best ritual recommendation
+- carry-forward note history
+- direct CTA
+  - `이 ritual로 다음 세션 시작`
+  - `이번 주 가장 잘 맞은 조합으로 시작`
+
+Pro 가치:
+
+- 더 깊은 분석이 아니라
+- `내가 어떤 조건에서 덜 무너지는지`를 실제로 알게 한다
+
+### BM 원칙
+
+Review는 Pro에서 이렇게 팔아야 한다.
+
+- “고급 통계”
+- “생산성 분석”
+
+가 아니라
+
+- `내 집중 리듬을 더 잘 이해하게 해주는 weekly review`
+- `다음 주의 시작 성공률을 높여주는 personalized reflection`
+
+---
+
+## 12. 사용자 플로우
+
+### Flow A. 주간 진입
+
+trigger:
+
+- `/stats` 직접 진입
+- `/app` teaser 클릭
+- 주말/주간 종료 시점의 passive prompt
+
+flow:
+
+1. snapshot hero
+2. start / recovery / completion
+3. ritual fit
+4. next week carry forward
+5. next CTA
+
+### Flow B. 세션 직후 light review teaser
+
+trigger:
+
+- 금주 4번째 completed session
+- 또는 금주 1번째 return after pause
+
+teaser 예시:
+
+- `이번 주 pause 뒤 복귀가 3번 있었어요`
+- `Forest 50/10에서 가장 잘 이어졌어요`
+
+CTA:
+
+- `주간 review 보기`
+
+### Flow C. 다음 세션 연결
+
+weekly review 마지막 CTA:
+
+- `이 조합으로 다음 세션 시작`
+- `/app`으로 연결하되 ritual preset을 prefill
+
+즉 review는 읽고 끝나는 화면이 아니라 다음 entry에 연결돼야 한다.
+
+---
+
+## 13. 정보 설계와 컴포넌트 구조 제안
+
+### `/stats` 1-screen IA
+
+1. Header
+2. Weekly Snapshot hero
+3. Start Quality
+4. Recovery Quality
+5. Completion Quality
+6. Ritual Fit
+7. Next Week Carry Forward
+
+### 프론트 컴포넌트 제안
+
+- `WeeklyReviewHero`
+- `ReviewMetricPair`
+- `RecoverySplitCard`
+- `RitualFitHighlight`
+- `CarryForwardPanel`
+
+현재의 작은 stat card 반복을 그대로 늘리는 방향은 피한다.
+
+---
+
+## 14. API / 데이터 계약 제안
+
+### 새 응답 모델
+
+`GET /api/v1/stats/weekly-review`
+
+response shape:
+
+- `weekRange`
+- `snapshot`
+- `startQuality`
+- `recoveryQuality`
+- `completionQuality`
+- `ritualFit`
+- `carryForward`
+- `source`
+
+### snapshot
+
+- `startedSessions`
+- `returnedSessions`
+- `completedGoals`
+- `focusMinutes`
+- `summaryLine`
+
+### startQuality
+
+- `startedSessions`
+- `activeDays`
+- `bestStartWindow`
+- `adHocVsPlanned`
+
+### recoveryQuality
+
+- `pausedSessions`
+- `returnedAfterPause`
+- `awayCandidates`
+- `returnedAfterAway`
+- `recoveryRate`
+
+### completionQuality
+
+- `completedSessions`
+- `completedGoals`
+- `carriedOverCount`
+- `completionRate`
+
+### ritualFit
+
+- `topScene`
+- `topSound`
+- `topTimerPreset`
+- `topComboSummary`
+- `confidence`
+
+### carryForward
+
+- `keepDoing`
+- `tryNext`
+- `recommendedEntryPreset`
+
+### write endpoint
+
+선택 기능:
+
+`POST /api/v1/stats/weekly-review/carry-forward`
+
+용도:
+
+- 다음 주 유지/변경 메모 저장
+
+초기 v1에서는 read-only로 시작해도 된다.
+
+---
+
+## 15. 구현 순서
+
+### Slice 1. 데이터 모델 재정의
+
+- weekly-review 응답 계약 설계
+- mock + API 양쪽 shape 통일
+
+### Slice 2. `/stats` IA 재구성
+
+- factual summary card 반복을 해체
+- hero + 4 quality sections + carry-forward로 재배치
+
+### Slice 3. copy / interpretation system
+
+- 허용되는 summary line 규칙 정리
+- 과한 해석 제거
+
+### Slice 4. Free / Pro gating
+
+- Free는 7일 snapshot 중심
+- Pro는 4주 trend / ritual fit 확장
+
+### Slice 5. `/app` 연결
+
+- review teaser
+- next-session start CTA 연결
+
+---
+
+## 16. 완료 기준
+
+- `/stats`가 더 이상 generic dashboard처럼 보이지 않는다
+- 사용자가 review를 보고 `다음 주엔 이걸 바꿔봐야겠다`를 얻는다
+- review가 다음 세션 entry와 연결된다
+- Free에서도 충분한 가치가 있고, Pro는 확실히 더 깊다
+- Pro 가치가 `더 많은 분석`이 아니라 `더 잘 시작하고 덜 무너지는 자기 이해`로 읽힌다
+
+---
+
+## 17. 절대 피해야 할 방향
+
+- planner analytics로 확장
+- task completion dashboard화
+- 생산성 점수화
+- 심리 진단처럼 보이는 카피
+- 차트와 카드 수를 premium으로 오해하는 것
+- review를 `/space`보다 더 시끄러운 화면으로 만드는 것

docs/work.md

@@ -91,18 +91,21 @@
 
 ## 작업 4
 
-- 제목: `Weekly Review` 상세 기획
+- 제목: `Weekly Review Reframe` 구현 준비
 - 목적:
-  - total time 중심이 아니라 행동 변화 중심의 review를 설계한다.
+  - `14_weekly_review_reframe_spec.md` 기준으로 `/stats`를 행동 변화 중심 review surface로 옮기기 위한 첫 구현 slice를 연다.
 - 변경 범위:
-  - started / resumed / completed / recovery rate / ritual fit 정의
-  - free / pro review 가치 구분
+  - weekly-review API shape 설계
+  - mock summary 구조 재정의
+  - `/stats` IA 재배치 초안
 - 제외 범위:
   - planner/dashboard 확장 금지
-  - 해석 과잉 카피 금지
+  - 과한 해석형 카피 금지
+  - Premium Ambience 작업 선행 금지
 - 완료 조건:
-  - review가 다음 세션 성공률을 높이는 역할로 정의된다.
+  - `/stats`가 더 이상 단순 factual card 반복이 아니라 snapshot + start/recovery/completion 구조로 전환되기 시작한다.
 - 검증:
-  - 기획 문서 작성
+  - 상세 spec과 구현 초안 일치
+  - 브라우저 구조 확인
 - 커밋 힌트:
-  - docs(product): weekly-review-spec
+  - feat(stats): weekly-review-snapshot