plan-review

name	plan-review
description	구현 계획 문서를 6가지 관점으로 순차 리뷰하고, 수동 텍스트 승인 루프로 의견/승인을 받아 즉시 반영한 뒤 반복 루프를 수행한다.

Plan Review

구현 계획 문서를 6가지 관점으로 검토하되, 결과를 한 번에 제출하지 않는다. 각 관점마다 요약을 먼저 제시하고 수동 텍스트 승인 루프로 승인 / 승인 안 함 / 수정 지시: ...를 받아 즉시 문서에 반영한다. 수동으로 선택/승인을 물어야 하는 모든 단계에서 반드시 권장안과 이유를 함께 제시한다. 관점 6(불확실성/애매성 질의)은 Summary 제시 후 [QUESTIONS]를 질문 단위로 하나씩 사용자에게 물어 선택을 받은 뒤 답변을 반영한다. 단, 추가 반영 제안이 없으면 해당 관점은 자동 PASS 처리하고 다음 관점으로 진행한다. 6개 관점을 모두 처리한 뒤 변경이 발생했으면 업데이트된 문서 기준으로 다시 1번 관점부터 루프를 반복한다.

사용법

• 계획 문서 경로가 주어지면 해당 문서를 리뷰한다.
• 경로가 없으면 리뷰할 계획 문서 경로를 요청한다.

수동 텍스트 승인 루프 규칙

• 승인 요청은 항상 수동 텍스트로 진행한다.
• 승인 요청의 허용 입력은 아래 3개만 사용한다.
  1. 승인: 제안된 권장 반영안으로 진행
  2. 승인 안 함: 이번 제안을 반영하지 않고 다음 단계로 진행
  3. 수정 지시: <내용>: 지시를 반영한 수정안을 다시 제시하고 재승인
• 승인 요청을 제시할 때는 항상 권장안과 권장 이유를 함께 제시한다.
• Other(다른 지시) 텍스트가 입력되면 수정 지시와 동일하게 처리한다.
• 입력이 불명확하면 확정하지 말고 허용 입력(승인, 승인 안 함, 수정 지시: ...)으로 재입력을 요청한다.
• 관점 6에서 [QUESTIONS]가 있으면 Summary 직후 질문을 한 번에 묶지 말고 번호 순서대로 하나씩 물어본다.
• 관점 6 질문을 제시할 때도 질문마다 권장 선택지와 권장 이유를 함께 제시한다.
• 관점 6 질문 응답은 선택: <번호 또는 선택지 텍스트> 형식으로 받고, 답변 직후 다음 질문으로 진행한다.
• 관점 6 질문이 모두 끝난 뒤 답변 반영안을 제시하고 공통 승인 요청(승인 / 승인 안 함 / 수정 지시: ...)을 수행한다.

실행 워크플로우

1단계: 계획 문서 읽기

$ARGUMENTS에서 파일 경로를 추출한다.

• 인자가 없으면: "리뷰할 계획 문서의 경로를 입력해주세요. 예: docs/plan/feature.md" 라고 안내하고 중단한다.
• 인자가 있으면: 해당 파일을 읽는다. 파일이 존재하지 않으면 에러를 안내하고 중단한다.
• 읽은 원본을 문서 v1로 고정한다.

2단계: 인터랙티브 리뷰 루프 초기화

• current_doc = 문서 v1
• iteration = 1
• max_iterations = 3 (권장 안전장치)
• applied_changes_log = []
• iteration_summaries = []

3단계: 관점별 순차 리뷰 + 즉시 반영 (Iteration N)

각 iteration에서 아래 6개 관점을 순서대로 처리한다. 각 관점 처리 절차는 동일하다.

1. 해당 관점 분석을 current_doc 기준으로 실행한다.
2. 분석 결과의 [PROPOSED_UPDATES]를 확인하고, 관점 6인 경우 [QUESTIONS] 존재 여부를 함께 확인한다.
3. [PROPOSED_UPDATES]가 없음이고 (관점 6이 아니거나 [QUESTIONS]가 질의 필요 없음)이면:
   • 해당 관점을 PASS_NO_ACTION으로 기록한다.
   • 사용자 선택 단계 없이 다음 관점으로 진행한다.
4. [PROPOSED_UPDATES]가 있거나 (관점 6이고 [QUESTIONS]가 존재하면):
   • 사용자에게 아래 형식으로 요약을 제시한다.
   • 관점 6이고 [QUESTIONS]가 있으면 질문-선택 루프를 먼저 수행한다. (질문 1개씩)
   • 승인 요청 또는 질문 제시 시마다 권장안과 권장 이유를 포함한다.
   • 수동 텍스트로 승인 / 승인 안 함 / 수정 지시: ...를 받는다.
   • 승인: 권장 반영안을 즉시 current_doc에 반영한다.
   • 승인 안 함: 반영하지 않고 다음 관점으로 진행한다.
   • Other(다른 지시) 또는 수정 지시: ...: 지시를 반영한 수정안을 다시 제시하고 동일 방식으로 재승인을 받는다.
5. 반영/패스 내역을 applied_changes_log에 기록한다.

승인 질문 포맷 (공통)

[PROPOSED_UPDATES]가 있을 때만 아래 선택을 받는다.

권장안과 권장 이유를 먼저 제시한 뒤 아래 선택을 받는다.

1. 승인: 권장 반영안 적용
2. 승인 안 함: 이번 관점 제안 미반영
3. 수정 지시: <내용> 또는 Other(다른 지시): 사용자 지시를 반영해 수정안 재승인

Other(다른 지시) 또는 수정 지시: ...를 입력하면 추가 지시를 반영한 초안을 다시 보여주고 동일 방식으로 최종 확인을 받는다.

관점 6 질문 응답 포맷 (전용)

관점 6에서 [QUESTIONS]가 있을 때는 질문을 하나씩 제시하고 아래 형식으로 응답을 받는다.

• 질문마다 먼저 권장 선택지와 권장 이유를 제시한다.
• 선택: <번호>
• 선택: <선택지 텍스트>

사용자에게 보여줄 출력 템플릿 (공통)

### Iteration {N} - 관점 {번호}: {관점명}

**Summary**
- {핵심 포인트 1}
- {핵심 포인트 2}

**제안 반영안**
- {문서에 추가/수정할 내용 요약}
- 권장 반영 위치: {INLINE 또는 ADDENDUM}

**권장 선택**
- 권장안: {승인 / 승인 안 함 / 수정 지시: <요약>}
- 권장 이유: {왜 이 선택이 현재 iteration에 최적인지}

**승인 요청**
- 수동 텍스트로 `승인`, `승인 안 함`, `수정 지시: ...` 중 하나를 입력

[PROPOSED_UPDATES]가 없을 때는 아래처럼 간단히 출력한다.

### Iteration {N} - 관점 {번호}: {관점명}

**Summary**
- {핵심 포인트}

**결과**
- PASS_NO_ACTION (추가 반영 제안 없음)

관점 6에서 [QUESTIONS]가 있을 때는 아래 템플릿으로 질문을 하나씩 진행한다.

### Iteration {N} - 관점 6: 불확실성/애매성 질의

**Summary**
- {핵심 포인트 1}
- {핵심 포인트 2}

**질문 {i}/{total}**
- 불확실 항목: {항목}
- 개발자 질문: {질문}
- 선택지:
  1. {선택지 A}
  2. {선택지 B}
  3. {선택지 C}
- 필요 이유(리스크): {리스크}
- 우선순위: {CRITICAL/HIGH/MEDIUM/LOW}
- 권장 선택: {1 또는 선택지 텍스트}
- 권장 이유: {왜 이 선택이 리스크/범위/일정 기준으로 최적인지}

**응답 요청**
- `선택: 1` 또는 `선택: {선택지 텍스트}` 중 하나를 입력

질문 루프 완료 후에는 답변 반영안을 요약해 공통 승인 요청 템플릿으로 이어간다.

---

관점 1: 문서 정합성

분석 프롬프트:

아래 구현 계획 문서를 프로젝트의 기존 문서와 비교하여 정합성을 검토하라.

## 계획 문서
{current_doc}

## 검토 절차

1. 프로젝트 루트에서 다음 파일/디렉토리를 탐색한다:
   - CLAUDE.md, AGENTS.md (프로젝트 루트 및 .claude/)
   - docs/ 디렉토리
   - 프로젝트 구조 문서 후보 (`project-structure`, `architecture`, `folder-structure`, `codebase-structure`, `directory-layout` 관련 파일명/헤더, 위치 고정 금지)
   - plans/ 디렉토리
   - README.md
   - 기타 컨벤션 문서 (.github/, CONTRIBUTING.md 등)

2. 각 문서에 대해 다음을 확인한다:
   - 계획이 기존 컨벤션/규칙과 충돌하는 부분
   - 계획이 기존 문서에서 정의한 것을 누락한 부분
   - 계획이 참조하는 문서/경로가 실제로 존재하는지
   - 프로젝트 구조 문서가 있으면 계획의 모듈 경계/디렉토리 경로/역할 정의와 일치하는지
   - 프로젝트 구조 문서가 없으면 부재 사실을 [NOTE]에 명시

## 출력 형식

[SUMMARY]
- 핵심 요약 2~5개

[ISSUES]
- [CONFLICT] {설명} — {근거 파일:라인}
- [GAP] {설명} — {참조 문서}
- [NOTE] {설명}

[PROPOSED_UPDATES]
- 문서에 반영 가능한 구체 문장/항목 제안
- 제안이 없으면 `없음`으로 명시

---

관점 2: 웹 검증

분석 프롬프트:

아래 구현 계획 문서에서 기술적 주장을 추출하고 웹 검색으로 검증하라.

## 계획 문서
{current_doc}

## 검토 절차

1. 기술적 주장(라이브러리 API, 버전, 제한사항, 외부 서비스 동작)을 추출한다.
2. 각 주장에 대해 공식 문서 중심으로 검증한다.
3. 기술적 주장이 없으면 검증 대상 없음을 명시한다.

## 출력 형식

[SUMMARY]
- 핵심 요약 2~5개

[CLAIMS]
| # | 주장 | 판정 | 근거 |
|---|------|------|------|
| 1 | {주장} | VERIFIED / OUTDATED / INCORRECT / UNVERIFIED | {출처} |

[PROPOSED_UPDATES]
- OUTDATED/INCORRECT/UNVERIFIED 해소를 위한 문서 수정안
- 제안이 없으면 `없음`으로 명시

---

관점 3: 코드 실현 가능성

분석 프롬프트:

아래 구현 계획 문서를 현재 프로젝트 코드베이스와 대조하여 실현 가능성을 평가하라.

## 계획 문서
{current_doc}

## 검토 절차

1. 프로젝트 구조, 언어/프레임워크, 설정 파일을 파악한다.
2. 프로젝트 구조 문서 후보 (`project-structure`, `architecture`, `folder-structure`, `codebase-structure`, `directory-layout`)가 있으면 함께 읽어 기준 구조를 파악한다. (예: `AGENTS.md`, `README.md`, `docs/`, `plans/`)
3. 계획에서 언급한 파일/모듈/패턴의 실제 존재 여부와 프로젝트 구조 문서와의 정합성을 확인한다.
4. 의존성/설정 누락과 영향 범위를 평가한다.

## 출력 형식

[SUMMARY]
- 핵심 요약 2~5개

[FEASIBILITY]
- 실현 가능성: HIGH / MEDIUM / LOW
- 근거:
  - {항목}: {설명}

[IMPACT]
- 계획에 명시되지 않은 영향 파일/영향 설명

[PROPOSED_UPDATES]
- 실현 가능성 향상을 위한 문서 수정안
- 제안이 없으면 `없음`으로 명시

---

관점 4: 테스트 계획 현실성/커버리지

분석 프롬프트:

아래 구현 계획 문서에 테스트 계획이 있는지 확인하고, 실서비스 유사 테스트 우선순위와 커버리지를 평가하라.

## 계획 문서
{current_doc}

## 검토 절차

1. 테스트 계획(테스트 목표, 범위, 시나리오, 환경, 데이터, 통과 기준) 존재 여부를 확인한다.
2. 테스트 우선순위를 평가한다.
   - 최우선: 실서비스와 유사한 검증 (예: 실제 의존성 연동 통합 테스트, E2E, 스테이징/프리프로덕션 리허설, 실제 트래픽 흐름 기반 시나리오)
   - 차순위: 단위 테스트, Mock 기반 테스트
3. 구현 계획의 핵심 기능/리스크/엣지케이스를 테스트 계획이 얼마나 커버하는지 매핑한다.
4. 실서비스 유사 테스트가 없거나 비중이 낮으면 갭을 명시하고 보강안을 제시한다.
5. 테스트 계획 자체가 없으면 반드시 추가 템플릿을 제안한다.

## 출력 형식

[SUMMARY]
- 핵심 요약 2~5개

[TEST_PLAN_STATUS]
- 존재 여부: PRESENT / PARTIAL / MISSING
- 우선순위 적절성: HIGH / MEDIUM / LOW
- 총평: {한 줄}

[COVERAGE]
| # | 구현 계획 항목 | 테스트 계획 반영 여부 | 테스트 유형 | 비고 |
|---|----------------|----------------------|-------------|------|
| 1 | {항목} | COVERED / PARTIAL / MISSING | REALISTIC / INTEGRATION / E2E / UNIT / MOCK | {설명} |

[PROPOSED_UPDATES]
- 실서비스 유사 테스트를 최우선으로 반영한 구체 수정안
- 누락된 범위를 채우는 테스트 시나리오 추가안
- 제안이 없으면 `없음`으로 명시

---

관점 5: 계획 품질

분석 프롬프트:

아래 구현 계획 문서의 품질을 7가지 차원에서 평가하라.

## 계획 문서
{current_doc}

## 평가 차원
1. 목표 명확성
2. 접근법 타당성
3. 엣지케이스 고려
4. 리스크 식별
5. 범위 적절성
6. 의존성 파악
7. 완전성

## 출력 형식

[SUMMARY]
- 핵심 요약 2~5개

[SCORES]
| 차원 | 점수 | 평가 |
|------|------|------|
| 목표 명확성 | {1-5} | {한 줄 평가} |
| 접근법 타당성 | {1-5} | {한 줄 평가} |
| 엣지케이스 고려 | {1-5} | {한 줄 평가} |
| 리스크 식별 | {1-5} | {한 줄 평가} |
| 범위 적절성 | {1-5} | {한 줄 평가} |
| 의존성 파악 | {1-5} | {한 줄 평가} |
| 완전성 | {1-5} | {한 줄 평가} |

[PROPOSED_UPDATES]
- 점수 개선을 위한 문서 수정안
- 제안이 없으면 `없음`으로 명시

---

관점 6: 불확실성/애매성 질의

분석 프롬프트:

아래 구현 계획 문서에서 실행 전 반드시 명확해져야 하는 불확실성/애매성을 찾아라.

## 계획 문서
{current_doc}

## 검토 절차

1. 책임 주체, 완료 기준, 범위 경계, 선행조건/의존성, 미확정 의사결정을 점검한다.
2. 개발자에게 물어볼 질문은 반드시 선택지(2~4개)를 포함한 닫힌 질문으로 작성한다.
3. 각 질문의 리스크와 우선순위를 부여한다.
4. 질문은 사용자에게 한 번에 보여주지 말고 하나씩 물어보기 쉽게 독립적으로 작성한다.
5. 불확실성이 없으면 "질의 필요 없음"을 명시한다.

## 출력 형식

[SUMMARY]
- 핵심 요약 2~5개

[QUESTIONS]
| # | 불확실 항목 | 개발자 질문 | 선택지(번호) | 필요 이유(리스크) | 우선순위 | 권장 선택(번호) | 권장 이유 |
|---|-------------|-------------|---------------|-------------------|----------|------------------|----------|
| 1 | {항목} | {질문} | 1) {옵션A} / 2) {옵션B} / 3) {옵션C} | {리스크} | CRITICAL/HIGH/MEDIUM/LOW | {1/2/3} | {권장 근거} |

[PROPOSED_UPDATES]
- 질문별 선택 결과를 반영한 문서 수정안 (INLINE 또는 ADDENDUM)
- 제안이 없으면 `없음`으로 명시

---

4단계: Iteration 종료 조건 판단

Iteration N에서 6개 관점을 처리한 뒤 다음을 판단한다.

• 이번 iteration에서 승인으로 실제 반영된 항목이 1건 이상이면:
  • iteration += 1
  • 업데이트된 current_doc 기준으로 관점 1부터 다시 루프
• 반영된 변경이 0건이면:
  • 루프 종료 (문서 안정화)
• iteration > max_iterations이면:
  • 루프 종료 후 경고를 리포트에 기록한다.

5단계: 최종 리포트 출력 (옵션)

루프 종료 후 기본은 간단 완료 요약만 출력한다.

• 기본 출력: 반복 횟수, 반영 건수, PASS_NO_ACTION 건수, 남은 리스크 한 줄
• 사용자가 "최종 리포트 보여줘"를 요청한 경우에만 아래 전체 템플릿을 출력한다.

# Plan Review Report

**문서**: {파일 경로}
**일시**: {현재 날짜/시간}
**반복 횟수**: {iteration_count}

## Overall Verdict: {PASS / CONCERNS / FAIL}

판정 기준:
- **PASS**: 최종 iteration에서 심각 이슈 없음, 미해결 질의 없음
- **CONCERNS**: 주의 이슈 존재 또는 미해결 질의 존재
- **FAIL**: INCORRECT 주장, 실현 불가, 핵심 충돌, CRITICAL 질의 미해결

## Iteration Summary
- Iteration 1: {핵심 변화}
- Iteration 2: {핵심 변화}
- ...

## Applied Changes Log
1. Iteration {N} / 관점 {번호} / {APPLY 방식} / {반영 요약}
2. ...

## Final Document Notes
- 최종 문서에서 남은 리스크
- 개발자 추가 확인 필요 항목

## Recommendations
1. [CRITICAL/HIGH/MEDIUM/LOW] {권고사항}
2. ...

최종 리포트는 "무엇을 발견했는지"보다 "무엇을 사용자 선택으로 반영했고, 현재 문서 상태가 어떤지"를 중심으로 정리한다.