with one click
plan-review
// plan-format으로 작성한 정책서와 기능/화면설계서 묶음을 외부 발행 전에 Product Docs SSOT 충돌과 디자인·개발·QA·운영 착수 가능성 측면에서 검토하는 스킬.
// plan-format으로 작성한 정책서와 기능/화면설계서 묶음을 외부 발행 전에 Product Docs SSOT 충돌과 디자인·개발·QA·운영 착수 가능성 측면에서 검토하는 스킬.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | plan-review |
| description | Use when an existing plan-format 기능/화면설계서·정책서 초안 또는 초안 폴더를 외부 발행 전에 검토하고 통과/조건부 통과/수정 필요 판정을 내려야 할 때. |
| argument-hint | <초안 폴더 또는 기능설계서/정책서 파일경로> |
/product-team-kit:plan-format으로 저장한 초안 폴더 또는 기능설계서/정책서 파일을 발행 전에 검토하는 스킬이다. 템플릿 구조 검사가 아니라 Product Docs SSOT 충돌과 용어 일관성을 2축으로 점검하는 gate다.
Product Docs SSOT는 <outputRoot>/을 제외한 현재 프로젝트의 Markdown 문서 중 제품 정책, PRD/요구사항, 기능/화면 설계, 운영/QA 판단을 담은 문서와, 그 Markdown이 상대경로로 명시 참조한 로컬 resource만 포함한다. 코드, 설정 파일, 빌드 산출물, dependency/vendor, 외부 URL은 SSOT 근거에서 제외한다. <outputRoot>/ 하위 파일은 검토 대상일 수 있지만 SSOT 근거로 사용하지 않는다.
<outputRoot>과 SSOT corpus 범위는 ../../references/config-contract.md를 따라 결정한다. outputRoot의 default는 planning이며, <outputRoot>/**은 항상 SSOT exclude에 자동 포함된다. ssot.include가 지정되면 SSOT corpus를 그 glob 안으로 좁히고, 미지정/빈 배열이면 default Product Team Space/Product Department/Colonova Product/_AI_ 정책서 & 기능설계서/**/*.md를 사용한다. ssot.exclude는 default 제외(.git/, vendor/, node_modules/, build/, dist/, .cache/, generated/)에 누적한다.
판정 기준, 합성 규칙, 2축 점검 기준, 근거 패키지 형식은 references/review-rules.md를 단일 기준으로 따른다. 최종 출력 형식은 references/output-format.md를 따른다. 사람용 리포트 하나로 출력하며 별도 YAML manifest 블록은 사용하지 않는다.
통과는 발견 사항이 없다는 뜻이 아니라, 검토 대상·config·SSOT corpus 탐색·2축 점검·출력 형식이 모두 성립했고 필수 수정/발행 전 확인 항목이 0건이라는 뜻이다.검증 대상 없음으로 처리할 수 있다. 후보가 있었는데 읽지 못했거나 비용 때문에 생략한 경우는 통과 금지다.plan-review는 초안, Product Docs SSOT, 팀 문서 export, linked resource, 외부 시스템을 수정하거나 게시하지 않는다. 필요한 최소 수정/확인 조건만 제시한다.각 파일은 실제 필요한 sub-step에서만 읽는다. dispatch 시작 시점에 묶어 읽지 않는다. 종료 분기에서 안 쓰는 파일을 읽으면 토큰 낭비이며 금지한다.
| 파일 | 읽는 시점 | 용도 |
|---|---|---|
<project-root>/.product-team-kit/config.json | 사전 점검 1 시작 | strict-exit 판정, outputRoot/ssot 확정 |
| 검토 대상 본문 + 짝문서 | 사전 점검 2 입력 타입 검증 통과 후 | 타입 판정 보강, 키워드 추출, 2축 점검 입력 |
references/review-rules.md | 키워드 추출 직후 (## SSOT corpus 선택 규칙 + ## 2축 점검 기준 + ## 발견 사항 필드 한 번에) | corpus listing, main A축 점검, B worker prompt inline |
| SSOT corpus 본문 | 키워드 매칭 후보 ≥1개 확인 후 | main A축 SSOT 충돌 점검 |
references/output-format.md | 종료 출력 직전 (분기 확정 후 1회) | "올바른 검토 대상이 아님" / 결과 3종 리포트 |
타입 판정 룰은 references/review-rules.md의 ## 검토 대상 타입 판정을 단일 진실 소스로 따른다. 본문 read 후 룰을 적용한다.
분기별 실제 읽기 순서:
config.json → output-format.md → 종료 (set-config 안내)config.json → 본문 (타입 판정) → output-format.md → 종료config.json → 본문/짝문서 → review-rules.md → output-format.md → 종료 (worker spawn 안 함)config.json → 본문/짝문서 → review-rules.md → corpus 후보 listing 후 0건 확인 → main A축 "검증 대상 없음" 처리 + B worker(용어 일관성) 본문 점검 → merge → output-format.mdconfig.json → 본문/짝문서 → review-rules.md → corpus listing → corpus 본문 read → main A축 점검 + B worker(용어 일관성) → merge → output-format.md실행 중 사용자에게 보이는 narration은 구조화된 step 헤더 한 줄로만 표시한다. 각 step 진입 시점에 정확히 한 줄을 출력한다.
형식: Step N/M: <step 이름> (M은 분기별 총 step 수, 사전 결정)
분기별 step 시퀀스 (config 검증은 모든 분기에서 silent — 헤더 미출력):
output-format.md 종료 템플릿만 출력.Step 1/2: 입력 타입 검증 → Step 2/2: 종료 출력Step 1/3: 검토 대상 read → Step 2/3: SSOT corpus 탐색 → Step 3/3: 종료 출력Step 1/5: 검토 대상 read → Step 2/5: SSOT corpus 탐색 → Step 3/5: 2축 점검 (A 검증 대상 없음 + B 본문) → Step 4/5: merge → Step 5/5: 리포트 출력Step 1/5: 검토 대상 read → Step 2/5: SSOT corpus 탐색 → Step 3/5: 2축 점검 (A + B 병렬) → Step 4/5: merge → Step 5/5: 리포트 출력step 헤더 외 금지 항목 (전부 출력 금지):
config.json 먼저 확인, 검토 대상 파일 2개 동시 read, output-format.md 읽는다config 정상, 직접 관련 SSOT 후보 발견, 상위 20줄 인덱스 스캔, 파일이 비어있는지 직접 확인, 두 파일 모두 빈 파일2축 점검 완료, 최종 리포트 출력, 이제 ~ 한다Read/Bash/Agent 툴 호출은 Claude Code UI가 자동 표시하므로 텍스트 보고 불필요. Tool 호출 사이에 진행 안내 텍스트 삽입 금지.
분기 결정 시점:
output-format.md 종료 템플릿만 출력한다.Step 1/M: ...)는 config 검증 통과 후 분기가 확정 가능한 시점에 출력한다.
Step 1/2: 입력 타입 검증 (총 M=2, Step 2/2: 종료 출력).Step 1/M: 검토 대상 read (M은 분기별 표대로).## 사전 점검 1검토 대상 read (또는 입력 타입 fail 분기에서 입력 타입 검증).사용자가 보는 turn 마지막 결과는 Step N/N (마지막 step) 직후 references/output-format.md 템플릿 1회 출력이다.
/product-team-kit:plan-review <초안 폴더 또는 기능설계서/정책서 파일경로>$plan-review <초안 폴더 또는 기능설계서/정책서 파일경로>예시:
/product-team-kit:plan-review planning/결제기능--YYYY-MM-DD-HHMMSS//product-team-kit:plan-review planning/결제기능--YYYY-MM-DD-HHMMSS/결제기능_기능설계서.md다음 의도에서는 plan-review를 선택한다.
다음 의도에서는 plan-review를 선택하지 않는다.
plan-format사용자가 "정리하고 검토"를 함께 요청했지만 기능설계서/정책서 초안 경로가 아직 없으면 plan-review를 먼저 호출하지 않는다. 먼저 plan-format으로 초안을 저장한 뒤 저장 경로를 대상으로 검토한다.
진행 표시 매핑: 1번 = silent (헤더 미출력), 2~4번 = Step 1/M: 검토 대상 read (입력 타입 fail 분기는 Step 1/2: 입력 타입 검증). step 헤더는 각 step 진입 시점에만 1회 출력하고 sub-action narration은 추가하지 않는다 (## 진행 표시 원칙).
이 단계에서 읽는 파일: config.json (1번), 검토 대상 본문 + 짝문서 (2~4번 통과 후). review-rules.md·SSOT corpus·output-format.md는 아직 읽지 않는다.
.product-team-kit/config.json 존재 여부를 확인하고 outputRoot, ssot.include, ssot.exclude를 확정한다. 파일 없음, JSON 파싱 실패, version 미일치, outputRoot 검증 거부는 치명 설정 오류로 즉시 종료하고 set-config 사용을 안내한다. 종료 출력은 output-format.md를 이 시점에 read해 적용한다. 비치명 검증 거부만 default fallback과 [설정 경고]로 처리한다.references/review-rules.md의 ## 검토 대상 타입 판정 룰로 확인한다 (파일명 stem suffix *_기능설계서.md/*_정책서.md, H1 제목, 폴더 입력 시 내부 ≥1개 매칭). 다른 문서 타입(상위설계서 등)이면 검토를 수행하지 않고 output-format.md를 read해 올바른 검토 대상이 아님 템플릿으로 종료한다. 본 룰을 본문 read만으로 평가할 수 없을 때만 review-rules.md의 본 섹션을 미리 read한다 (이외 SSOT corpus·review-rules.md 본 섹션 외부는 read하지 않음).plan-format 산출 파일명인 [안전기능명]_기능설계서.md / [안전기능명]_정책서.md의 같은 stem을 우선해 짝문서를 찾는다.검증 한계에 짝문서 없음을 기록한다. 검토 대상이 명시적으로 다른 문서의 정책/기능 판단에 의존하면 분류를 필수 수정 또는 발행 전 확인으로 올린다.각 축은 dispatch에서 확정한 검토 대상 본문과 필요한 SSOT 근거 패키지로 점검한다. 상세 기준은 references/review-rules.md의 ## 2축 점검 기준 섹션을 단일 진실 소스로 따른다.
발견 사항은 분류(필수 수정 / 발행 전 확인 / 참고)와 함께 기록한다. 마커([미정]/[가정]/[확인 필요]/[충돌 후보]) 자체는 plan-format 책임 영역이며 본 검토는 분류 대상으로 삼지 않는다. 단, 마커 본문이 SSOT 근거와 충돌하면 A축 발견으로, 마커 본문 안에서 같은 대상을 가리키는 표기가 어긋나면 B축 발견으로 기록할 수 있다.
dispatch → main A축 점검 + B worker(용어 일관성) 병렬 → merge 3단계로 동작한다. SSOT corpus는 main이 보유·사용하므로 A축은 main이 직접 점검하고, 본문만 보는 B만 worker로 분리한다. 병렬 호출 환경이 없거나 입력이 작아 분리 비용이 더 큰 경우 단일 패스 fallback으로 진행해도 결과 형식은 동일해야 한다.
진행 표시 매핑: dispatch의 SSOT corpus 탐색·매칭 = Step 2/M: SSOT corpus 탐색. main A축 점검 + B worker 병렬 = Step 3/M: 2축 점검. merge = Step 4/M: merge. 종료 출력 = Step 5/M: 리포트 출력 (## 진행 표시 원칙).
읽는 파일: 사전 점검에서 읽은 config.json·본문·짝문서 재사용. review-rules.md는 SSOT corpus 선택 단계 직전에 read. SSOT corpus 본문은 키워드 매칭 후보 ≥1개일 때만 read.
분류·고정 항목 결정 + A축 SSOT 충돌 점검을 수행한다. B 용어 일관성 본문 점검은 worker가 담당한다.
outputRoot, ssot.include, ssot.exclude) — ../../references/config-contract.md 따름. 치명 설정 오류는 즉시 종료하고 set-config 안내.output-format.md를 read해 올바른 검토 대상이 아님 템플릿으로 종료.## 사전 점검 4단계 그대로).review-rules.md read — 이 시점에서 한 번만. ## SSOT corpus 선택 규칙 + ## 2축 점검 기준을 함께 적용한다. A축·SSOT 선택 규칙은 main 자체 사용, B는 worker prompt에 inline.review-rules.md의 ## SSOT corpus 선택 규칙 따름.review-rules.md 규칙 4.5.review-rules.md의 (a) 추출 성공 + 매칭 0건 / (b) 추출 실패 처리. 추출 실패는 worker spawn 없이 즉시 수정 필요 결과로 종료한다. 이 시점에 output-format.md를 read해 적용.review-rules.md의 ## 2축 점검 기준 → A. SSOT 충돌 + ## 발견 사항 필드 7 필드 형식으로 발견 사항 list 작성. 발견 0건이면 내부적으로 no-findings 동등 처리. corpus 0건(추출 성공)이면 발견 0건 + A축 검증 대상 없음으로 표기.review-rules.md의 ## 2축 점검 기준 → B. 용어 일관성과 ## 발견 사항 필드를 worker prompt에 inline.읽는 파일: 없음. dispatch에서 읽은 review-rules.md·본문을 worker prompt에 inline 포함. worker가 직접 파일 read하지 않는다. SSOT corpus는 worker에 전달하지 않는다 (A축은 main 직접 점검).
main이 단일 어시스턴트 메시지에 Agent tool 호출 1 block 발행한다. main A축 점검과 B worker 호출은 동시에 진행 가능하다. worker 호출이 회신될 때까지 merge로 가지 않는다.
호출 환경에서 Agent 호출이 불가능하면 (Codex, MCP 단일 패스 환경) 단일 패스 fallback으로 main이 2축을 순차 점검한다. 결과 형식은 동일해야 한다.
| 책임 | 입력 |
|---|---|
| main (A축 SSOT 충돌) | dispatch 결과 + SSOT corpus 본문 + review-rules.md A축 (자체 사용) |
plan-review-terminology-worker (B축) | dispatch 결과 (본문만) + review-rules.md B축 inline + ## 발견 사항 필드 inline |
worker는 references/review-rules.md의 ## 발견 사항 필드 7 필드 표 형식으로 발견 사항만 return한다. 발견 0건 시 응답 끝에 <!-- worker-flag: no-findings --> 한 줄 명시.
main A축 점검 결과도 동일한 7 필드 형식을 따른다. 발견 0건이면 내부적으로 no-findings 동등 상태를 기록한다.
worker는 합성·결과 3종 판정·리포트 작성을 하지 않는다. 본문 수정·파일 write도 하지 않는다. 모두 main의 merge가 일괄 처리한다.
읽는 파일: 없음. dispatch에서 읽은 review-rules.md를 재사용 (합성 규칙·결과 3종 기준). 종료 출력 직전에만 output-format.md를 read.
출력은 2층 구조다 (output-format.md의 ## 출력 2층 구조). 상단은 dedup·보수 합성된 통합 list, 하단은 agent별 원본 발견 raw. 두 면을 같은 리포트에 출력한다.
references/review-rules.md의 ## 합성 규칙 적용 (위치+제목+근거 정규화 dedup, NFC, 보수 분류). 축·내부 ID 컬럼은 두지 않는다.references/review-rules.md의 ## 결과 3종 기준 + ## 보수 합성 우선순위 적용 (상단 list 기준).<!-- worker-flag: no-findings --> + 완료 전 자체 점검 통과 → 통과.검증 한계에 기록 후 보수 합성. main A축 발견은 main이 직접 7 필드 형식으로 작성하므로 retry 대상이 아니다.review-rules.md ## 발견 사항 필드 → 표 출력 형식 (GFM)을 어겼으면 (separator 행 누락, leading/trailing | 누락, cell 안 unescaped |로 컬럼 어긋남, backtick·HTML 안 unescaped | 포함) main이 cell escape·separator 행 보정만 적용해 하단 블록에 노출한다. cell escape는 review-rules.md ## 발견 사항 필드 → 표 출력 형식 (GFM)의 main 보정 단계 cell escape 알고리즘을 그대로 따른다 (backtick·HTML 안 |도 escape 대상). 보정 적용 사실은 검증 한계에 <worker> 출력 형식 보정 적용 한 줄 남긴다. 보정해도 컬럼 수가 맞지 않으면 해당 worker 블록을 fenced ```text ``` 원본 텍스트로 노출하고 사유를 검증 한계에 명시. main A축, 상단 통합 list도 동일 GFM 형식과 escape 알고리즘을 따른다 (main이 자기 출력에도 같은 escape 적용).references/output-format.md 템플릿으로 사람용 리포트 출력. 템플릿을 감싼 text ... 또는 text ... fence는 docs 가독성용이므로 출력에 포함하지 않는다. fence 내부 본문만 raw markdown으로 출력한다. 설정 경고는 dispatch 모은 목록 사용.최종 리포트를 출력하기 직전에 아래를 확인한다. 하나라도 실패하면 references/review-rules.md의 ## 통과 금지 조건과 ## 보수 합성 우선순위를 적용해 결과를 보수적으로 조정하고, 실패 이유를 검증 한계 또는 지정된 종료 템플릿에 남긴다.
.product-team-kit/config.json 치명 오류가 없고, 비치명 경고는 [설정 경고]에 모았다.SSOT corpus 0건 (관련 Markdown 부재)로 명시했다.읽지 않은 관련 후보/검증 한계에 남겼다.검증 한계에 남겼다.통과라면 필수 수정·발행 전 확인이 0건이고, 통과 금지 조건에 해당하는 신호가 없다.references/output-format.md 순서와 라벨을 따른다.현재 대화 컨텍스트는 근거가 아니다. 대화에서 알게 된 배경, 의도, 작성 당시 판단은 검토 대상 파일 또는 SSOT 근거에 없으면 근거 부족으로 본다.
references/review-rules.md만 따른다.references/output-format.md만 따른다. 이 파일은 종료 분기가 확정된 직후 1회만 read한다. YAML manifest 블록은 사용하지 않는다.<outputRoot>/ 산출물은 review target으로만 읽고 SSOT 근거로 승격하지 않는다.[설정 경고] 블록 한 번으로 표기한다. 경고 포맷은 ../../references/config-contract.md를 따른다.