Skip to content

Add user replay evidence guidance pack#689

Merged
sungjunlee merged 3 commits into
mainfrom
issue-683-user-replay-guidance
Jun 8, 2026
Merged

Add user replay evidence guidance pack#689
sungjunlee merged 3 commits into
mainfrom
issue-683-user-replay-guidance

Conversation

@sungjunlee

@sungjunlee sungjunlee commented Jun 8, 2026

Copy link
Copy Markdown
Owner

Summary

  • Add opt-in user-replay-evidence guidance selection for product-flow task signals.
  • Document the new advisory pack and task-profile selection hint while keeping Done Criteria/rubric authority explicit.
  • Add generic code/docs negative coverage and a product-flow fixture rendering test.

Verification

  • HEAD: 8cb18d8
  • node --test tests/relay-plan/scripts/task-profile.test.js tests/relay-plan/scripts/dispatch-prompt-emit.test.js tests/relay-plan/scripts/rubric-reference-contract.test.js
  • Result: 41 pass, 0 fail

Closes #683
Refs #678

Summary by CodeRabbit

릴리스 노트

  • New Features

    • 사용자 여정/화면 변경 작업에 대한 새로운 가이던스 팩 추가. 검토자가 사용자가 수행할 수 있는 내용을 간결한 재생 증거로 기록 가능.
  • Documentation

    • 가이던스 팩 참조 및 작업 프로필 문서 업데이트.
  • Tests

    • 가이던스 팩 선택 규칙 및 자동 감지 기능 검증 테스트 추가.

@coderabbitai

coderabbitai Bot commented Jun 8, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@sungjunlee, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 43 minutes and 37 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ee2dc774-273b-41e0-985d-cb4082a4d9f7

📥 Commits

Reviewing files that changed from the base of the PR and between 8cb18d8 and cdc174e.

📒 Files selected for processing (4)
  • skills/relay-plan/references/guidance-packs.md
  • skills/relay-plan/scripts/task-profile.js
  • tests/relay-plan/fixtures/task-profile/product-flow-done-criteria.md
  • tests/relay-plan/scripts/task-profile.test.js

Walkthrough

이 PR은 제품 플로우 태스크를 위한 새로운 user-replay-evidence 가이던스 팩을 추가합니다. 팩 정의, 자동 선택 로직, 테스트 계약 및 포괄적인 테스트 커버리지를 포함합니다.

Changes

user-replay-evidence 가이던스 팩 도입

Layer / File(s) Summary
가이던스 팩 정의 및 계약
skills/relay-plan/references/guidance-packs.md, skills/relay-plan/references/task-profile.md, tests/relay-plan/scripts/rubric-reference-contract.test.js
새로운 user-replay-evidence 팩을 정의하여 사용자 여정 변경 시 리플레이 증거(진입점, 주요 경로, 최종 상태, 가시적 예외)를 남기도록 가이드한다. 팩이 Done Criteria/루브릭의 필수 요구사항을 대체하지 않음을 명시하고, 테스트 계약에 팩을 등록한다.
제품 플로우 감지 및 팩 선택
skills/relay-plan/scripts/task-profile.js
제품/사용자/고객 플로우 키워드를 감지하는 PRODUCT_FLOW_PATTERN 정규식과 hasProductFlowSignal 헬퍼 함수를 추가하고, deriveTaskProfile에서 신호 감지 시 user-replay-evidence 팩을 자동으로 포함한다.
테스트 검증: 비제품 플로우 및 제품 플로우 시나리오
tests/relay-plan/fixtures/task-profile/product-flow-done-criteria.md, tests/relay-plan/scripts/task-profile.test.js
온보딩 사용자 여정 fixture를 통해 리플레이 증거 요구사항을 구체화하고, 일반 코드/문서 태스크는 팩을 포함하지 않으며 제품 플로우 태스크는 팩을 포함하고 렌더링 결과가 올바른 구조를 유지하는지 검증한다.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

  • sungjunlee/dev-relay#405: 유사하게 guidance-packs.mdrubric-reference-contract.test.js에서 가이던스 팩 계약을 수정하여 필수 팩 목록을 확장한다.

Poem

🐰 사용자의 여정을 따라가며,
리플레이 증거를 남기자네!
제품 흐름의 진짜 길을 밟고,
데모 덫을 피해 나가는 길,
검토자의 눈에 명확히 보이리라! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed PR 제목 'Add user replay evidence guidance pack'는 변경 사항의 핵심인 새로운 가이던스 팩 추가를 명확하게 설명합니다.
Linked Issues check ✅ Passed 변경 사항이 #683의 모든 주요 목표를 충족합니다: user-replay-evidence 팩 구현, product-flow 신호 감지, guidance-packs.md 문서화, 관련 테스트 추가.
Out of Scope Changes check ✅ Passed 모든 변경 사항이 #683의 범위 내에 있으며, 새로운 guidance pack 추가 및 관련 테스트/문서에만 집중합니다.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-683-user-replay-guidance

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@sungjunlee

Copy link
Copy Markdown
Owner Author

Relay Review Round 1

Verdict: CHANGES_REQUESTED
Summary: DC 상태: PARTIAL task-profile 선택은 구현됐지만 필수 generic product-flow 신호 범위가 좁습니다. VERIFIED guidance-packs.md는 사용/비사용/권위 경계를 문서화했습니다. VERIFIED generic code/docs 비선택 테스트가 있습니다. PARTIAL product-flow fixture는 렌더링과 권위 경계를 확인하지만 rubric이 요구한 replay 세부 항목을 렌더링하지 않습니다. VERIFIED 새 skill/reviewer path, merge gate, Dear Scene 용어는 추가되지 않았습니다.
Contract: FAIL
Quality Review: NOT_RUN
Quality Execution: PASS
Issues:

  • skills/relay-plan/scripts/task-profile.js:10 — Product-flow selector misses required generic signal classes: The new selector only recognizes explicit flow/journey wording plus a small set of named flows. The rubric requires generic product-flow signals such as file/input/provider/state/export/delete/retry, demo/synthetic risk, and UI/harness provider alignment. Tasks in those categories will not receive user-replay-evidence unless they also happen to contain flow/journey wording.
  • skills/relay-plan/references/guidance-packs.md:74 — Rendered replay guidance omits required replay evidence details: The rendered guidance currently asks for entry point, main path, final state, and a visible edge case, but the dispatch_rendering rubric requires real input, negative case, state transition, and evidence artifact expectations. The product-flow fixture/test only proves the generic bullet and authority boundary, so it does not satisfy the planned rendering contract.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/relay-plan/scripts/task-profile.js`:
- Line 10: Add a concise explanatory comment above the PRODUCT_FLOW_PATTERN
constant that documents the three alternation groups and what each matches: (1)
phrases like "user/customer/product journey/flow" (handles optional space/dash
and pluralization), (2) specific flow keywords such as "onboarding", "checkout",
"sign-up", "login", "purchase", "profile", "search", "invite", "upload" with
optional "flow(s)" and hyphen/space variants, and (3) terms like
"screen-by-screen", "end-to-end", or "e2e" optionally followed by
"product/user/customer" and "flow/journey"; include a short example or two for
each group and note that the regex is case-sensitive or not (and any flags) so
future maintainers understand intent when updating PRODUCT_FLOW_PATTERN.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2cdb82ec-15ae-4bcb-92e8-fba8469eb4b6

📥 Commits

Reviewing files that changed from the base of the PR and between c50f743 and 8cb18d8.

📒 Files selected for processing (6)
  • skills/relay-plan/references/guidance-packs.md
  • skills/relay-plan/references/task-profile.md
  • skills/relay-plan/scripts/task-profile.js
  • tests/relay-plan/fixtures/task-profile/product-flow-done-criteria.md
  • tests/relay-plan/scripts/rubric-reference-contract.test.js
  • tests/relay-plan/scripts/task-profile.test.js

const SIZES = new Set(["S", "M", "L", "XL"]);
const TRUST_BOUNDARY_PATTERN = /\b(?:trust[- ]boundary|auth[- ]boundary|trust root|forge|forged|bypass|fail closed|gate-check|validate[- ]?(?:manifest|transition)|state transition|state-machine)\b/;
const STATE_MACHINE_PATTERN = /\b(?:state transition|state-machine|validate[- ]?transition|manifest state)\b/;
const PRODUCT_FLOW_PATTERN = /\b(?:user|customer|product)[ -]?(?:journey|flow)s?\b|\b(?:onboarding|checkout|sign[- ]?up|login|purchase|activation|booking|subscription|settings|profile|search|invite|upload)[ -]?flows?\b|\b(?:screen-by-screen|end-to-end|e2e)\s+(?:product|user|customer)?\s*(?:flow|journey)s?\b/;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

복잡한 정규식 패턴에 설명 주석을 추가하세요.

PRODUCT_FLOW_PATTERN은 3개의 교대 패턴으로 구성된 복잡한 정규식이지만 설명 주석이 없습니다. 코딩 가이드라인에 따르면 복잡한 로직에는 의미 있는 주석이 필요합니다. 각 교대 패턴이 감지하는 케이스를 설명하는 주석을 추가하여 유지보수성을 개선하세요.

💡 제안하는 주석 예시
+// Detect product/user flow keywords in Done Criteria/task signals:
+// 1. user/customer/product journey|flow (e.g., "user journey", "product-flow")
+// 2. Domain-specific flows (e.g., "onboarding", "checkout flow", "sign-up flow")
+// 3. Screen-by-screen descriptors (e.g., "end-to-end user flow", "e2e product journey")
 const PRODUCT_FLOW_PATTERN = /\b(?:user|customer|product)[ -]?(?:journey|flow)s?\b|\b(?:onboarding|checkout|sign[- ]?up|login|purchase|activation|booking|subscription|settings|profile|search|invite|upload)[ -]?flows?\b|\b(?:screen-by-screen|end-to-end|e2e)\s+(?:product|user|customer)?\s*(?:flow|journey)s?\b/;
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const PRODUCT_FLOW_PATTERN = /\b(?:user|customer|product)[ -]?(?:journey|flow)s?\b|\b(?:onboarding|checkout|sign[- ]?up|login|purchase|activation|booking|subscription|settings|profile|search|invite|upload)[ -]?flows?\b|\b(?:screen-by-screen|end-to-end|e2e)\s+(?:product|user|customer)?\s*(?:flow|journey)s?\b/;
// Detect product/user flow keywords in Done Criteria/task signals:
// 1. user/customer/product journey|flow (e.g., "user journey", "product-flow")
// 2. Domain-specific flows (e.g., "onboarding", "checkout flow", "sign-up flow")
// 3. Screen-by-screen descriptors (e.g., "end-to-end user flow", "e2e product journey")
const PRODUCT_FLOW_PATTERN = /\b(?:user|customer|product)[ -]?(?:journey|flow)s?\b|\b(?:onboarding|checkout|sign[- ]?up|login|purchase|activation|booking|subscription|settings|profile|search|invite|upload)[ -]?flows?\b|\b(?:screen-by-screen|end-to-end|e2e)\s+(?:product|user|customer)?\s*(?:flow|journey)s?\b/;
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/relay-plan/scripts/task-profile.js` at line 10, Add a concise
explanatory comment above the PRODUCT_FLOW_PATTERN constant that documents the
three alternation groups and what each matches: (1) phrases like
"user/customer/product journey/flow" (handles optional space/dash and
pluralization), (2) specific flow keywords such as "onboarding", "checkout",
"sign-up", "login", "purchase", "profile", "search", "invite", "upload" with
optional "flow(s)" and hyphen/space variants, and (3) terms like
"screen-by-screen", "end-to-end", or "e2e" optionally followed by
"product/user/customer" and "flow/journey"; include a short example or two for
each group and note that the regex is case-sensitive or not (and any flags) so
future maintainers understand intent when updating PRODUCT_FLOW_PATTERN.

Source: Coding guidelines

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 618cee5dc4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

const SIZES = new Set(["S", "M", "L", "XL"]);
const TRUST_BOUNDARY_PATTERN = /\b(?:trust[- ]boundary|auth[- ]boundary|trust root|forge|forged|bypass|fail closed|gate-check|validate[- ]?(?:manifest|transition)|state transition|state-machine)\b/;
const STATE_MACHINE_PATTERN = /\b(?:state transition|state-machine|validate[- ]?transition|manifest state)\b/;
const PRODUCT_FLOW_PATTERN = /\b(?:user|customer|product)[ -]?(?:journey|flow)s?\b|\b(?:onboarding|checkout|sign[- ]?up|login|purchase|activation|booking|subscription|settings|profile|search|invite|upload)[ -]?flows?\b|\b(?:screen-by-screen|end-to-end|e2e)\s+(?:product|user|customer)?\s*(?:flow|journey)s?\b/;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include standalone checkout/onboarding signals

For product tasks that mention a journey type without the literal word flow—for example, “Update the checkout page so customers can pay…” or “Improve onboarding so a new user reaches the dashboard”—this pattern does not match, and the secondary surface/signal check also misses them unless they happen to include one of the narrow state/export/delete/retry terms. That contradicts the new pack’s documented “Use when” cases for onboarding and checkout, so relay-plan will omit user-replay-evidence on common user-visible product-flow tasks that the feature is meant to cover.

Useful? React with 👍 / 👎.

@sungjunlee

Copy link
Copy Markdown
Owner Author

Relay Review Round 2

Verdict: CHANGES_REQUESTED
Summary: DC 상태: PARTIAL task-profile.js는 product-flow fixture에서 user-replay-evidence를 선택하지만 provider/state 같은 백엔드 문구 조합에도 선택될 수 있어 unrelated prompt output 보존이 깨집니다. VERIFIED guidance-packs.md는 사용/비사용/권위 경계를 문서화했습니다. PARTIAL generic code/docs 비선택 테스트는 있으나 실제 정규식이 매칭하는 backend provider/state 조합을 막지 못합니다. VERIFIED product-flow fixture는 replay guidance와 Done Criteria/rubric 권위 경계를 렌더링합니다. VERIFIED 새 skill/reviewer path, merge gate, Dear Scene 용어는 추가되지 않았습니다.
Contract: FAIL
Quality Review: NOT_RUN
Quality Execution: PASS
Issues:

  • skills/relay-plan/scripts/task-profile.js:11 — Provider/state 백엔드 작업에도 replay guidance가 선택됩니다: PRODUCT_SURFACE_PATTERN이 provider를 product surface로 취급하고 PRODUCT_FLOW_SIGNAL_PATTERN이 state transition을 flow signal로 취급합니다. 그래서 UI나 사용자 여정이 없는 일반 코드 작업인 Add provider state transition validation in the relay-plan parser helper 같은 입력도 두 패턴을 모두 만족해 user-replay-evidence를 받게 됩니다. 이는 product-flow 신호에만 선택하고 unrelated prompt output은 바꾸지 않아야 한다는 계약과 generic code/docs 비선택 의도를 깨뜨립니다.

@sungjunlee

Copy link
Copy Markdown
Owner Author

Relay Review

Verdict: LGTM
Summary: DC 상태: VERIFIED task-profile.js는 product-flow/journey 및 UI surface + replay signal 조합에서 user-replay-evidence를 선택하고, docs 및 generic backend/provider-state negative cases는 제외합니다. VERIFIED guidance-packs.md는 사용/비사용/권위 경계를 문서화했습니다. VERIFIED generic code/docs 및 backend signal negative tests가 추가됐습니다. VERIFIED product-flow fixture가 replay guidance와 Done Criteria/rubric authority boundary를 렌더링합니다. VERIFIED 새 skill/reviewer path, merge gate, Dear Scene 용어는 추가되지 않았습니다. 변경 파일은 모두 DC 직접 구현 또는 테스트/참조 지원 범위입니다.
Contract: PASS
Quality Review: PASS
Quality Execution: PASS
Rounds: 3

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cdc174e4e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +150 to +151
if (change_type === "docs") return false;
if (PRODUCT_FLOW_PATTERN.test(text)) return true;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Exclude non-product change types from replay guidance

For test-, prompt-, or infrastructure-only tasks that mention a product journey, e.g. Update checkout flow regression coverage in tests/... without product behavior changes, change_type is not docs, so PRODUCT_FLOW_PATTERN still adds user-replay-evidence. That contradicts the new pack’s own “Do not use” boundary for tests/prompt/infra work with no changed product journey and causes relay-plan to inject irrelevant replay guidance into those dispatch prompts.

Useful? React with 👍 / 👎.

@sungjunlee sungjunlee merged commit b7e9fcb into main Jun 8, 2026
2 checks passed
@sungjunlee sungjunlee deleted the issue-683-user-replay-guidance branch June 8, 2026 12:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

relay-plan: add opt-in user-replay evidence guidance for product-flow tasks

1 participant