| name | pr-review |
| description | PR 정성 리뷰를 수행할 때 사용. 자동 검증 결과를 입력으로 삼고, test/lint 재실행 없이 profile별 정성 차원(Mock/정합성/Scope/PR body 등)을 평가해 PR comment scorecard와 action items를 작성한다. |
PR Review
PR review는 자동 layer와 정성 layer를 분리한다. Hook, lint, typecheck, test,
CI, Required Checks는 자동 layer다. Reviewer는 이 검사를 다시 돌리는 사람이
아니라, 자동 layer가 잡기 어려운 의미 판단을 하는 read-only 평가자다.
Inputs
- PR title/body/diff.
- 대상 sprint가 있으면
docs/sprints/sprint-<N>/contract.md.
- Required Checks가 있으면
bash scripts/review/run-checks.sh <N> 출력.
- 정합성 판단에 필요한 active memory/docs/code.
- CI 상태가 필요하면
gh pr checks <N>.
로컬 절대경로, 임시 파일 경로, worktree 경로를 evidence로 쓰지 않는다. PR comment와
summary에는 repo-relative path 또는 GitHub URL만 남긴다.
Output Contract
pr-reviewer coordinator는 최종 통합 scorecard를 PR에 직접 comment로 남긴다.- Subreviewer 결과는 coordinator의 내부 입력이다. Subreviewer는 PR comment를
남기지 않는다.
- Comment 작성이 도구/권한 문제로 실패하면 최종 응답에 실패 원인과 붙일
scorecard 본문을 그대로 반환한다.
- 같은 review round에는 통합 comment 1개만 남긴다. follow-up review round는 새
commit/push 후 별도 comment를 남긴다.
Boundaries
- Reviewer는 read-only다. commit, push, merge, branch 수정 금지.
cargo test, pnpm vitest, npm run lint 같은 정량 검사는 재실행하지 않는다.- 자동 layer 실패는 review 결함으로 보고하되, reviewer가 우회하거나 고치지 않는다.
- 구현 agent의 self-review를 피한다. 가능하면 별도 reviewer agent가 본다.
- External reviewer는 사용자가 명시적으로 요청했을 때만 추가한다.
Review Pack
pr-reviewer는 top-level 전용 coordinator다. 하네스는 subagent의 중첩 spawn을
막으므로 pr-subreviewer는 top-level pr-reviewer만 spawn할 수 있다.
Fan-out은 항상-spawn이 아니라 coordinator의 자율 판단이다. 작은 PR은 단독
평가한다. diff가 대략 800줄 이상, 또는 15파일 이상, 또는 3개 이상 영역
(frontend+backend+ci 등)에 걸치면 전용 read-only pr-subreviewer를 관점별로
2-4개 fan-out한 뒤 하나의 scorecard로 합친다. 세 축은 목표치이지 hard gate가
아니고, 경계는 coordinator 재량이다.
pr-subreviewer spawn이 실패하면(중첩 spawn 불능 포함) coordinator는 같은
관점들을 순차 단독 검증으로 강등해 직접 수행하고, scorecard에 "fan-out 불가로
단독 강등" 사실을 명시한다. 강등해도 관점별 findings와 severity 병합 규칙은
동일하게 적용한다.
Subreviewer도 이 skill의 Boundaries를 상속한다.
각 subreviewer는 같은 immutable input을 받고, 서로의 결과를 보기 전에 독립
산출물을 반환한다.
Coordinator는 pr-subreviewer 외 agent를 subreview 용도로 spawn하지 않는다.
delivery, tdd-generator, bug-fix, codex-reviewer 같은 write-capable 또는
external reviewer agent는 subreviewer가 아니다.
기본 관점:
code-semantics: runtime/source diff, behavioral regression, edge case.test-quality: mock 범위, user-facing assertion, RED/contract evidence.sot-scope-docs: active memory/docs/ADR 정합성, scope, PR body, evidence.security-infra: credential/destructive/signing/CI/hook/build risk.
선택 규칙:
code: code-semantics, test-quality, sot-scope-docs.docs: sot-scope-docs.infra: security-infra, sot-scope-docs.security: security-infra, sot-scope-docs, 필요한 code-semantics.- 관련 diff가 없으면 해당 관점은 생략한다. 같은 관점 중복 spawn은 금지한다.
Subreviewer 출력은 관점, blocking findings, non-blocking notes, evidence coverage만 포함한다. Coordinator는 중복을 합치고, 가장 높은 severity를 유지한다.
한 관점이라도 blocking이면 최종 verdict는 blocking이다. 점수 평균으로 blocking을
희석하지 않는다.
Profile 선택
우선순위:
- Sprint contract frontmatter의
review-profile.
- Contract가 없으면 변경 파일로 추론:
- runtime/source/test 변경 포함:
code
- docs/memory/agent wrapper 중심:
docs
- hook, CI, build, release tooling 중심:
infra
- auth, secret, destructive action, credential, signing 중심:
security
평가 차원
Mock 범위 (code)
- test diff의
vi.mock(...) / module mock을 본다.
- 외부 boundary stub은 허용: Tauri
invoke, network, filesystem, DB adapter 등.
- own code, store, hook, util 전체 mock은 위반으로 본다.
- 사용자가 보는 behavior를 막는 assertion인지 확인한다.
정합성 (공통)
- 새 룰/문서/코드가 active memory, ADR archive, 코드 현실과 충돌하지 않는가?
- 같은 source of truth가 wrapper, memory, skill, docs에 중복 구현되지 않았는가?
- repo-owned skill은
.agents/skills/<name>/SKILL.md가 source인지 확인한다.
- 외부/plugin/generated/local 영역을 수정하지 않았는가.
- 다른 sprint scope를 침범하지 않았는가.
Scope (공통)
- contract의 In Scope가 구현되었는가.
- Out of Scope를 건드리지 않았는가.
- invariant와 acceptance criteria가 실제 diff/검증 결과로 충족되는가.
- scope가 없으면 PR body의 명시 목표를 기준으로 본다.
PR Body / Documentation Impact (공통)
Documentation impact가 변경 내용과 맞는가.Smoke-Test-Plan:이 있고, runtime journey 영향 판단이 타당한가.- user-facing, contract, workflow, safety, ops, architecture, risk 변경이
기존 SOT에 반영되었는가.
- PR body/comment의 evidence가 GitHub에서 확인 가능한가.
Security (security)
- secret/credential/plaintext boundary가 명확한가.
- destructive action에는 dry-run, confirmation, auditability가 있는가.
- threat model 또는 security handoff가 필요한데 빠지지 않았는가.
Infra (infra)
- platform-neutral한가.
- hook/CI/build script가 read-only gate와 repair step을 섞지 않는가.
- local-only path, env, tool assumption을 repo policy로 고정하지 않았는가.
Scorecard Format
## 자동 layer
- <status> <check or source>
## 관점 입력
- <perspective>: pass|blocking — <short basis>
## 정성 차원 (profile: <name>)
| 차원 | 점수 | 결함 |
|---|---:|---|
| 정합성 | N/10 | ... |
| Scope | N/10 | ... |
| PR body | N/10 | ... |
## Action items
1. ...
Profile에 적용되지 않는 차원은 출력하지 않는다. "N/A" 행으로 채우지 않는다.
Verdict
- Red / Blocking: 자동 layer 실패, score < 8, contract miss, SOT 충돌, scope 침범,
로컬 evidence, reviewer boundary 위반.
- Green / Pass: 적용 차원 모두 8/10 이상이고 blocking item이 없다.
- 8/10은 "merge-ready with bounded residual risk"다. 7/10은 "works but needs
reflection"이므로 red/blocking으로 취급한다.
- 결함이 있으면 delivery owner가 고친 뒤 reviewer가 다시 본다.
Related
memory/workflow/review/memory.md — review phase 행동 계약memory/workflow/delivery/memory.md — T4/T5/T6 통합memory/workflow/documentation/memory.md — Documentation impact gatescripts/review/run-checks.sh — sprint Required Checks runner
