From 445ef54528a164e50d5f26465ec34e361180c61c Mon Sep 17 00:00:00 2001
From: corpi <lj845854@gmail.com>
Date: Sat, 14 Mar 2026 19:27:46 +0900
Subject: [PATCH] =?UTF-8?q?docs(product):=20weekly=20review=20entry=20flow?=
 =?UTF-8?q?=20spec=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/12_core_loop_execution_roadmap.md |   1 +
 docs/15_app_stats_entry_flow_spec.md   | 437 +++++++++++++++++++++++++
 docs/work.md                           |  40 +--
 3 files changed, 458 insertions(+), 20 deletions(-)
 create mode 100644 docs/15_app_stats_entry_flow_spec.md

diff --git a/docs/12_core_loop_execution_roadmap.md b/docs/12_core_loop_execution_roadmap.md
index 22b44fe..9a9ef27 100644
--- a/docs/12_core_loop_execution_roadmap.md
+++ b/docs/12_core_loop_execution_roadmap.md
@@ -181,6 +181,7 @@ VibeRoom은 아래 방식으로 진행한다.
 문서:
 
 - `14_weekly_review_reframe_spec.md`
+- `15_app_stats_entry_flow_spec.md`
 
 ### Phase 6. Premium Ambience System
 
diff --git a/docs/15_app_stats_entry_flow_spec.md b/docs/15_app_stats_entry_flow_spec.md
new file mode 100644
index 0000000..5a4dc34
--- /dev/null
+++ b/docs/15_app_stats_entry_flow_spec.md
@@ -0,0 +1,437 @@
+# 15. `/app -> /stats -> /app` Weekly Review Entry Flow Spec
+
+Last Updated: 2026-03-14
+
+이 문서는 VibeRoom의 `Weekly Review`를 **어디서, 왜, 어떤 타이밍에 열어야 하는지**를 정의하는 진입 플로우 문서다.
+
+핵심 목적은 하나다.
+
+> `/stats`를 고립된 summary page가 아니라, `/app`의 다음 세션 시작 성공률을 높여주는 review ritual로 코어 루프 안에 넣는다.
+
+관련 문서:
+
+- `09_app_entry_detailed_spec.md`
+- `12_core_loop_execution_roadmap.md`
+- `14_weekly_review_reframe_spec.md`
+- `../../product_principles.md`
+- `../../current_context.md`
+
+---
+
+## 1. 문제 정의
+
+현재 구현 기준에서 `/stats`는 route는 존재하지만,
+제품 루프 안에서의 진입 이유가 약하다.
+
+현재 문제:
+
+- `/stats`는 사실상 고립된 페이지다
+- 사용자가 왜 지금 review를 봐야 하는지 맥락이 없다
+- `/space`에서 바로 review로 튀면 execution 흐름을 끊는다
+- `/app`과 `/stats`가 연결되지 않아, review가 다음 세션 시작으로 이어지지 않는다
+
+즉, 지금 `/stats`는 “있을 수는 있는 페이지”지만
+**사용자가 자연스럽게 보게 되는 페이지는 아니다.**
+
+---
+
+## 2. 한 줄 정의
+
+> Weekly Review의 primary flow는 `/app`에서 review teaser를 보고, `/stats`에서 지난 7일의 집중 리듬을 짧게 정리한 뒤, 다시 `/app`으로 돌아와 다음 세션을 시작하는 흐름이다.
+
+---
+
+## 3. 제품 원칙
+
+### 1. `/stats`의 primary entry는 `/app`이다
+
+- review는 “지금 일하는 중에 보는 것”이 아니라
+- “다음 세션을 시작하기 직전에 확인하는 것”이다
+
+### 2. `/space`는 review의 메인 진입점이 아니다
+
+- `/space`는 execution surface다
+- review는 boundary ritual이어야 한다
+- `/space`에서는 teaser만 허용하고, full review로의 강한 유도는 금지한다
+
+### 3. review는 다음 행동으로 연결되어야 한다
+
+- `/stats`는 읽고 끝나는 페이지가 아니다
+- 마지막 CTA는 반드시 `/app`의 next session start와 연결돼야 한다
+
+### 4. review 진입은 “보면 좋음”이 아니라 “지금 보면 의미 있음”이어야 한다
+
+- 무조건 항상 띄우지 않는다
+- 데이터가 충분하고, 지금 보는 것이 실제로 의미 있을 때만 노출한다
+
+### 5. review는 planning이 아니라 focus optimization이다
+
+- 할 일 정리로 이어지면 실패
+- 다음 세션의 시작 조건을 더 잘 맞추는 흐름이어야 한다
+
+---
+
+## 4. 왜 `/app`이 primary entry인가
+
+`/app`은 commitment gate다.
+즉 사용자가 “지금 한 가지를 붙잡고 들어가겠다”는 결정을 내리는 곳이다.
+
+review가 가장 유의미한 순간도 바로 여기다.
+
+왜냐하면:
+
+- review를 보고 바로 다음 세션을 시작할 수 있다
+- `/space`보다 맥락이 느슨해서 회고가 자연스럽다
+- `/stats`를 planner page처럼 쓰지 않고 entry ritual로 흡수할 수 있다
+
+반대로 `/space`는:
+
+- 이미 실행 중인 화면이고
+- review가 들어오면 흐름을 끊고
+- 제품을 dashboard처럼 보이게 만들 수 있다
+
+결론:
+
+- `/app`은 review를 여는 문
+- `/stats`는 주간 review desk
+- `/app`으로 돌아와 다시 시작
+
+이 삼각 구조가 가장 맞다.
+
+---
+
+## 5. 사용자 플로우
+
+### Primary Flow
+
+`/app -> /stats -> /app`
+
+1. 사용자가 `/app`에 들어온다
+2. hero 아래 또는 하단에 `weekly review teaser`가 보인다
+3. 사용자가 teaser를 누른다
+4. `/stats`로 이동한다
+5. review를 본다
+6. 하단 CTA `이 흐름으로 다음 세션 시작`
+7. `/app`으로 돌아온다
+8. review에서 이어온 ritual/context를 가지고 바로 start한다
+
+핵심:
+
+- review는 `/app`을 대체하지 않는다
+- review는 `/app`을 보조한다
+- review를 보고 다시 `/app`으로 돌아오는 구조가 중요하다
+
+### Secondary Flow
+
+`/space complete -> teaser -> /stats`
+
+1. 사용자가 `/space`에서 세션을 마친다
+2. complete flow가 끝난다
+3. 조건이 충족되면 작은 review teaser만 보여준다
+4. 사용자가 원할 때만 `/stats`로 간다
+
+중요:
+
+- `/space`에서는 full review를 메인 행동으로 밀지 않는다
+- complete tray를 review 유도 UI로 바꾸지 않는다
+
+### Tertiary Flow
+
+`profile / secondary nav -> /stats`
+
+- 다시 review를 보고 싶은 사용자를 위한 명시적 진입
+- 메인 CTA는 아니다
+
+---
+
+## 6. `/app`에서 review teaser를 언제 보여줄 것인가
+
+항상 보여주면 안 된다.
+“지금 봐도 의미 없음” 상태에서는 review가 노이즈가 된다.
+
+### 노출 조건
+
+기본 규칙:
+
+- 최근 7일 started session >= 3
+
+추가 강화 조건:
+
+- completed session >= 2
+  또는
+- returned after pause >= 1
+
+즉,
+
+- 데이터가 너무 적으면 teaser를 숨긴다
+- 최소한 “이번 주 리듬”이라고 부를 수 있을 만큼 쌓였을 때만 연다
+
+### 노출하지 않는 경우
+
+- 첫 1~2회 사용
+- 세션 기록이 거의 없는 주
+- current session이 있고 resume가 primary인 상황에서 above-the-fold 경쟁이 심할 때
+
+이 경우:
+
+- `/app` 메인 hero는 single-goal commitment에 집중
+- review teaser는 숨기거나 below-the-fold에 둔다
+
+---
+
+## 7. `/app` teaser 설계
+
+### 위치
+
+추천 위치:
+
+- hero 바로 아래
+- 또는 hero 하단과 footer 사이
+
+금지:
+
+- hero CTA보다 위
+- hero CTA와 같은 무게
+- card 3개 중 하나처럼 보이게 배치
+
+### 형태
+
+- low-emphasis secondary panel
+- 작고 조용한 one-liner + secondary CTA
+
+예시:
+
+- `이번 주엔 오전 시작에서 가장 오래 이어졌어요`
+- `pause 뒤 복귀 3회 · review 보기`
+
+### CTA
+
+- `주간 review 보기`
+
+보조 문구:
+
+- `다음 세션 전에 가볍게 보고 갈 수 있어요`
+
+### UX 원칙
+
+- teaser는 insight를 다 말하지 않는다
+- review를 보고 싶게 만들되, hero를 가리지 않는다
+- start CTA보다 절대 커 보이면 안 된다
+
+---
+
+## 8. `/stats` 내부 플로우
+
+### 진입 직후
+
+- 이번 주 snapshot hero
+- start / recovery / completion
+- carry forward
+
+### 마지막 CTA
+
+review의 마지막 CTA는 아래 중 하나여야 한다.
+
+- `이 흐름으로 다음 세션 시작`
+- `이 조합으로 /app 돌아가기`
+
+추천:
+
+- CTA를 `/app?review=weekly&preset=...` 같은 방식으로 연결
+- 최소한 query 또는 client state로 ritual/context를 넘긴다
+
+중요:
+
+- `/stats`에서 바로 `/space`로 가지 않는다
+- `/app`을 다시 거치게 해서 commitment gate를 유지한다
+
+왜냐하면:
+
+- review 후에도 goal은 다시 내가 정해야 한다
+- VibeRoom의 핵심은 single-goal commitment이지, review에서 바로 auto-start가 아니다
+
+---
+
+## 9. `/app` 복귀 후 UX
+
+### 복귀 상태
+
+`/stats`에서 온 경우 `/app`은 plain 상태가 아니라
+review-aware state가 된다.
+
+보여줄 것:
+
+- “방금 본 review 기준 추천” 한 줄
+- review carry-forward hint
+- optional ritual prefill
+
+예시:
+
+- `이번 주에 가장 잘 맞았던 흐름 · Forest · 50/10`
+- `이번엔 시작을 더 작게 잡아보세요`
+
+### 유지할 것
+
+- goal은 여전히 사용자가 직접 입력
+- microStep도 직접 입력 가능
+
+자동으로 하지 말 것:
+
+- goal 자동 채우기
+- 바로 `/space`로 보냄
+- todo/list를 다시 불러옴
+
+즉 review는:
+
+- 방향을 준다
+- 하지만 결정을 대신하진 않는다
+
+---
+
+## 10. Free / Pro 차이
+
+### Free
+
+- `/app` teaser는 1개만
+- `/stats`에서는 이번 주 snapshot + start / recovery / completion 핵심까지만
+- return CTA는 generic
+  - `이 흐름으로 다음 세션 시작`
+
+### Pro
+
+- teaser가 더 구체적일 수 있다
+  - `Forest · 50/10에서 pause 뒤 복귀율이 가장 높았어요`
+- `/stats` 마지막 CTA가 더 개인화된다
+  - `가장 잘 맞은 ritual로 /app 돌아가기`
+- `/app` 복귀 후 ritual prefill / carry-forward hint가 더 정교하다
+
+핵심:
+
+- Pro는 더 많은 review가 아니라
+- 더 정확한 next-session handoff를 판다
+
+---
+
+## 11. UI/UX 원칙
+
+### `/app` teaser
+
+- hero보다 작음
+- 한 줄 summary
+- secondary CTA
+- glass/card를 크게 쓰지 않음
+
+### `/stats`
+
+- calm review desk
+- 읽고 이해하고, 마지막에 행동 하나를 고르는 구조
+
+### `/app` return state
+
+- 다시 시작하는 감각 유지
+- review를 보고 왔다고 해서 `/app`이 dashboard처럼 바뀌면 안 된다
+
+---
+
+## 12. 구현 순서
+
+### Slice 1. `/app` weekly review teaser 추가
+
+범위:
+
+- teaser 노출 조건
+- teaser UI
+- `/stats` deep link
+
+완료 기준:
+
+- `/app`에서 review로 들어가는 primary path가 생긴다
+
+### Slice 2. `/stats -> /app` return CTA 연결
+
+범위:
+
+- `/stats` 마지막 CTA
+- query/state handoff
+- `/app` review-aware state
+
+완료 기준:
+
+- review가 읽고 끝나는 페이지가 아니라 다음 세션으로 이어진다
+
+### Slice 3. Pro personalized handoff
+
+범위:
+
+- best ritual carry-forward
+- review origin state 유지
+- CTA copy personalization
+
+완료 기준:
+
+- Pro가 더 자연스럽게 다음 세션으로 이어진다
+
+### Slice 4. `/space` secondary teaser
+
+범위:
+
+- complete 이후 작은 review teaser
+- full review 강제 이동 금지
+
+완료 기준:
+
+- `/space`에서도 review가 존재하지만 execution을 방해하지 않는다
+
+---
+
+## 13. 데이터 / 인터페이스 제안
+
+### `/app` teaser용 데이터
+
+새 hook 또는 기존 `useFocusStats` 확장:
+
+- `hasEnoughWeeklyData`
+- `weeklyTeaserLine`
+- `reviewHref`
+
+### `/stats -> /app` handoff
+
+추천 query:
+
+- `review=weekly`
+- `entryPreset=forest-50-10`
+- `carryHint=start-smaller`
+
+주의:
+
+- query는 가볍게
+- 민감한 분석 전체를 싣지 않는다
+
+### `/app` 복귀 상태
+
+로컬 상태:
+
+- `reviewSource`
+- `suggestedEntryPreset`
+- `carryForwardHint`
+
+---
+
+## 14. 완료 기준
+
+- `/stats`의 primary entry가 `/app`에 생긴다
+- `/space`는 review의 secondary entry만 가진다
+- review를 본 뒤 사용자가 다시 `/app`으로 돌아와 다음 세션을 시작할 수 있다
+- review가 planner나 dashboard가 아니라 next-session ritual처럼 읽힌다
+- Free / Pro의 handoff 차이가 분명하다
+
+---
+
+## 15. 절대 피해야 할 방향
+
+- `/space`에서 review로 강하게 끌어가는 것
+- review를 top nav의 메인 기능처럼 밀어올리는 것
+- `/stats`에서 바로 `/space` auto-start
+- review 결과로 goal을 자동 생성하는 것
+- review teaser가 `/app` hero보다 더 커 보이게 하는 것
+- planner/todo 회고처럼 보이게 만드는 것
diff --git a/docs/work.md b/docs/work.md
index 6420b62..c5cbce2 100644
--- a/docs/work.md
+++ b/docs/work.md
@@ -91,23 +91,23 @@
 
 ## 작업 4
 
-- 제목: `Weekly Review Reframe` 2차 구현
-- 목적:
-  - `14_weekly_review_reframe_spec.md` 기준으로 `/stats` review를 더 실제 제품 수준으로 끌어올린다.
-- 변경 범위:
-  - recovery quality 실제 집계 연결
-  - ritual fit highlight 1차
-  - Free / Pro review gating
-- 제외 범위:
-  - planner/dashboard 확장 금지
-  - 과한 해석형 카피 금지
-  - Premium Ambience 작업 선행 금지
-- 완료 조건:
-  - `/stats`의 recovery가 limited state가 아니라 실제 데이터 기반으로 보인다.
-  - ritual fit이 mock 문구가 아니라 실제 주간 review 흐름에 들어간다.
-  - Free와 Pro의 review 차이가 분명해진다.
-- 검증:
-  - 상세 spec과 구현 일치
-  - 브라우저 구조 / 문장 / hierarchy 확인
-- 커밋 힌트:
-  - feat(stats): weekly-review-recovery
+- 제목: `Weekly Review Entry Flow` 구현
+ - 목적:
+  - `15_app_stats_entry_flow_spec.md` 기준으로 `/app -> /stats -> /app` loop를 실제 제품 루프에 연결한다.
+ - 변경 범위:
+  - `/app` weekly review teaser
+  - `/stats` 마지막 CTA의 `/app` return handoff
+  - `/app` review-aware return state
+ - 제외 범위:
+  - `/stats`에서 바로 `/space` auto-start 금지
+  - review teaser를 hero보다 강하게 노출하는 것 금지
+  - planner/todo 회고 흐름으로 확장 금지
+ - 완료 조건:
+  - `/app`에서 review로 들어가는 primary path가 생긴다.
+  - `/stats`를 보고 다시 `/app`으로 돌아와 다음 세션을 시작할 수 있다.
+  - review가 읽고 끝나는 페이지가 아니라 next-session ritual처럼 동작한다.
+ - 검증:
+  - `/app -> /stats -> /app` 실제 브라우저 플로우 확인
+  - hero와 teaser의 시각 우선순위 확인
+ - 커밋 힌트:
+  - feat(app): weekly-review-entry-flow