docs(product): weekly review reframe spec 추가

2026-03-14 19:13:35 +09:00
parent 74e44fff69
commit 679601d201
3 changed files with 643 additions and 9 deletions
--- a/docs/12_core_loop_execution_roadmap.md
+++ b/docs/12_core_loop_execution_roadmap.md
@@ -174,7 +174,12 @@ VibeRoom은 아래 방식으로 진행한다.
 상태:
- 아직 본격 기획 전
+- 상세 기획 문서 작성 완료
 - 구현 전
 문서:
 - `14_weekly_review_reframe_spec.md`
 ### Phase 6. Premium Ambience System
--- a/docs/14_weekly_review_reframe_spec.md
+++ b/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`보다 더 시끄러운 화면으로 만드는 것
--- a/docs/work.md
+++ b/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 정의
+  - weekly-review API shape 설계
-  - free / pro review 가치 구분
+  - 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