Minimal Diff Review

Minimal Diff Review

Judge whether the requested behavior was implemented with the smallest change that still preserves clarity, correctness, safety, and repository conventions. A small diff is not the fewest lines; it is the least new policy, structure, and touched surface needed for the stated outcome.

Operating contract

• Problem: an otherwise correct implementation can accumulate speculative guards, broad types, one-use abstractions, pattern drift, and unrelated cleanup.
• Use when: a concrete implementation is ready for a focused minimum-safe-diff pass before commit, PR, or handoff.
• Do not use when: the task is a general correctness, security, architecture, performance, or refactoring review, or when no concrete change can be resolved.
• Produce: CLEAN, TRIM, or BLOCKED, with evidence and the smallest safe alternative for every admitted finding.

Review contract

• Review the concrete change and nearby repository evidence. Do not review from the prompt alone when a diff or files are available.
• Keep the pass read-only. If the user also asks for fixes, report the audit first so accepted findings can be separated from optional cleanup.
• Do not invent findings to fill the five categories. A clean diff should receive a clean verdict.
• Distinguish a valid finding from its remediation. Recommend the smallest repository-consistent alternative that closes the finding.
• Match the user's language and keep the report compact.

Resolve the target

1. Use an explicitly named PR, commit, branch, diff, file set, or directory.
2. Otherwise, in a Git repository, inspect the current branch change against its real base or upstream. For active local edits, include staged, unstaged, and relevant untracked files.
3. If no concrete change can be resolved, stop with BLOCKED and ask for the target. Do not guess from recently modified files.

Before judging the code, read applicable repository instructions and establish the requested outcome, explicit scope, and out-of-scope items. If scope is unclear, mark that limitation instead of labeling every adjacent change as scope creep.

Build the evidence pack

Inspect only what is needed to answer the audit:

• changed-file list, diff stat, and full relevant diff;
• nearby implementations of the same responsibility;
• existing owner, utility, enum, service, component, or API pattern that the change could reuse;
• declared types, call sites, discriminants, generated schemas, contracts, and tests needed to distinguish required safety from speculative defense;
• the user request, issue, or plan that defines scope.

Use repository search rather than recollection when claiming a pattern is new or conventional. A pattern is not suspect merely because it is unfamiliar to the reviewer.

Apply the five lenses

1. Overengineering and excessive defense

Look for machinery whose removal would not violate the request, a repository rule, a public contract, an invariant, or a demonstrated failure path. Common signals include speculative retries, fallback layers, feature flags, configuration, normalization, wrappers, registries, or error branches added without a current requirement.

Before accepting null, undefined, shape, or default guards as necessary, trace where the value is created and which valid callers can reach the changed code. Repeated optional chaining, fallback values, impossible default branches, typeof or in checks, casts, and non-null assertions can be symptoms of a parameter, field, generic, or union declared broader than its actual owner contract. When every valid caller or discriminated state already guarantees the shape, flag the downstream defense and prefer narrowing the type at the source so impossible states are not propagated.

Do not narrow a type merely to delete guards. Preserve runtime validation for unknown, decoded JSON, storage reads, feature flags, external SDKs, and other trust boundaries. A type-narrowing finding requires evidence from all valid callers, a discriminated union, generated schema, or another authoritative contract; if that evidence is incomplete, mark the criterion 확인 불가 rather than recommending an unsafe assertion or a lying type.

Preserve validation and error handling at trust boundaries, authorization and security checks, data-loss prevention, accessibility affordances, and repository-required invariants. These are not removable defensive code merely because the happy path is simpler.

2. Repository-pattern drift

Compare the change with the nearest code that owns the same responsibility. Flag a new pattern only when an existing pattern can express the requirement more directly and the diff gives no concrete reason to diverge.

Treat a new pattern as justified when the existing path cannot satisfy the contract, ownership boundary, safety requirement, or reuse need. State that evidence rather than rewarding conformity for its own sake.

3. Unnecessary functions and abstractions

Question one-use helpers, classes, wrappers, variables, types, and modules when they only rename a simple expression or hide a side effect that is clearer at the call site.

Do not recommend inlining when a name exposes a real policy, the logic has multiple meaningful steps, it is reused, it creates a useful test seam, or it isolates a trust or ownership boundary. The test is whether the abstraction lowers the reader's reasoning cost, not its call count alone.

4. Scope creep

Map every changed file and behavioral change to the requested outcome. Flag unrelated formatting, renaming, cleanup, refactoring, docs, configuration, dependency, API, data, or behavior changes that can be removed without weakening the requested result.

Do not classify mechanically required generated output, tests, migrations, or contract updates as scope creep when the repository or changed interface requires them.

5. Minimal-diff opportunity

Ask whether the same outcome can be achieved by reusing an existing owner or by changing fewer concepts, files, branches, or public surfaces. Prefer deleting orphan changes over polishing them.

Do not trade away readability, explicit policy, tests, types, safety, or contract correctness just to reduce line count. A broader diff is acceptable when each part is traceable to the outcome and narrower alternatives would be incorrect.

Admit a finding only with evidence

A finding should identify:

1. the exact changed location;
2. which of the five lenses it violates;
3. the request, repository precedent, contract, declared type, or call-site evidence supporting the judgment;
4. the concrete cost of keeping it; and
5. a smaller safe alternative.

For a type-narrowing finding, cite both the unnecessarily broad type and the caller, discriminant, schema, or owner contract proving that a narrower type is valid. The minimum alternative should narrow that source type or state model and remove only the defenses that become statically impossible; do not replace guards with casts or non-null assertions.

Use 필수 only when the change causes scope or behavior drift, duplicates a source of truth, breaks an owner or repository boundary, or adds material unjustified surface. Use 권장 for a real simplification whose current form remains correct. Omit taste-only comments and hypothetical edge cases.

Report format

Use this structure, translated to the user's language:

판정: CLEAN | TRIM | BLOCKED
검토 범위: <diff/base/files and stated outcome>

발견사항
- [필수|권장] [과설계|타입 좁히기|패턴 이탈|불필요한 추상화|범위 이탈|최소 diff] path:line
  근거: <concrete evidence and cost>
  최소 대안: <smallest safe change>

5개 기준
1. 과설계/방어코드/타입 좁히기: clear | finding N | 확인 불가
2. 기존 패턴: clear | finding N | 확인 불가
3. 함수/추상화: clear | finding N | 확인 불가
4. 작업 범위: clear | finding N | 확인 불가
5. 최소 diff: clear | finding N | 확인 불가

검증 한계: <only if relevant>

Sort findings by required action and impact, not by file order. When there are no findings, write 발견사항 없음 and still show the five-line coverage summary. Do not add generic praise or unrelated review advice.

Boundaries

• This skill does not replace correctness, security, performance, architecture, or runtime validation reviews.
• Do not modify code, open a PR, post a comment, or broaden the review target as part of this audit.
• Do not turn one local preference into a repository-wide rule without evidence.
• If the real issue is an incorrect owner, contract, or behavior, report that concrete issue instead of disguising it as a style simplification.