| 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
phase_config: string
disposition_set: string
diverge_claims: list
challenge_results: list
response_results: list
review_summary: object
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
- from: complexity-decide → to: domain-process
- from: complexity-decide → to: synthesis
- from: domain-process → to: extract-learnings
- from: diverge → to: challenge
- from: challenge → to: challenge-response
- from: challenge → to: synthesis
- from: challenge-response → to: synthesis
- from: synthesis → to: orchestrator-synthesis
- 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
참조
