diff --git a/docs/12_core_loop_execution_roadmap.md b/docs/12_core_loop_execution_roadmap.md index e579a77..85f439d 100644 --- a/docs/12_core_loop_execution_roadmap.md +++ b/docs/12_core_loop_execution_roadmap.md @@ -16,6 +16,7 @@ Last Updated: 2026-03-15 - `09_app_entry_detailed_spec.md` - `10_refocus_system_spec.md` - `11_away_return_recovery_spec.md` +- `16_product_alignment_audit_plan.md` --- @@ -373,4 +374,5 @@ Away / Return이 끼어들기 전, 다음으로 예정된 축은 아래 두 가 현재 위치: -> `3. Break refinement`를 마무리했고, `4. Weekly Review`의 entry flow 구현까지 마친 상태다. +> 코어 루프 기준으로는 `4. Weekly Review`의 entry flow 구현까지 마친 상태이고, +> 운영 기준으로는 이제 `Product Alignment Audit`을 통해 core loop 전반의 기획-구현 정합성을 전수 점검하는 단계다. diff --git a/docs/16_product_alignment_audit_plan.md b/docs/16_product_alignment_audit_plan.md new file mode 100644 index 0000000..137efaa --- /dev/null +++ b/docs/16_product_alignment_audit_plan.md @@ -0,0 +1,602 @@ +# 16. Product Alignment Audit Plan + +Last Updated: 2026-03-15 + +이 문서는 VibeRoom 전체에서 **기획과 구현이 어긋난 부분을 체계적으로 찾아내고, 실제 수정 작업까지 연결하는 실행 계획**이다. + +목표는 단순하다. + +> 우연히 발견한 불일치를 그때그때 고치는 방식에서 벗어나, +> 어떤 세션과 어떤 에이전트가 들어와도 같은 기준으로 앱 전체를 점검하고 닫을 수 있는 운영 체계를 만든다. + +--- + +## 1. 왜 이 문서가 필요한가 + +최근 점검에서 이미 아래 문제가 반복적으로 드러났다. + +- 카피는 `break`를 약속하는데 실제 동작은 `pause`인 경우 +- spec은 `/app`이 review의 primary entry라고 적혀 있는데 구현에서는 resume 상태에서 review entry가 사라지는 경우 +- `goal click`, `수정`, `expand/collapse`의 역할 분리가 코드와 문서에서 다르게 남는 경우 +- `/stats -> /app` handoff가 실제 행동을 바꾸지 않는데 문구는 개인화된 추천을 약속하는 경우 + +즉 현재 문제는 “버그가 많다”가 아니라, +**기획 / 카피 / 상태 모델 / 실제 코드 / 문서가 동시에 drift할 수 있는 구조**라는 점이다. + +이 audit plan의 목적은 아래 4개다. + +1. source of truth를 고정한다 +2. route / state / copy / BM claim을 같은 표로 점검한다 +3. 발견된 불일치를 severity와 수정 단위로 즉시 분류한다 +4. 수정 후 문서와 QA까지 같은 라운드에서 닫는다 + +--- + +## 2. Audit의 정의 + +이 문서에서 말하는 `alignment audit`는 아래 5개를 동시에 보는 점검이다. + +### 1. Product Alignment + +- 제품 원칙과 실제 기능이 맞는가 +- single-goal, single-microStep, commitment-first 원칙이 지켜지는가 + +### 2. Flow Alignment + +- 사용자가 실제로 밟는 경로가 기획된 유저 플로우와 맞는가 +- entry / recovery / complete / review의 연결이 끊기지 않는가 + +### 3. Copy Alignment + +- 화면 문구가 실제 동작을 과장하거나 왜곡하지 않는가 +- 초심자도 용어 없이 이해 가능한가 + +### 4. State Alignment + +- pause / break / return / complete / resume 같은 상태 의미가 코드와 카피에서 일치하는가 + +### 5. Business Alignment + +- Free / Pro 가치 제안이 실제 제품 행동으로 느껴지는가 +- “된다고 쓰여 있지만 실제로는 안 되는” BM성 약속이 없는가 + +--- + +## 3. Source of Truth 우선순위 + +Audit 중 충돌이 생기면 아래 순서로 판단한다. + +1. `product_principles.md` +2. `/Users/ijeongmin/Desktop/corpi/viberoom/current_context.md` +3. route/flow 관련 상세 spec + - `09_app_entry_detailed_spec.md` + - `10_refocus_system_spec.md` + - `11_away_return_recovery_spec.md` + - `13_space_intent_card_collapsed_expanded_spec.md` + - `14_weekly_review_reframe_spec.md` + - `15_app_stats_entry_flow_spec.md` +4. `90_current_state.md` +5. 실제 코드 + +중요: + +- 코드가 source of truth가 아니다 +- 하지만 문서가 낡았고 코드가 더 최근 의도를 반영한다면, 그 차이를 `finding`으로 기록한 뒤 문서를 업데이트한다 + +--- + +## 4. Audit 범위 + +### 4.1 Route 범위 + +반드시 본다. + +- `/` +- `/login` +- `/app` +- `/space` +- `/stats` +- `/settings` +- `/admin` + +### 4.2 Core Product Flow 범위 + +반드시 본다. + +- Landing -> Auth -> `/app` +- `/app` new start +- `/app` resume +- `/space` focus +- `/space` pause +- `/space` return +- `/space` next beat +- `/space` goal complete +- `/space` complete -> setup +- `/app -> /stats -> /app` +- paywall / Pro handoff + +### 4.3 Cross-cutting 범위 + +반드시 본다. + +- i18n copy +- query param handoff +- API contract / optimistic UI +- plan tier gating +- toast / reminder / empty state +- docs drift + +--- + +## 5. Audit 원칙 + +### 1. 화면이 아니라 “행동 단위”로 점검한다 + +예: + +- `Goal Complete` 화면 자체를 보는 게 아니라 +- `사용자가 목표를 끝냈다고 느끼는 순간 -> 선택 -> 결과 상태` 전체를 본다 + +### 2. copy와 behavior를 반드시 함께 본다 + +카피만 맞고 동작이 다르면 실패다. +동작은 맞는데 카피가 과장되면 그것도 실패다. + +### 3. Free / Pro 약속은 더 엄격하게 본다 + +BM에 연결된 카피는 일반 카피보다 더 엄격하게 검증한다. + +예: + +- “추천 ritual로 돌아가기” +- “방금 끝낸 흐름까지 담아 review” +- “주간 review가 다음 세션을 돕는다” + +### 4. 한 라운드에서 `finding -> fix -> docs -> commit`까지 닫는다 + +발견만 하고 쌓아두지 않는다. + +### 5. 브라우저 QA 없이 닫지 않는다 + +`tsc`, `eslint` 통과는 필수지만 충분조건이 아니다. + +--- + +## 6. Finding 분류 기준 + +### P1 + +제품 의미가 뒤틀리는 불일치 + +예: + +- break로 쓰였는데 실제로 break가 아님 +- primary entry가 없어짐 +- Pro value를 약속하지만 실제로 작동하지 않음 + +### P2 + +사용자 플로우가 헷갈리거나 약속이 약해지는 불일치 + +예: + +- 문구는 맞지만 진입점이 숨겨짐 +- 2단계 flow인데 1단계처럼 보임 +- recovery 상태가 시각적으로 구분되지 않음 + +### P3 + +문서 / 카피 / 접근성 / 잔여 코드 드리프트 + +예: + +- 오래된 spec 표현 +- dead i18n key +- aria-label과 가시 UI가 어긋남 + +--- + +## 7. 실제 Audit 방법 + +Audit은 아래 6단계로 진행한다. + +### Phase 0. Baseline Freeze + +산출물: + +- 현재 기준 문서 목록 +- 현재 route / widget ownership map +- 현재 work order + +실행: + +- `current_context.md` +- `90_current_state.md` +- `12_core_loop_execution_roadmap.md` +- route map / session brief 확인 + +목적: + +- 무엇이 기준인지 먼저 잠근다 + +--- + +### Phase 1. Route & Flow Inventory + +각 route마다 아래를 표로 만든다. + +- route +- intended role +- main CTA +- secondary CTA +- entry source +- exit target +- hidden states +- Pro-specific behavior + +산출물: + +- `route-flow matrix` + +점검 질문: + +- 사용자는 이 route에 왜 오는가 +- 여기서 무엇을 해야 하는가 +- 다음 화면은 어디인가 +- 실제 코드가 이 흐름을 유지하는가 + +--- + +### Phase 2. State Contract Audit + +`/space`와 `/app`의 상태 전이를 표로 만든다. + +필수 상태: + +- setup +- focus +- paused +- return +- refocus +- next-beat +- complete-choice +- complete-next +- break +- review-entry + +각 상태마다 본다. + +- state 이름 +- 사용자가 이해하는 의미 +- 실제 trigger +- visible UI +- exit actions +- side effects + +산출물: + +- `state contract matrix` + +핵심 목적: + +- 이름만 있고 실제 의미가 다른 상태를 찾는다 + +--- + +### Phase 3. Copy / Behavior Audit + +각 핵심 CTA에 대해 아래를 점검한다. + +- label +- user promise +- actual effect +- mismatch 여부 + +예: + +- `잠시 비우기` +- `쉬기 이어가기` +- `다음 목표로 바로 시작` +- `주간 review 보기` +- `추천 ritual과 함께 /app 돌아가기` + +산출물: + +- `copy-behavior mismatch list` + +--- + +### Phase 4. Business Model Audit + +Free / Pro를 아래 기준으로 본다. + +- user sees +- user clicks +- actual unlocked behavior +- value perception +- overclaim risk + +반드시 보는 곳: + +- paywall copy +- `/stats` Pro carry-forward +- `/app` teaser / return hint +- review insight / ritual recommendation + +산출물: + +- `BM promise audit` + +--- + +### Phase 5. Browser Journey Audit + +이 단계는 실제 브라우저에서 한다. + +필수 시나리오: + +1. 로그인 후 `/app` 첫 진입 +2. `/app`에서 새 goal 시작 +3. `/app` resume 상태 +4. `/space` pause -> refocus -> resume +5. `/space` away -> return(focus) +6. `/space` focus ended while away -> return(break) +7. `/space` microStep done -> next beat +8. `/space` goal complete choice +9. `/space` goal complete next +10. `/space` complete -> setup -> review teaser +11. `/app` weekly review teaser -> `/stats` -> `/app` +12. Pro 상태 handoff + +각 시나리오마다 본다. + +- first meaningful paint +- primary CTA visibility +- copy comprehension +- next action clarity +- state transition correctness +- dismiss behavior +- mobile / desktop 차이 + +산출물: + +- `browser QA findings` + +--- + +### Phase 6. Fix Closure + +각 finding은 아래 단위로 닫는다. + +- finding 요약 +- severity +- affected files +- fix approach +- docs to update +- validation commands +- manual QA notes +- commit hash + +이 단계까지 끝나야 “수정 완료”다. + +--- + +## 8. 실제 실행 순서 + +앱 전체 audit은 아래 순서로 진행한다. + +### Slice A. Core Loop Alignment + +범위: + +- `/app` +- `/space` +- `/stats` + +우선 점검: + +- entry +- recovery +- completion +- review handoff + +이유: + +- VibeRoom의 돈 되는 핵심 가치가 여기 있다 + +### Slice B. Monetization Alignment + +범위: + +- paywall +- plan tier +- Pro copy +- Pro actual behavior + +이유: + +- BM 과장은 제품 신뢰를 가장 빠르게 해친다 + +### Slice C. Shell & Supporting Routes + +범위: + +- `/` +- `/login` +- `/settings` +- `/admin` + +이유: + +- 핵심 루프보다 우선순위는 낮지만, 전체 완성도와 신뢰에 영향이 크다 + +### Slice D. Docs & Regression Guard + +범위: + +- `current_context.md` +- `90_current_state.md` +- detailed specs +- lint / dead copy / route map + +이유: + +- 다음 세션에서 다시 어긋나지 않게 만드는 단계다 + +--- + +## 9. 추천 산출물 + +이 audit을 실제로 굴릴 때는 아래 3개 파일이 필요하다. + +### 1. 기준 문서 + +- 이 문서 `16_product_alignment_audit_plan.md` + +### 2. 실제 finding ledger + +추천 파일: + +- `17_product_alignment_findings.md` + +형식: + +- ID +- severity +- route / flow +- product promise +- actual behavior +- affected files +- fix status + +### 3. execution checklist + +추천 위치: + +- `work.md` + +형식: + +- 이번 slice에서 확인할 시나리오 +- 수정 범위 +- 제외 범위 +- 완료 조건 + +--- + +## 10. 이 audit을 어떻게 실행할 것인가 + +### 라운드 단위 규칙 + +한 라운드는 아래 순서로만 진행한다. + +1. 이번 slice 범위 결정 +2. static audit +3. browser audit +4. findings 정리 +5. fix +6. docs update +7. validation +8. commit + +### 각 라운드 출력 형식 + +항상 아래 형식으로 닫는다. + +- 추가 +- 수정 +- 삭제 +- 검증 +- 커밋 + +### 커밋 규칙 + +- 한 주제 = 한 커밋 +- 기획 불일치 정리는 `fix(flow): ...` +- 문서 중심 라운드는 `docs(product): ...` + +--- + +## 11. 바로 다음 실행 계획 + +### 실행 1. `17_product_alignment_findings.md` 생성 + +범위: + +- 현재까지 이미 드러난 core loop mismatch를 먼저 기록 + +포함: + +- break semantics +- review entry visibility +- review teaser overclaim +- Pro handoff realism +- docs drift + +### 실행 2. Slice A static audit + +대상: + +- `/app` +- `/space` +- `/stats` + +목표: + +- route-flow matrix +- state contract matrix +- copy-behavior mismatch list + +### 실행 3. Slice A browser audit + +대상 시나리오: + +1. `/app` first entry +2. `/app` resume +3. `/app -> /stats -> /app` +4. `/space` pause / return / complete +5. `/space complete -> setup -> review teaser` + +### 실행 4. findings fix round + +원칙: + +- P1 먼저 +- 그 다음 P2 +- P3는 같은 파일을 만질 때 함께 정리 + +--- + +## 12. 완료 기준 + +Alignment audit이 제대로 굴러간 상태는 아래와 같다. + +- 중요한 CTA가 실제 동작을 과장하지 않는다 +- primary / secondary entry가 문서와 코드에서 동일하다 +- pause / break / return / complete의 의미가 사용자 기준으로도 분리된다 +- Free / Pro 가치 제안이 실제 행동으로 느껴진다 +- 다음 세션/에이전트가 문서를 읽고도 현재 제품 상태를 오해하지 않는다 + +--- + +## 13. 절대 하지 말아야 할 것 + +- 브라우저 QA 없이 문서만 보고 “정상”이라고 판단 +- 카피만 바꾸고 실제 상태 모델은 그대로 두기 +- BM 문구를 구현보다 앞서 나가게 두기 +- `current_context.md`를 나중에 한꺼번에 갱신하기 +- 한 라운드에 너무 많은 route를 동시에 수정하기 + +--- + +## 14. 최종 판단 + +VibeRoom이 premium product가 되려면, +UI refinement만으로는 부족하다. + +정말 중요한 것은: + +> 사용자가 읽는 문구, 누르는 행동, 실제로 일어나는 상태 변화, +> 그리고 그걸 설명하는 문서가 모두 같은 제품을 말하고 있어야 한다. + +이 audit plan은 그 정합성을 제품 운영의 기본 프로세스로 만들기 위한 문서다. diff --git a/docs/session_brief.md b/docs/session_brief.md index ff1a7fc..40e1bde 100644 --- a/docs/session_brief.md +++ b/docs/session_brief.md @@ -14,9 +14,9 @@ Last Updated: 2026-03-15 ## 현재 우선순위 -1. `/space` Refocus + Return 브라우저 QA -2. `Weekly Review` 상세 기획 -3. `Premium Ambience System` 방향 정리 +1. `Product Alignment Audit` findings ledger 시작 +2. `Core Loop Alignment` static/browser audit +3. `Weekly Review` recovery 집계 연결 ## 최근 세션 상태 diff --git a/docs/work.md b/docs/work.md index a053e1d..93030c7 100644 --- a/docs/work.md +++ b/docs/work.md @@ -6,7 +6,8 @@ - 작업은 가능한 한 "주제별"로 분리해서 작성한다. - 한 주제는 가능하면 한 커밋으로 끝낼 수 있게 범위를 좁힌다. -- "금지사항/제외 범위"를 명시해서 불필요한 변경을 막는다. +- `finding -> fix -> docs -> validation -> commit`까지 한 라운드에서 닫는다. +- browser QA가 필요한 작업은 반드시 완료 조건에 명시한다. ## 우선순위 @@ -17,104 +18,69 @@ ## 작업 1 -- 제목: `/space` Refocus polish 마무리 +- 제목: `Product Alignment Audit` findings ledger 시작 - 목적: - - `10_refocus_system_spec.md` 기준으로 pause / refocus / next beat / goal complete를 premium recovery flow로 정리한다. - - recovery overlay가 planner/checklist처럼 보이지 않게 한다. + - `16_product_alignment_audit_plan.md` 기준으로 core loop 전반의 기획-구현 불일치를 하나의 ledger로 수집한다. + - 더 이상 발견 즉시 감으로 수정하지 않고, severity와 affected flow 기준으로 정리한다. - 변경 범위: - - pause tray - - refocus tray - - next beat tray - - goal complete tray - - copy / hierarchy / material / motion polish + - `/app` + - `/space` + - `/stats` + - 관련 카피 / query handoff / plan tier - 제외 범위: - - multi-goal / list affordance 추가 금지 - - social/accountability 확장 금지 - - review 통계 확장 금지 + - visual redesign 직접 착수 금지 + - 새로운 feature spec 확장 금지 + - `/settings`, `/admin` 구현 변경 금지 - 완료 조건: - - refocus가 `편집 기능`이 아니라 `recovery ritual`처럼 읽힌다. - - pause / next beat / complete가 한 번에 하나만 보인다. - - bright/dark scene 모두에서 안정적으로 읽힌다. + - `17_product_alignment_findings.md`가 생성된다 + - 최소한 P1 / P2 finding이 route, promise, actual behavior, affected file 기준으로 정리된다 + - 이미 수정된 항목과 아직 열린 항목이 분리된다 - 검증: - - 브라우저 수동 확인 + - 문서 self-review - 커밋 힌트: - - feat(space): refocus-system polish + - docs(product): alignment findings ledger 시작 ## 작업 2 -- 제목: `Away / Return Recovery` 구현 +- 제목: `Core Loop Alignment Audit` static slice - 목적: - - `11_away_return_recovery_spec.md` 기준으로 pause 없이 떠난 사용자의 복귀 흐름을 구현한다. - - `pause`, `break`, `return`이 같은 멈춤 상태처럼 읽히지 않게 한다. + - `/app`, `/space`, `/stats`의 route-flow matrix와 state contract matrix를 만든다. + - primary/secondary entry, CTA promise, 실제 상태 전환이 맞는지 정리한다. - 변경 범위: - - `visibilitychange` - - `pagehide` - - sleep/wake delta 감지 - - return tray - - focus ended while away 처리 + - route/flow inventory + - state contract matrix + - copy-behavior mismatch 정리 - 제외 범위: - - webcam / idle tracking / 감시성 기능 금지 - - planner/list affordance 추가 금지 - - break를 standard pause처럼 재사용 금지 + - visual polish 직접 수정 금지 + - recovery browser QA 금지 - 완료 조건: - - focus가 끝난 뒤 복귀하면 바로 standard break로 가지 않는다. - - return 상태에서 `이어가기 / 한 조각 다시 잡기 / 지금부터 쉬기` 중 적절한 제안이 나온다. + - `/app`, `/space`, `/stats`의 primary CTA와 secondary CTA가 표로 정리된다 + - pause / return / complete / review handoff의 상태 의미가 문서화된다 + - static mismatch가 severity와 함께 분류된다 - 검증: - - 브라우저 수동 확인 + 상태 전이 점검 + - source-of-truth 문서 대조 - 커밋 힌트: - - feat(space): away-return-recovery + - docs(flow): core-loop alignment matrix 추가 ## 작업 3 -- 제목: `Pause / Break / Return` 분리 polish +- 제목: `Core Loop Alignment Audit` browser slice - 목적: - - 세 상태가 감정적으로도 구조적으로도 다르게 읽히도록 정리한다. + - static audit에서 나온 핵심 흐름을 브라우저에서 실제로 검증한다. + - 문서와 코드가 맞더라도 실제 체감이 어긋나는지를 잡는다. - 변경 범위: - - 카피 - - material - - tray hierarchy - - timer/HUD와의 연결 + - `/app` first entry + - `/app` resume + - `/app -> /stats -> /app` + - `/space` pause / return / next beat / complete + - `/space` complete -> setup -> weekly review teaser - 제외 범위: - - review 통계 확장 금지 - - social/accountability 확장 금지 + - bulk visual redesign 금지 + - new feature 추가 금지 - 완료 조건: - - pause는 recovery tone - - break는 release tone - - return은 re-entry tone으로 분리된다 - - copy와 CTA hierarchy 2차 분리가 반영된다 - - motion polish 1차가 반영된다 + - browser QA findings가 ledger에 반영된다 + - P1/P2 mismatch는 수정 대상 라운드로 분리된다 - 검증: - - 브라우저 수동 확인 - - motion 미세 조정 + - manual browser QA - 커밋 힌트: - - feat(space): separate-pause-break-return - -## 작업 4 - -- 제목: `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처럼 동작한다. -- 진행 상태: - - Slice 1 완료: `/app` hero 아래 low-emphasis weekly review teaser 추가 - - Slice 2 완료: `/stats` 마지막 CTA가 `/app?review=weekly&carryHint=...` handoff로 연결 - - `/app`은 query를 받아 review-aware return hint를 먼저 보여준다 - - Slice 3 완료: Pro에서 추천 ritual과 더 구체적인 CTA / return hint가 연결된다 - - Slice 4 완료: `/space` complete 이후 setup drawer 아래에 secondary review teaser가 노출된다 - - 다음 작업: recovery browser QA 후 weekly review 실제 recovery 집계 연결 -- 검증: - - `/app -> /stats -> /app` 실제 브라우저 플로우 확인 - - hero와 teaser의 시각 우선순위 확인 -- 커밋 힌트: - - feat(app): weekly-review-entry-flow + - docs(qa): core-loop browser audit 기록