@su-record/vibe 2.9.1 → 2.9.3

package/{commands/vibe.spec.review.md → skills/vibe.spec.review/SKILL.md}

@@ -1,16 +1,29 @@
-# /vibe.spec.review - SPEC Quality Review
+---
+name: vibe.spec.review
+tier: core
+description: "Review and enhance an existing SPEC with GPT/Gemini cross-validation. Runs 100-point quality gate (loop until perfect or stuck), Race Review with convergence-based termination (no round cap), optional Codex adversarial review, Review Debate Team, and final user checkpoint. Must use this skill after vibe.spec completes, or when the user says 'review spec', '스펙 리뷰'."
+triggers: ["spec review", "review spec", "SPEC 리뷰", "명세 리뷰", race review]
+priority: 80
+chain-next: []
+---
+
+# vibe.spec.review — SPEC Quality Review
 
 Review and enhance SPEC with GPT/Gemini cross-validation.
 
-**Purpose:** Run this command in a NEW session after `/vibe.spec` to ensure accurate review execution.
+**Purpose:** Run this skill after `vibe.spec` to ensure accurate review execution. For large contexts, invoke in a new session.
 
 ---
 
 ## Usage
 
-```bash
-/vibe.spec.review "feature-name"
+This skill is automatically called in Phase 4 of the `/vibe.spec` orchestrator. If direct invocation is needed:
+
 ```
+Load skill `vibe.spec.review` with feature: "feature-name"
+```
+
+Or via natural language trigger: "스펙 리뷰", "review spec", "명세 리뷰".
 
 **Prerequisites:**
 - SPEC file exists: `.claude/vibe/specs/{feature-name}.md` (single) or `.claude/vibe/specs/{feature-name}/_index.md` (split)
@@ -20,30 +33,37 @@ Review and enhance SPEC with GPT/Gemini cross-validation.
 
 ## Codex Plugin Integration
 
-> **Codex 플러그인 감지**: 워크플로우 시작 시 아래 명령으로 자동 감지.
+> **Codex plugin detection**: Auto-detected at workflow start with the command below.
 >
 > ```bash
 > CODEX_AVAILABLE=$(node "{{VIBE_PATH}}/hooks/scripts/codex-detect.js" 2>/dev/null || echo "unavailable")
 > ```
 >
-> `available`이면 `/codex:adversarial-review` 자동 호출. `unavailable`이면 기존 GPT+Gemini 워크플로우로 동작.
+> If `available`, `/codex:adversarial-review` is automatically invoked. If `unavailable`, falls back to the existing GPT+Gemini workflow.
 
 ---
 
 > **⏱️ Timer**: Call `getCurrentTime` tool at the START. Record the result as `{start_time}`.
 
+**`.last-feature` pointer update** (immediately after Timer):
+
+```
+Write ".claude/vibe/.last-feature" ← feature-name (one line)
+If the value is already the same, no-op.
+```
+
 ## Workflow
 
 ```
-/vibe.spec "feature" → SPEC created
+/vibe.spec "feature" → SPEC created (Phase 3)
         ↓
-    /new (new session)
-        ↓
-/vibe.spec.review "feature" → Quality validation + GPT/Gemini review
+Phase 4: vibe.spec.review skill (this) → Quality validation + GPT/Gemini review
         ↓
     /vibe.run "feature"
 ```
 
+**For large contexts**: After `/new`, re-enter `/vibe.spec "feature"` → Smart Resume will start from Phase 4.
+
 ---
 
 ## File Reading Policy (Mandatory)
@@ -103,9 +123,9 @@ Extracted info:
 
 ---
 
-## Step 2: Quality Validation (95-Point Gate)
+## Step 2: Quality Validation (100-Point Gate)
 
-**🚨 MANDATORY: Score must be ≥ 95 to proceed**
+**🚨 MANDATORY: Score must reach 100 to proceed. Loop until perfect or stuck.**
 
 ### 2.1 Quality Checklist
 
@@ -121,23 +141,56 @@ Extracted info:
 | **Security** | Auth/permission requirements specified | 10% |
 | **Performance** | Response time/load requirements specified | 10% |
 
-### 2.2 Quality Gate Loop
+### 2.2 Quality Gate Loop (No Round Cap)
 
 ```python
-max_iterations = 3
 iteration = 0
+prev_score = -1
 
-while iteration < max_iterations:
+while True:
     iteration += 1
     score = calculate_quality_score(spec, feature)
 
-    print(f"━━━ Quality Check [{iteration}/{max_iterations}] ━━━")
+    print(f"━━━ Quality Check [{iteration}] ━━━")
     print(f"Score: {score}/100")
 
-    if score >= 95:
-        print("✅ Quality Gate PASSED")
+    if score >= 100:
+        print("✅ Quality Gate PASSED (100/100)")
         break
 
+    # Auto-fixer hit a wall → ask the user (prevents runaway AND respects 100 target)
+    if score == prev_score:
+        missing_items = identify_missing_items(spec)
+        print(f"⚠️ Auto-fixer limit reached: stuck at {score}/100")
+        print(f"Remaining items require human input:")
+        for item in missing_items:
+            print(f"  ❌ {item}")
+
+        if ultrawork_mode:
+            # ultrawork: no user intervention, record TODO and proceed
+            print("ℹ️ ultrawork mode — recording gaps to TODO and proceeding")
+            record_todo(missing_items)
+            break
+
+        # Interactive: ask the user to fill in or explicitly approve
+        user_input = ask_user(
+            "Please either:\n"
+            "  1. Provide values for the remaining items (I'll apply them)\n"
+            "  2. Type 'proceed' to accept current score and continue\n"
+            "  3. Type 'abort' to stop the workflow"
+        )
+
+        if user_input == "abort":
+            raise WorkflowAborted("User aborted at Quality Gate")
+        if user_input == "proceed":
+            record_todo(missing_items)
+            break
+        # otherwise: apply user-provided values → re-evaluate
+        apply_user_values(user_input)
+        continue
+
+    prev_score = score
+
     # Auto-fix missing items
     missing_items = identify_missing_items(spec)
     for item in missing_items:
@@ -146,18 +199,23 @@ while iteration < max_iterations:
         update_feature()
 
     print(f"✅ Applied {len(missing_items)} fixes - Re-evaluating...")
-
-if score < 95:
-    print(f"⚠️ Score {score} < 95 after {max_iterations} iterations")
-    print("Remaining gaps added to TODO. Proceeding with current quality.")
 ```
 
+**Termination conditions:**
+- `score == 100` → pass (primary success)
+- `score == prev_score` (auto-fixer stuck) → **ask the user**:
+  - User provides values → re-evaluate (loop continues, may reach 100)
+  - User says "proceed" → record gaps as TODO and continue to Step 3
+  - User says "abort" → stop entire workflow
+  - `ultrawork` mode → skip prompt, auto-record TODO and continue
+- No iteration cap — the only way to exit without 100 is explicit user approval or ultrawork.
+
 **Output format:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 QUALITY GATE [1/3]
+📊 QUALITY GATE [1]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Score: 87/100 ⚠️ BELOW THRESHOLD (95)
+Score: 87/100 ⚠️ BELOW 100
 
 Missing items:
   ❌ Error handling scenarios (10%)
@@ -171,14 +229,50 @@ Re-evaluating...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 QUALITY GATE [2/3]
+📊 QUALITY GATE [2]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Score: 96/100 ✅ PASSED
+Score: 96/100 ⚠️ BELOW 100
+
+Missing items:
+  ❌ Concurrent session policy (4%)
+
+Auto-fixing...
+  ✅ Added concurrent session policy
+
+Re-evaluating...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 QUALITY GATE [3]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Score: 100/100 ✅ PASSED
 
 ✅ Quality Gate PASSED - proceeding to GPT/Gemini review
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+**Stuck case (auto-fixer limit reached):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 QUALITY GATE [4]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Score: 87/100 ⚠️ STUCK (same as previous iteration)
+
+Auto-fixer hit a wall. These items need human input:
+  ❌ Business rule: monthly subscription renewal grace period (days?)
+  ❌ Target latency for search API (<?ms)
+  ❌ Data retention policy for audit logs (how many days?)
+
+How would you like to proceed?
+  1. Provide the values directly (e.g., "grace period 7 days, search 500ms, audit logs 90 days")
+     → Values will be applied and the score re-evaluated (100 may be reachable)
+  2. "proceed" — Accept the current score, record remaining items as TODO, then continue to Step 3
+  3. "abort" — Stop the workflow
+
+(In ultrawork mode, this prompt is skipped — TODO is auto-recorded and execution continues)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
 ### 2.3 Auto-Fix Rules
 
 | Missing Item | Auto-Fix Method |
@@ -192,25 +286,93 @@ Score: 96/100 ✅ PASSED
 
 ---
 
-## Step 3: Race Review (GPT + Gemini Cross-Validation) - Max 3 Rounds (v2.6.9)
+## Step 3: Race Review (GPT + Gemini Cross-Validation) - Convergence-Based (No Round Cap)
 
 **RULES FOR RACE REVIEW:**
 
 1. **YOU MUST** use the Bash tool to call `llm-orchestrate.js` directly
 2. **DO NOT** simulate or fake review results
 3. Run rounds sequentially (each round uses updated SPEC)
+4. **No hard round cap** — loop until P1=0 AND no new findings (convergence)
+
+> Race Mode reviews SPEC with GPT and Gemini in parallel, then cross-validates findings for higher confidence. The loop continues until quality converges naturally.
+
+### Termination Rules
+
+- **P1 = 0 AND no new findings this round** → converged, stop (primary success)
+- **Round 1 with P1 = 0 AND no P2/P3** → perfect on first try, stop (early success)
+- **Round N findings == Round N-1 findings** → **stuck**: LLMs keep flagging same issues that auto-applier can't resolve → **ask the user** (see 3.2.1)
+
+### Stuck Handling (3.2.1)
+
+When the same findings repeat across rounds, the auto-apply loop has hit a wall. This typically means:
+- The fix requires human judgment (architectural trade-off, domain rule, etc.)
+- The LLMs are producing a false positive that the auto-applier can't dismiss
+- The suggested fix conflicts with an existing constraint
+
+**Interactive mode** — prompt the user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ RACE REVIEW STUCK at Round {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Same findings repeated from Round {N-1}. Auto-applier cannot resolve:
+
+| # | Issue | Severity | GPT | Gemini | Reason it's stuck |
+|---|-------|----------|-----|--------|-------------------|
+| 1 | {issue title} | P1 | ✅ | ✅ | {e.g., "fix requires domain decision"} |
+| 2 | {issue title} | P2 | ✅ | ❌ | {e.g., "conflicts with existing constraint"} |
+
+How would you like to proceed?
+  1. Provide a resolution directly (e.g., "issue 1: retry 5 times, issue 2: ignore")
+     → Changes will be applied and the next round re-run
+  2. "proceed" — Record current issues as TODO and continue to Step 4
+  3. "abort" — Stop the workflow
+
+(In ultrawork mode, this prompt is skipped — TODO is auto-recorded and execution continues)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Pseudocode:**
+
+```python
+if current_findings == prev_findings:
+    if ultrawork_mode:
+        print("ℹ️ ultrawork mode — recording stuck issues to TODO and proceeding")
+        record_todo(current_findings)
+        break
+
+    user_input = ask_user(
+        "Race Review stuck. Please either:\n"
+        "  1. Provide resolution for the listed issues\n"
+        "  2. Type 'proceed' to record as TODO and continue to Step 4\n"
+        "  3. Type 'abort' to stop the workflow"
+    )
+
+    if user_input == "abort":
+        raise WorkflowAborted("User aborted at Race Review")
+    if user_input == "proceed":
+        record_todo(current_findings)
+        break
+    # otherwise: apply user-provided resolutions → next round
+    apply_user_resolutions(user_input)
+    continue  # re-run the round with updated SPEC
+```
 
-> Race Mode reviews SPEC with GPT and Gemini in parallel, then cross-validates findings for higher confidence.
+### Narrowing Scope (Noise Reduction)
 
-### Convergence Rule (Early Exit)
+To prevent LLM cosmetic noise from causing infinite loops while still reaching 100% quality:
 
-- **Round N findings == Round N-1 findings** → converged, stop immediately (no need to reach Round 3)
-- **Round 1 with P1 = 0** → skip Round 2 and stop
-- **Max 3 rounds** — if new P1s still appear after 3 rounds, record as TODO and stop
+| Round | Scope |
+|-------|-------|
+| 1 | Full scope (P1 + P2 + P3) |
+| 2 | P1 + P2 only |
+| 3+ | P1 only (until P1=0 or convergence) |
 
-### 3.1 Review Loop (Max 3 Rounds)
+### 3.1 Review Loop (No Round Cap)
 
-**For EACH round (1, 2, 3), run GPT + Gemini in PARALLEL via Bash tool. Stop early if converged.**
+**Run GPT + Gemini in PARALLEL via Bash tool for each round. Stop when termination rules trigger.**
 
 **🚨 IMPORTANT: SPEC content is too large for CLI arguments. Use --input file method (no pipe needed).**
 
@@ -219,9 +381,10 @@ Score: 96/100 ✅ PASSED
 **Step A: Save SPEC content + prompt as JSON to scratchpad temp file (using Write tool):**
 - Write JSON to `[SCRATCHPAD]/spec-review-input.json` with content:
 ```json
-{"prompt": "Review this SPEC for completeness, specificity, testability, security, and performance. Round [N]/3. Find issues and improvements. Return JSON: {issues: [{id, title, description, severity, suggestion}]}. SPEC content: [SPEC_CONTENT]"}
+{"prompt": "Review this SPEC for completeness, specificity, testability, security, and performance. Round [N] (scope: [SCOPE]). Find issues and improvements. Return JSON: {issues: [{id, title, description, severity, suggestion}]}. SPEC content: [SPEC_CONTENT]"}
 ```
 - Where `[SPEC_CONTENT]` is the full SPEC text (properly JSON-escaped inside the prompt string)
+- `[SCOPE]` is `P1+P2+P3` for round 1, `P1+P2` for round 2, `P1` for rounds 3+
 
 **Step B: Script path:**
 - `[LLM_SCRIPT]` = `{{VIBE_PATH}}/hooks/scripts/llm-orchestrate.js`
@@ -239,13 +402,13 @@ node "[LLM_SCRIPT]" gemini orchestrate-json --input "[SCRATCHPAD]/spec-review-in
 ```
 
 **🚨 MANDATORY: Replace `[SCRATCHPAD]` with the actual scratchpad directory path.**
-**🚨 Replace `[N]` with the current round number (1, 2, or 3).**
+**🚨 Replace `[N]` with the current round number (1, 2, 3, ...).**
 **🚨 Replace `[LLM_SCRIPT]` with the resolved absolute path from Step B.**
 **🚨 Run GPT and Gemini calls in PARALLEL (two separate Bash tool calls at once).**
 
-- Round 1: Write SPEC → Run GPT + Gemini in parallel → Cross-validate → Apply fixes → Update SPEC file
-- Round 2: Write updated SPEC → Run → Cross-validate → Apply fixes → Update SPEC file
-- Round 3: Write final SPEC → Run → Cross-validate → Confirm no issues remain
+- Round 1: Write SPEC → Run GPT + Gemini in parallel (full scope) → Cross-validate → Apply fixes → Update SPEC file
+- Round 2: Write updated SPEC → Run (P1+P2 scope) → Cross-validate → Apply fixes → Update SPEC file
+- Round 3+: Write updated SPEC → Run (P1-only scope) → Cross-validate → Apply fixes → Continue until P1=0 AND no new findings (or convergence detected)
 
 ### 3.2 Cross-Validation Rules
 
@@ -261,46 +424,46 @@ node "[LLM_SCRIPT]" gemini orchestrate-json --input "[SCRATCHPAD]/spec-review-in
 3. Auto-apply P1/P2 improvements to SPEC and Feature files (use Edit tool)
 4. Continue to next round with updated SPEC content
 
-### 3.3 User Decision Checkpoint (Round 3 이후)
+### 3.3 User Decision Checkpoint (After Convergence)
 
-**🚨 MANDATORY: 3라운드 완료 후 사용자 판단 체크포인트 실행**
+**🚨 MANDATORY: Run user judgment checkpoint when the review loop reaches convergence**
 
-> Type 6 (Iterative-Reasoning) 패턴: AI가 혼자 결정하지 않고, 사용자와 함께 판단
+> Type 6 (Iterative-Reasoning) pattern: AI does not decide alone — judges together with the user
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔍 USER CHECKPOINT: 리뷰 결과 검토
+🔍 USER CHECKPOINT: Review Results
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-3라운드 리뷰에서 발견된 주요 변경사항:
+Key changes found across {N} review rounds:
 
-| # | 변경 내용 | 출처 | 신뢰도 |
-|---|----------|------|--------|
-| 1 | {변경1} | GPT+Gemini | 100% |
-| 2 | {변경2} | GPT only | 50% |
+| # | Change | Source | Confidence |
+|---|--------|--------|------------|
+| 1 | {change1} | GPT+Gemini | 100% |
+| 2 | {change2} | GPT only | 50% |
 | ... | ... | ... | ... |
 
-질문:
-1. 위 변경사항 중 제외하고 싶은 항목이 있나요?
-2. 추가로 명시해야 할 요구사항이 있나요?
-3. 기술적 접근 방식에 동의하시나요?
+Questions:
+1. Are there any changes above you'd like to exclude?
+2. Are there any additional requirements that should be specified?
+3. Do you agree with the technical approach?
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**Checkpoint 행동 규칙:**
+**Checkpoint action rules:**
 
-| 상황 | 행동 |
-|------|------|
-| `ultrawork` 모드 | 체크포인트 스킵, 자동 진행 |
-| 일반 모드 | 반드시 사용자 응답 대기 |
-| 사용자가 변경 요청 | 수정 후 다시 체크포인트 |
-| 사용자가 승인 | Step 4로 진행 |
+| Situation | Action |
+|-----------|--------|
+| `ultrawork` mode | Skip checkpoint, auto-proceed |
+| Normal mode | Must wait for user response |
+| User requests changes | Apply changes, then re-run checkpoint |
+| User approves | Proceed to Step 4 |
 
 **Output format:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🏁 SPEC RACE REVIEW - Round 1/3
+🏁 SPEC RACE REVIEW - Round 1 (scope: P1+P2+P3)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Model Results:
@@ -325,7 +488,7 @@ Auto-applying...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🏁 SPEC RACE REVIEW - Round 2/3
+🏁 SPEC RACE REVIEW - Round 2 (scope: P1+P2)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Cross-Validated Issues:
@@ -340,107 +503,65 @@ Auto-applying...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🏁 SPEC RACE REVIEW - Round 3/3
+🏁 SPEC RACE REVIEW - Round 3 (scope: P1)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Cross-Validated Issues: None
 
-✅ No changes needed - SPEC is complete
+✅ Converged: P1 = 0 AND no new findings
 ✅ Consensus Rate: 100%
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### Step 3.1: Codex Adversarial Review (Codex 플러그인 활성화 시)
+> If new P1s appear at round 3, the loop continues to round 4, 5, ... until convergence.
+
+### Step 3.1: Codex Adversarial Review (When Codex Plugin Is Active)
 
-> **활성화 조건**: Codex 플러그인 설치 시 자동 실행. 미설치 시 스킵.
-> GPT+Gemini Race Review와 **동시에** 실행하여 3중 교차 검증.
+> **Activation condition**: Automatically runs when Codex plugin is installed. Skipped if not installed.
+> Runs **simultaneously** with GPT+Gemini Race Review for triple cross-validation.
 
-Codex adversarial review는 SPEC의 **설계 결정에 도전**합니다:
-- 대안적 아키텍처가 더 나은지 검증
-- 오버엔지니어링 또는 과소 설계 여부
-- 누락된 엣지케이스 및 비기능 요구사항
+Codex adversarial review **challenges the design decisions** in the SPEC:
+- Validates whether an alternative architecture would be better
+- Checks for over-engineering or under-engineering
+- Identifies missing edge cases and non-functional requirements
 
-**실행 (GPT+Gemini Race와 병렬):**
+**Execution (parallel with GPT+Gemini Race):**
 
 ```
 /codex:adversarial-review
 ```
 
-**결과 통합**: Race Review 교차 검증 테이블에 Codex 열 추가:
+**Result integration**: Add Codex column to the Race Review cross-validation table:
 
 ```markdown
 | Issue | GPT | Gemini | Codex | Confidence |
 |-------|-----|--------|-------|------------|
-| {이슈} | ✅/❌ | ✅/❌ | ✅/❌ | {%} |
+| {issue} | ✅/❌ | ✅/❌ | ✅/❌ | {%} |
 ```
 
-- 3개 모델 중 2개 이상 동의 → **High Confidence**
-- Codex만 발견한 이슈 → **P2** (설계 관점 검토 필요)
-- 3개 모두 동의 → **P1** (즉시 수정)
+- 2 or more of 3 models agree → **High Confidence**
+- Issue found only by Codex → **P2** (requires design perspective review)
+- All 3 models agree → **P1** (fix immediately)
 
 ---
 
 ## Step 3.5: Review Debate Team (Agent Teams)
 
-> **조건**: Agent Teams 활성화 + 3라운드 완료 후 P1/P2 이슈 2개 이상 발견 시
-> 여러 관점에서 교차 검증하여 오탐 제거 및 우선순위 조정
-
-**팀 구성:**
-
-| 팀원 | 역할 |
-|------|------|
-| security-reviewer (리더) | 보안 관점 우선순위 결정, 교차 검증 주도 |
-| architecture-reviewer | 구조적 영향 평가, 설계 일관성 확인 |
-| performance-reviewer | 성능 영향 평가, 불필요한 최적화 식별 |
-| simplicity-reviewer | 과잉 설계 여부, YAGNI 위반 식별 |
-
-**활성화 조건:**
-
-| 상황 | 행동 |
-|------|------|
-| P1/P2 이슈 2개 이상 | 자동 활성화 |
-| P1/P2 이슈 1개 이하 | 스킵 → Step 4로 진행 |
-| Agent Teams 비활성화 | 스킵 → Step 4로 진행 |
-
-**spawn 패턴:**
-
-```text
-TeamCreate(team_name="spec-debate-{feature}", description="SPEC review debate for {feature}")
-
-Task(team_name="spec-debate-{feature}", name="security-reviewer", subagent_type="security-reviewer",
-  mode="bypassPermissions",
-  prompt="SPEC 리뷰 팀 리더. GPT/Gemini가 발견한 P1/P2 이슈를 교차 검증하세요.
-  SPEC: {spec_content}
-  발견된 이슈: {p1_p2_issues}
-  역할: 각 이슈가 진짜인지(오탐 아닌지) 검증. 실제 영향도 기준으로 우선순위 조정.
-  분쟁이 있는 이슈는 해당 리뷰어에게 SendMessage로 확인 요청하세요.")
-
-Task(team_name="spec-debate-{feature}", name="architecture-reviewer", subagent_type="architecture-reviewer",
-  mode="bypassPermissions",
-  prompt="SPEC 리뷰 팀 아키텍처 전문가. 아키텍처 관련 이슈를 검증하세요.
-  SPEC: {spec_content}
-  역할: 구조적 일관성, SOLID 원칙, 레이어 경계 검증.
-  우선순위 변경 필요 시 security-reviewer에게 SendMessage로 알리세요.")
-
-Task(team_name="spec-debate-{feature}", name="performance-reviewer", subagent_type="performance-reviewer",
-  mode="bypassPermissions",
-  prompt="SPEC 리뷰 팀 성능 전문가. 성능 관련 이슈를 검증하세요.
-  SPEC: {spec_content}
-  역할: 성능 요구사항 현실성 평가, 불필요한 최적화 식별.
-  P2→P1 승격이 필요하면 security-reviewer에게 SendMessage로 알리세요.")
-
-Task(team_name="spec-debate-{feature}", name="simplicity-reviewer", subagent_type="simplicity-reviewer",
-  mode="bypassPermissions",
-  prompt="SPEC 리뷰 팀 단순성 전문가. 과잉 설계 여부를 검증하세요.
-  SPEC: {spec_content}
-  역할: YAGNI 위반, 불필요한 복잡성 식별.
-  P1→P2 강등이 필요하면 security-reviewer에게 SendMessage로 알리세요.")
-```
-
-**결과 통합:**
-- 팀 합의 결과를 SPEC에 반영 (P1 즉시 적용, P2 노트 추가)
-- 팀원 shutdown_request → TeamDelete로 정리
-- Step 4 (Final Summary)로 진행
+> **Team definition**: See `agents/teams/review-debate-team.md` (SPEC Review context)
+> **Condition**: Agent Teams enabled + 2 or more P1/P2 issues found after review loop convergence
+
+**Activation conditions:**
+
+| Situation | Action |
+|-----------|--------|
+| 2 or more P1/P2 issues | Auto-activate |
+| 1 or fewer P1/P2 issues | Skip → proceed to Step 4 |
+| Agent Teams disabled | Skip → proceed to Step 4 |
+
+**Result integration:**
+- Apply team consensus results to SPEC (P1 applied immediately, P2 added as notes)
+- Team member shutdown_request → clean up with TeamDelete
+- Proceed to Step 4 (Final Summary)
 
 ---
 
@@ -451,11 +572,11 @@ Task(team_name="spec-debate-{feature}", name="simplicity-reviewer", subagent_typ
 ✅ SPEC REVIEW COMPLETE: {feature-name}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Quality Score: 96/100 ✅
-Review Rounds: 3/3 ✅
-Total Improvements: 4
+Quality Score: 100/100 ✅
+Review Rounds: {N} (converged: P1=0, no new findings) ✅
+Total Improvements: {M}
 ⏱️ Started: {start_time}
-⏱️ Completed: {getCurrentTime 결과}
+⏱️ Completed: {getCurrentTime result}
 
 Updated files:
   📋 .claude/vibe/specs/{feature-name}.md (or split folder)
@@ -516,30 +637,30 @@ If no issues, proceed with /vibe.run "{feature-name}".
 
 ### 5.1 Final User Checkpoint
 
-**🚨 MANDATORY: `/vibe.run` 진행 전 최종 사용자 확인**
+**🚨 MANDATORY: Final user confirmation before proceeding to `/vibe.run`**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ SPEC 리뷰 완료 - 최종 확인
+✅ SPEC Review Complete - Final Confirmation
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-다음 질문에 답변해 주세요:
+Please answer the following questions:
 
-1. **요구사항 정확성**: 위 SPEC이 원래 의도한 기능을 정확히 설명하고 있나요?
-2. **범위 적절성**: 구현 범위가 너무 크거나 작지 않나요?
-3. **기술 스택**: 선택된 기술 스택에 동의하시나요?
-4. **우선순위**: Phase 순서와 우선순위가 맞나요?
+1. **Requirements accuracy**: Does the SPEC above accurately describe the originally intended feature?
+2. **Scope appropriateness**: Is the implementation scope neither too large nor too small?
+3. **Tech stack**: Do you agree with the chosen tech stack?
+4. **Priority**: Is the Phase order and priority correct?
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-💡 "ok" 또는 "진행"으로 승인 / 수정 사항이 있으면 말씀해 주세요
+💡 Type "ok" or "proceed" to approve / share any changes you'd like made
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 **Why This Checkpoint Matters:**
 
-> AI가 더 많이 해준다고 좋은 게 아닙니다.
-> 사용자가 AI와 함께 생각하고 판단할 때 최고의 결과가 나옵니다.
-> 이 체크포인트는 Type 6 (Iterative-Reasoning) 패턴을 유도합니다.
+> More AI doing more is not always better.
+> The best results come when the user thinks and judges together with AI.
+> This checkpoint induces the Type 6 (Iterative-Reasoning) pattern.
 
 ---
 
@@ -586,11 +707,7 @@ Continuing with {other model} results only...
 
 ## Quick Mode
 
-For faster iteration (1 round only):
-
-```bash
-/vibe.spec.review "feature-name" --quick
-```
+For faster iteration (1 round only): pass `--quick` flag when invoking the skill (or via `/vibe.spec "feature-name" --quick` orchestrator).
 
 ---