factory-code-review

Factory Code Review

수용 기준에 대한 정량 채점과 severity 분류를 수행하고, 최종 준수율 판정을 내린다.

Core Principle

주관적 "looks good"이 아닌 정량적 준수율로 판정한다. 이 스킬은 judge이며, doer가 아니다.

Recommended Inputs

• factory/architect/architect.md — 수용 기준, 컴포넌트, 인터페이스 (필수)
• factory/prd/prd.md — 요구사항 ID (권장)

Scope Boundary

This skill: Score implementation against acceptance criteria and deliver a quantitative verdict.

MUST NOT:

• Write, modify, or delete any code → factory-develop
• Fix issues or deviations directly → route to appropriate skill
• Change acceptance criteria to match implementation → criteria judge the code, not vice versa

The Judge's Oath: This skill produces a SCORE and a VERDICT, not CODE CHANGES. Below-threshold scores route back to the appropriate skill — never "just fix it here".

When boundary is crossed: STOP. Revert changes, re-score from clean state. Route deviations to factory-develop (implementation gaps) or factory-architect (design gaps).

---

Step 0: Decision Agenda

공유 프로토콜: settings/templates/decision-agenda.md

0-1. Read Prior Decisions

이전 스킬의 decisions 파일을 읽는다 (있으면):

• factory/architect/decisions.md
• factory/develop/decisions.md
• factory/e2e/decisions.md

이미 결정된 항목은 "Pre-decided"로 표시하고 skip.

0-2. Generate Agenda

입력과 컨텍스트를 분석하여 아래 결정 항목을 기본 Agenda로 구성.

Tier 1 (Strategic — 사용자 필수):

ID	Decision	비위임
CR-D-001	심각도 분류 오버라이드 — AI 판정 후 사용자가 확인/수정	No
CR-D-002	판정 기준 오버라이드 — 90/70 기본값을 사용자가 조정 가능	Yes

Tier 2 (Tactical — AI 기본값 + 사용자 오버라이드):

ID	Decision	AI 기본값
CR-D-003	편차 처리 방향 (지금 수정 vs 나중)	Severity 기반: Critical→지금, Minor→나중
CR-D-004	기술 부채 수용 항목	명시적 수용 없음 (모두 리포트)

0-3. Agenda Overview

AskUserQuestion으로 진행 방식 확인:

• 핵심만 검토 (Recommended): Tier 1만 직접, Tier 2는 AI 기본값
• 전체 검토: Tier 1 + Tier 2 모든 결정을 직접
• 알아서 해줘: AI가 결정하고 근거 기록. CR-D-002(판정 기준 오버라이드)만 반드시 확인

0-4. Decision Walk-through

선택에 따라 AskUserQuestion으로 결정 수집 (최대 4개/배치, 의존성 순서 준수).

• CR-D-001은 Step 4 Issue Review 후 심각도 분류 결과를 사용자에게 확인한다.
• CR-D-002는 Step 3 Compliance Score 산출 전에 기준을 사용자에게 확인한다.

0-5. Record Decisions

factory/code-review/decisions.md에 기록:

ID	Decision	Choice	Rationale	Decided By	Date

0-6. Proceed

모든 선행 결정 기록 후 Step 1로 진행.

---

Step 1: Review Scope Identification

Git SHA 기반 리뷰 범위 확보:

BASE_SHA=$(git rev-parse HEAD~1)  # 또는 origin/main
HEAD_SHA=$(git rev-parse HEAD)
git diff --stat ${BASE_SHA}..${HEAD_SHA}
git diff ${BASE_SHA}..${HEAD_SHA}
git diff --stat --cached               # staged but not yet committed
git ls-files --others --exclude-standard  # untracked new files

리뷰 대상 파악:

1. factory/prd/prd.md — 요구사항 ID
2. factory/architect/architect.md — 수용 기준, 컴포넌트, 인터페이스
3. factory/analysis/analysis.md — 선택한 접근 방식
4. 변경된 파일 (git diff ${BASE_SHA}..${HEAD_SHA}로 확인)

---

Step 2: Acceptance Criteria Scoring Matrix

factory/architect/architect.md의 모든 수용 기준에 대해 채점:

AC ID	Requirement	Test Status	Implementation Status	Verdict
AC-001	FR-001	Pass/Fail/No Test	Complete/Partial/Missing	✅/⚠️/❌

Verdict Rules:

• ✅ Pass: 테스트 통과 AND 구현이 설계와 일치
• ⚠️ Partial: 테스트 통과하지만 구현이 설계에서 이탈 OR 사소한 갭
• ❌ Fail: 테스트 실패 OR 구현 누락

---

Step 3: Compliance Score

Compliance = (✅ count / total AC count) × 100

Score: [N]% ([✅ count]/[total])

Score	Verdict	Action
90%+	PASS	배포/머지 준비 완료
70-89%	NEEDS IMPROVEMENT	식별된 갭 수정 후 재검증
<70%	REDESIGN	Architect Phase로 복귀, 근본적 문제

---

Step 4: Issue Review (Severity Classification)

변경된 코드를 리뷰하고 이슈를 severity로 분류:

Critical (Must Fix)

버그, 보안 이슈, 데이터 손실 리스크, 깨진 기능

Important (Should Fix)

아키텍처 문제, 누락된 기능, 부족한 에러 처리, 테스트 갭

Minor (Nice to Have)

코드 스타일, 최적화 기회, 문서 개선

각 이슈에 반드시 포함:

• File:line 참조
• 무엇이 잘못되었는지
• 왜 중요한지
• 어떻게 수정하는지 (명확하지 않은 경우)

---

Step 5: Quality Checklist

각 항목을 확인하고 증거 기록:

Behavior

• 모든 기능 요구사항 구현됨
• 모든 비기능 요구사항 충족 (또는 예외 문서화)
• 에러 처리가 설계 시나리오를 커버
• 설계의 엣지 케이스가 처리됨

Testing

• 유닛 테스트 통과
• 통합 테스트 통과
• E2E 테스트 통과
• 테스트 불안정성(flaky) 없음

Build & Tooling

• 프로젝트 빌드 에러 없음
• 린터 통과 (또는 문서화된 억제)
• 타입 체크 통과 (해당 시)
• 새 경고 없음

Documentation & Code Quality

• 코드가 프로젝트 컨벤션을 따름 (analysis에서 확인)
• 공개 인터페이스가 설계 시그니처와 일치
• 디버그 코드나 임시 해킹 남지 않음
• 변경 범위가 Change Impact Map과 일치

Production Readiness

• 마이그레이션 전략 (스키마 변경 시)
• 하위 호환성 고려됨
• 문서 완비
• 명백한 버그 없음

---

Step 6: Deviation Report

준수율이 100% 미만이면 각 편차를 나열:

### DEV-001: [AC ID] [Title]
- **Gap**: [무엇이 누락되었거나 다른지]
- **Severity**: Critical / Major / Minor
- **Recommendation**: [해결을 위한 구체적 행동]

---

Step 7: Final Report

factory/code-review/code-review.md에 작성:

# Acceptance Report: [Project Name]

## Summary
- **Date**: [ISO 8601, e.g. 2026-03-02T14:30:00Z]
- **Compliance Score**: [N]%
- **Verdict**: PASS / NEEDS IMPROVEMENT / REDESIGN

## Scoring Detail
[Step 2의 테이블]

## Issues Found

### Critical (Must Fix)
[이슈 목록 with file:line]

### Important (Should Fix)
[이슈 목록 with file:line]

### Minor (Nice to Have)
[이슈 목록 with file:line]

## Quality Checklist
[Step 5의 결과]

## Deviations
[Step 6, 있는 경우]

## Strengths
[잘된 점을 구체적으로. file:line 참조 포함.]

## Verification Evidence
- Test command: [command]
- Test results: [N/N passing]
- Build command: [command]
- Build result: [success/failure]
- Lint command: [command]
- Lint result: [N warnings, N errors]

## Recommendations
[코드 품질, 아키텍처, 프로세스 개선 사항]

## Sign-off
- [ ] 모든 수용 기준 검토됨
- [ ] 준수율 산출됨
- [ ] 품질 체크리스트 완료됨
- [ ] 편차 문서화됨 (있는 경우)

---

Step 8: Present Verdict

Display the summary:

── Factory Code Review Report ───────────
Project:    [name]
Score:      [N]% — [PASS/NEEDS IMPROVEMENT/REDESIGN]
Tests:      [N/N passing]
Deviations: [N]
─────────────────────────────────────────

Routing on non-PASS verdicts:

• NEEDS IMPROVEMENT (70-89%): Top 3 deviations listed → /factory-develop로 갭 수정 후 /factory-e2e 재실행
• REDESIGN (<70%): Top 3 deviations listed → /factory-architect로 설계 재검토부터 다시 진행

---

Critical Rules

DO:

• 실제 severity로 분류 (모든 것이 Critical은 아님)
• 구체적으로 (file:line, 모호하지 않게)
• 왜 이슈가 중요한지 설명
• 강점을 인정
• 명확한 판정 제시

DON'T:

• 확인하지 않고 "looks good" 말하기
• 사소한 것을 Critical로 표시
• 리뷰하지 않은 코드에 피드백
• 모호하게 ("에러 처리 개선")
• 명확한 판정 회피
• 주관적 "이 정도면 괜찮다"로 점수 부풀리기

---

Review Red Flags

절대 하지 않는다:

• "간단해서" 리뷰를 건너뛰기
• Critical 이슈를 무시하기
• 수정하지 않은 Important 이슈가 있는 채 진행하기
• 유효한 기술적 피드백에 근거 없이 반박하기

리뷰어가 틀렸을 때:

• 기술적 근거로 반박한다
• 코드/테스트로 정상 동작을 증명한다
• 명확하지 않으면 설명을 요청한다

---

Example Output

### Strengths
- Clean database schema with proper migrations (db.ts:15-42)
- Comprehensive test coverage (18 tests, all edge cases)
- Good error handling with fallbacks (summarizer.ts:85-92)

### Issues

#### Important
1. **Missing help text in CLI wrapper**
   - File: index-conversations:1-31
   - Issue: No --help flag, users won't discover --concurrency
   - Fix: Add --help case with usage examples

2. **Date validation missing**
   - File: search.ts:25-27
   - Issue: Invalid dates silently return no results
   - Fix: Validate ISO format, throw error with example

#### Minor
1. **Progress indicators**
   - File: indexer.ts:130
   - Issue: No "X of Y" counter for long operations
   - Impact: Users don't know how long to wait

### Assessment
**Compliance Score: 92% — PASS**
**Reasoning:** Core implementation is solid with good architecture and tests. Important issues are easily fixed and don't affect core functionality.

---

Completion Message

Verdict-dependent completion:

• PASS: "프로젝트가 모든 수용 기준을 통과했습니다. 배포/머지 준비가 완료되었습니다."
• NEEDS IMPROVEMENT: "개선이 필요합니다. /factory-develop로 갭을 수정하세요."
• REDESIGN: "근본적 재설계가 필요합니다. /factory-architect로 돌아가세요."

결정 기록은 factory/code-review/decisions.md에 저장되었습니다.