review

name	review
description	다관점 DD 리뷰 실행 — 여러 관점에서 품질 검증. Use when the user says "리뷰 해줘", "검토해봐", "DD 리뷰", or wants multi-perspective review.
context	main
allowed-tools	["Read","Write","Edit","Glob","Grep","Agent"]
spec-version	2

Review Skill

Skill Type: review Version: 2.1.0 Invocation: AI 내부 호출 (사용자가 "리뷰해줘" 요청 시 자동 활성화) Squad: workspace/squads/review/

---

WHY

코드, 설계, 문서 등 다양한 산출물의 품질을 다관점에서 검증하는 워크플로우. Phase 분리 기반 다관점 DD Review를 실행하여, 발산 에이전트가 가능성 공간을 정의하고, 수렴 에이전트가 반증을 시도하며, 오케스트레이터가 구조화 종합한다. 단일 관점의 사각지대를 Phase 간 교차로 보완하여 의사결정 품질을 높인다.

---

STATE

review_target:       string    # 리뷰 대상물 경로 또는 내용
complexity:          string    # low | medium | high | very-high | domain
phase_config:        string    # phase-skip | phase-1-2-3 | phase-1-2-3-orch
disposition_set:     string    # 사용할 에이전트 세트 (architecture | direction | paper | default)
diverge_claims:      list      # Phase 1 출력 — 가능성 공간 주장 목록
challenge_results:   list      # Phase 2 출력 — 반증 시도 결과
response_results:    list      # Phase 2 응답 — 반박/수용 (Very High만)
review_summary:      object    # Phase 3 종합 — 가능성/위험/긴장/실행 권고
learnings_extracted: list      # 추출된 교훈

STEPS

Step 0: 사전 참조

1. vault/knowledge/learnings.md 읽기 → 기존 교훈 중 이번 대상에 적용되는 것 사전 확인
2. vault/knowledge/quality-gates.md 읽기 → 해당 카테고리(AG/DG/VG) gates 중 이번 대상에 적용되는 것 확인
3. 이전 리뷰 권고 확인 → 같은 initiative/도메인에서 이전 리뷰의 Critical/Recommended 항목 중 미해소 건 확인

이전 리뷰 권고 확인: 미해소 건이 있으면 이번 리뷰 종합에 "이전 미해소 권고" 섹션을 포함한다. 권고 이력은 리뷰 산출물 자체에 기록되므로 별도 추적 파일 없음.

Step 1: 복잡도 판단 + Phase 구성 결정

입력: 리뷰 대상물 (설계 문서, initiative 정의, 아키텍처, 논문 등)

복잡도 → Phase 구성:

대상 카테고리	복잡도	Phase 구성	에이전트
단일 결정/설정 변경	Low	Phase 생략 (단독 분석)	pragmatic-builder
단일 문서/리서치	Medium	Phase 생략 (합의 분류만)	critical-analyst + pragmatic-builder
아키텍처/설계 문서	High	Phase 1+2+3 전체	전원 (4개 DD)
Initiative 정의/리뷰	High	Phase 1+2+3 전체	전원 (4개 DD)
크로스 프로젝트 설계	Very High	Phase 1+2+3 + Orchestrator Synthesis	전원 + 발산 에이전트 응답
학술 논문	Domain	paper.md 고유 프로세스	paper.md 4명

사용자 오버라이드: "전원 리뷰해줘" 또는 "전체 파이프라인으로" → 복잡도 무관하게 전원 참여 + 전체 Phase 강제.

Step 2: 도메인 특화 disposition 확인

workspace/squads/review/agents/ 에서 대상 도메인에 맞는 disposition set이 있는지 확인:

도메인	Disposition Set	상태
학술 논문	paper.md (4명)	검증됨
아키텍처/Initiative	architecture.md (4 DD 에이전트)	활성
방향 정렬	direction.md (4 DD 에이전트, 방향 특화)	활성
콘텐츠	content.md	미작성
대화 품질	conversation.md	미작성

도메인 특화 set이 없으면 → 기본 4 DD 에이전트 사용.

Step 3: Phase 1 — Diverge (High 이상)

참여: exploratory-connector + emergent-advocate (병렬, 독립)

목적: 가능성 공간 정의. "무엇이 가능한가?", "무엇과 연결되는가?"

스폰 프롬프트 구조:

당신은 [DD 전문 — 에이전트 파일에서 복사].

다음 대상물을 분석하세요:
[대상물 경로 또는 내용]

**Phase 1 (Diverge) 규칙**:
- 가능성 공간을 정의하세요. 제한 없이 열어두는 것이 목적입니다.
- 각 주장에 대해 **자가 반증 조건** (이 주장이 틀릴 수 있는 조건)을 반드시 포함하세요.
- 다른 리뷰어의 관점을 예측하거나 참조하지 마세요.

평가 기준:
[도메인별 기준]

출력 형식:
[에이전트별 Output Format + 자가 반증 조건]

Step 4: Phase 2 — Challenge (High 이상)

참여: critical-analyst + pragmatic-builder (Phase 1 출력을 입력으로 수신)

목적: Phase 1 주장에 대한 반증 시도. "그 가능성의 전제가 맞는가?", "실제로 작동하는가?"

핵심 규칙: Phase 1의 핵심 주장 각각에 대해 "틀릴 수 있는 조건"만 생성. 주장을 기각할 수 없음.

스폰 프롬프트 구조:

당신은 [DD 전문 — 에이전트 파일에서 복사].

Phase 1에서 다음 주장들이 제시되었습니다:
[Phase 1 출력 전문]

**Phase 2 (Challenge) 규칙**:
- 각 주장에 대해 "이 주장이 틀릴 수 있는 조건"만 제시하세요.
- 주장을 기각하거나 대안을 제시하는 것이 아닙니다. 반증 조건을 탐색하는 것입니다.
- Phase 1의 자가 반증 조건을 참조하되, 추가 반증 조건을 발견하는 것이 핵심 가치입니다.

반증 시도 형식:
[Phase 1 주장 인용] → [이 주장이 틀릴 조건] → [해당 조건의 현실 가능성: 높음/중간/낮음]

Very High 복잡도 추가: Phase 2 결과를 Phase 1 발산 에이전트에게 다시 전달하여 반박 또는 수용 응답.

Step 4.5: Phase 2 응답 (Very High만)

Phase 2의 반증 시도를 Phase 1 발산 에이전트에게 전달:

• 반박: 반증 조건이 현실에서 성립하지 않는 근거 제시
• 수용: 해당 반증 조건을 인정하고 주장 범위를 조정

Step 5: Phase 3 — Synthesis

실행: 오케스트레이터가 Phase 1+2 (+ Phase 2 응답) 결과를 종합.

출력 구조:

## Review Summary: [대상물]

### 참여 에이전트 + Phase 구성
- Phase 1 (Diverge): [에이전트 목록]
- Phase 2 (Challenge): [에이전트 목록]

### 가능성 (반증되지 않은 것)
Phase 2에서 유효한 반증 조건이 제시되지 않았거나, 발산 에이전트가 성공적으로 반박한 주장.
1. [주장]: [내용] — [합의 수준]

### 위험 (반박되지 않은 반증)
Phase 2의 반증 시도가 발산 에이전트에 의해 반박되지 않은 항목.
1. [반증]: [내용] — [현실 가능성] — [권고 수준: Critical/Recommended/Optional]

### 긴장 (미해소)
양측 모두 유효한 논거를 제시하여 미해소 상태. 사용자 판단 필요.
1. [항목]: [발산 관점] vs [수렴 관점]

### 실행 권고
- [ ] Critical: [반드시 해소]
- [ ] Recommended: [해소 권장]
- [ ] Optional: [선택적]

합의 분류 (Phase 3에서 통합):

분류	정의
Consensus	4명 에이전트 동의
Strong	3명 동의, 1명 미언급 또는 약한 동의
Moderate	2명 동의
Divergence	의견 분기 — 긴장 범주로 보존

Low/Medium 복잡도: Phase 1/2 없이 직접 종합. 기존 합의 분류(Consensus/Strong/Moderate/Divergence) 형식 사용.

Step 5.5: Orchestrator Synthesis (Very High / 사용자 요청 시)

Phase 3 이후, initiative phase와 context를 고려해 실질적 working items 도출.

분류 기준:

카테고리	정의	처리
Actual Blocker	방향 오류 위험 — 다음 ST 진입 전 해소 필수	실행 권고에 포함
Natural Emergence	설계/실행 중 자연히 마주칠 것	언급만, 권고 제외
Premature	현재 phase에 맞지 않는 검증 요구 / 파일럿 없이 측정 불가	기각 사유 명시

판단 기준:

• "이것을 지금 해소하지 않으면 방향 오류로 흘러가는가?" → Actual Blocker
• "설계하면서 자연히 결정이 생기는 구조인가?" → Natural Emergence
• "파일럿/실험 없이 이 기준을 정의하는 것이 의미 있는가?" → Premature

산출물:

### Orchestrator Synthesis

- **Working items** (지금 해야 할 것): [Actual Blockers — 1-3개]
- **Natural emergence** (별도 처리 불필요): [항목들]
- **기각** (현재 phase에 맞지 않음): [항목 + 기각 사유]
- **오케스트레이터 권고**: [전체 방향성 1-2문장]

---

Step 6: Learnings 추출

리뷰 결과 중 도메인 불문 재사용 가능한 교훈이 있으면 workspace/squads/review/vault/knowledge/learnings.md에 추가.

추출 기준: 특정 대상물에 종속되지 않는 일반적 교훈.

Step 6.5: Derived Side Cycle — Quality Gates 피드백

리뷰 findings를 preventable / emergent로 분류하고, preventable findings를 workspace/squads/review/vault/knowledge/quality-gates.md에 반영.

1. 각 finding을 분류:
   - preventable: 기존 원칙/learnings를 따랐으면 방지 가능
   - emergent: Phase 간 교차에서만 발견 가능한 창발적 통찰

2. preventable findings → quality-gates.md 업데이트:
   - 새 gate 추가 (ID 체계: AG-/DG-/VG-/RG-/PG-)
   - 기존 gate 위반 재발 시 적용 이력 업데이트

3. emergent findings → learnings.md에만 (Step 6에서 처리됨)

분류 기준:

질문	YES →	NO →
기존 Vatty 설계 원칙을 따랐으면 방지되었는가?	preventable	emergent 후보
기존 learnings를 적용했으면 방지되었는가?	preventable	emergent 후보
Phase 1 단독 분석에서 발견 가능했는가?	preventable	emergent
Phase 간 교차에서만 발견되었는가?	emergent	preventable

효과 측정: preventable_ratio = preventable_count / total_findings — 감소 추세가 목표.

Step 7: 권고 이행 기록

리뷰 종합(Step 5)의 실행 권고 중 Critical과 Recommended 항목의 이행 여부를 기록한다.

시점: 리뷰 직후가 아니라, 권고를 반영한 작업이 완료된 후.

기록 방식: 리뷰 산출물에 직접 업데이트 (별도 추적 파일 없음).

### 권고 이행 현황 (리뷰 후 업데이트)

| # | 수준 | 권고 | 상태 | 해소 방법/사유 |
|---|------|------|------|--------------|
| 1 | Critical | ... | addressed | D-032에서 반영 |
| 2 | Recommended | ... | deferred | Phase 2에서 처리 예정 |
| 3 | Recommended | ... | rejected | 근거: ... |

Step 7.5: 적응형 학습 기록

리뷰 완료 시 다음 최소 기록을 산출물에 포함:

- 리뷰 유형: [architecture / direction / paper / R&D / ...]
- Phase 구성: [Phase 1+2+3 / Medium(Phase 생략) / Low(단독)]
- Phase 1 주장 수: N개
- Phase 2 반증 시도 수: M개
- 반증되지 않은 주장: K개 (가능성 범주)
- 반박되지 않은 반증: J개 (위험 범주)
- 미해소 긴장: T개
- preventable ratio: preventable / total findings

사례 N≥3 축적 후 Phase 구성별 효과 패턴 분석 → Convention 승격 검토.

---

JUDGMENT

복잡도 → Phase 구성 결정

복잡도	Phase 구성	전환 조건
Low	Phase 생략 (단독 분석)	단일 결정/설정 변경
Medium	Phase 생략 (합의 분류만)	단일 문서/리서치
High	Phase 1+2+3 전체	아키텍처/설계/Initiative 정의
Very High	Phase 1+2+3 + Orchestrator Synthesis	크로스 프로젝트 설계
Domain	고유 프로세스	학술 논문 → paper.md

• 사용자가 "전원 리뷰해줘" 또는 "전체 파이프라인으로" 요청 시 → 복잡도 무관 전원 참여 + 전체 Phase 강제
• Phase 2 결과에서 반증 시도가 모두 낮은 현실 가능성이면 → Phase 2 응답(Very High) 생략 가능
• preventable ratio 감소 추세가 아니면 → quality-gates 보강 필요 신호

---

AGENT DELEGATION

Step	에이전트	위임 내용
Step 3 (Phase 1 Diverge)	exploratory-connector, emergent-advocate	가능성 공간 정의 (병렬, 독립)
Step 4 (Phase 2 Challenge)	critical-analyst, pragmatic-builder	Phase 1 주장에 대한 반증 시도
Step 4.5 (Phase 2 응답)	exploratory-connector, emergent-advocate	반증에 대한 반박/수용 (Very High만)

에이전트 정의: workspace/squads/review/agents/ (도메인 특화) 또는 시스템 에이전트 (agents/)

---

KNOWLEDGE REFS

참조	역할	로드 시점
workspace/squads/review/README.md	프로세스 개요	Step 0
workspace/squads/review/policies/pipeline.md	파이프라인 정책	Step 1 (복잡도 판단)
workspace/squads/review/vault/knowledge/learnings.md	기존 교훈	Step 0 (pre-check)
workspace/squads/review/vault/knowledge/quality-gates.md	품질 게이트 (AG/DG/VG)	Step 0 (pre-check), Step 6.5
vault/knowledge/research/agent-design/multi-perspective-dd-review.md	연구 배경	필요 시

---

에이전트 Phase 배치

Phase 1 (Diverge) — 가능성 공간 정의

에이전트	DD	핵심 질문
exploratory-connector	D2↑ D7↑	"이게 무엇과 연결되나?"
emergent-advocate	D1 D2↑ D7↑	"이게 만들어지면 무엇이 가능해지나?"

Phase 2 (Challenge) — 반증 시도

에이전트	DD	핵심 질문
critical-analyst	D1↑ D2↑	"이 전제가 틀릴 조건은?"
pragmatic-builder	D3 D4↓ D5B↑	"이게 실제로 작동할 조건은?"

선택 알고리즘

1. 대상물의 카테고리 판단
2. 복잡도 판단 (Low/Medium/High/Very High)
3. 카테고리 × 복잡도 → Phase 구성 + 에이전트 셋 결정
4. 사용자 오버라이드 확인
5. 도메인 특화 disposition set 확인 (있으면 우선)

예시

• "이 설계 문서 리뷰해줘" → High → Phase 1+2+3, 전원
• "D-001~D-005 결정 리뷰해줘" → Medium → Phase 생략, critical + pragmatic
• "전체 파이프라인으로 리뷰해줘" → 전원 + 전체 Phase 강제
• "논문 리뷰해줘" → paper.md 4명 (고유 프로세스)

---

FLOW

nodes:
  - id: pre-check
    type: auto
    entry: true
    summary: "사전 참조 — learnings, quality-gates, 이전 리뷰 미해소 건"
    postcondition:
      - "기존 learnings 중 적용 대상이 식별됨"
      - "해당 카테고리 quality-gates가 로드됨"
    side_effects:
      - reads: workspace/squads/review/vault/knowledge/learnings.md
      - reads: workspace/squads/review/vault/knowledge/quality-gates.md

  - id: complexity-decide
    type: auto
    summary: "복잡도 판단 + Phase 구성 + 도메인 특화 disposition 확인"
    postcondition:
      - "complexity가 확정됨 (low|medium|high|very-high|domain)"
      - "phase_config가 확정됨"
      - "disposition_set이 확정됨"
    judgment:
      - condition: "Low/Medium"
        next: synthesis
      - condition: "High/Very High"
        next: diverge
      - condition: "Domain (학술 논문 등)"
        next: domain-process
      - condition: "사용자 오버라이드 (전원)"
        next: diverge
        type: override

  - id: diverge
    type: agent
    agent: agents/exploratory-connector.md, agents/emergent-advocate.md
    summary: "Phase 1 — 가능성 공간 정의 (병렬)"
    output: [diverge-claims]
    postcondition:
      - "각 에이전트가 독립적으로 주장을 생성함"
      - "각 주장에 자가 반증 조건이 포함됨"
      - "diverge_claims가 STATE에 기록됨"

  - id: challenge
    type: agent
    agent: agents/critical-analyst.md, agents/pragmatic-builder.md
    summary: "Phase 2 — 반증 시도 (Phase 1 출력 입력)"
    input: [diverge-claims]
    output: [challenge-results]
    postcondition:
      - "Phase 1 주장 각각에 반증 조건이 제시됨"
      - "각 반증의 현실 가능성(높음/중간/낮음)이 평가됨"
      - "challenge_results가 STATE에 기록됨"
    judgment:
      - condition: "Very High 복잡도"
        next: challenge-response
      - condition: "High 복잡도"
        next: synthesis

  - id: challenge-response
    type: agent
    agent: agents/exploratory-connector.md, agents/emergent-advocate.md
    summary: "Phase 2 응답 — 반박/수용 (Very High만)"
    input: [challenge-results]
    output: [response-results]
    postcondition:
      - "각 반증에 대해 반박 또는 수용이 명시됨"
      - "response_results가 STATE에 기록됨"

  - id: domain-process
    type: auto
    summary: "도메인 특화 프로세스 — paper.md 등 고유 에이전트 세트로 오케스트레이션"
    postcondition:
      - "도메인 특화 에이전트의 분석이 완료됨"
      - "review_summary가 STATE에 기록됨"

  - id: synthesis
    type: auto
    summary: "Phase 3 — 종합 (가능성/위험/긴장/실행 권고)"
    output: [review-summary]
    postcondition:
      - "가능성/위험/긴장/실행 권고가 구조화됨"
      - "합의 분류(Consensus/Strong/Moderate/Divergence)가 완료됨"
      - "review_summary가 STATE에 기록됨"
    judgment:
      - condition: "Very High 복잡도"
        next: orchestrator-synthesis
      - condition: "기본"
        next: extract-learnings

  - id: orchestrator-synthesis
    type: auto
    summary: "Orchestrator Synthesis — Actual Blocker/Natural Emergence/Premature 분류 (Very High만)"
    postcondition:
      - "findings가 Actual Blocker/Natural Emergence/Premature로 분류됨"
      - "Working items(1-3개)이 도출됨"

  - id: extract-learnings
    type: auto
    summary: "도메인 불문 교훈 추출 → learnings.md"
    postcondition:
      - "재사용 가능한 교훈이 식별됨 (0개 가능)"
    side_effects:
      - updates: workspace/squads/review/vault/knowledge/learnings.md

  - id: quality-gates-feedback
    type: auto
    summary: "preventable/emergent 분류 → quality-gates.md 반영"
    postcondition:
      - "findings가 preventable/emergent로 분류됨"
      - "preventable_ratio가 계산됨"
    side_effects:
      - updates: workspace/squads/review/vault/knowledge/quality-gates.md

  - id: record-tracking
    type: auto
    summary: "권고 이행 기록 + 적응형 학습 기록"
    postcondition:
      - "적응형 학습 기록이 산출물에 포함됨"

edges:
  - from: pre-check           → to: complexity-decide
  - from: complexity-decide   → to: diverge             # High/Very High
  - from: complexity-decide   → to: domain-process      # Domain (paper.md 등)
  - from: complexity-decide   → to: synthesis            # Low/Medium
  - from: domain-process      → to: extract-learnings
  - from: diverge             → to: challenge
  - from: challenge           → to: challenge-response   # Very High
  - from: challenge           → to: synthesis            # High
  - from: challenge-response  → to: synthesis
  - from: synthesis           → to: orchestrator-synthesis  # Very High
  - from: synthesis           → to: extract-learnings       # 기본
  - from: orchestrator-synthesis → to: extract-learnings
  - from: extract-learnings   → to: quality-gates-feedback
  - from: quality-gates-feedback → to: record-tracking

참조

• DD 에이전트: agents/critical-analyst.md, agents/pragmatic-builder.md, agents/exploratory-connector.md, agents/emergent-advocate.md
• 도메인 Dispositions: workspace/squads/review/agents/