repo-review
Review only the exact worktree and commit supplied by the workflow. First verify its HEAD
equals the supplied commit and its current branch equals the supplied branch. If either
differs, report a blocking integrity finding instead of reviewing another checkout.
Method
- Scope the diff — changed files, new endpoints, migrations, pages and components, and
their blast radius in the codebase map.
- Line it up against the approved LLD, the shared contract and the repository's
instructions. Where the harness supports it you may spawn one fresh read-only subagent
following this skill for an independent pass.
- Review every dimension below that applies to this repository's technology. Read-only:
never edit code.
- Consolidate findings by severity and decide
blocking.
Checklist
- Completeness — every task in the task list your instructions name is built, and nothing
outside the LLD's scope is; a task marked as needing a human gate (migrations, permissions,
payments, production config, dependencies) matches the LLD exactly.
- Correctness — logic matches the LLD and acceptance criteria; concurrency, transactions
and idempotency for retried writes.
- Contract — endpoints, payloads, error shape and status codes match exactly; a consumer
calls the API as published; breaking changes are flagged, never silent.
- Security — authorization on every operation; input validation and bounds; injection;
output encoding and XSS; secrets and PII in code, logs or analytics; SSRF; tokens in client
storage.
- Compatibility and data — additive changes; migrations expand → migrate → contract,
reversible, indexed, with a safe backfill.
- Reliability and performance — timeouts, retries with backoff, rate limits and payload
caps; no N+1 or unbounded queries; code-splitting and list virtualization in UIs.
- UI — every state reachable (loading, empty, success, validation error, API error,
permission denied, retry); WCAG AA keyboard, focus, labels and contrast; double-submit and
optimistic-update rollback; localizable strings.
- Observability — structured logs without PII, metrics and traces on new paths.
- Tests — branches, error paths and the acceptance-criteria edge cases are tested, and the
assertions check behavior. Inspect every change to an existing test: when your instructions
list changed test files, say for each whether the approved design justifies it. A weakened,
skipped or deleted assertion without that basis is a blocker.
- Domain rules (only when the workspace has them: the
## Invariants and consistency and
## Change scenarios sections of docs/technical/<domain>.md, or
docs/impact/side-effects.yaml) — the diff breaks no invariant (<PREFIX>-INV-NNN); a moved or
renamed enforcing line keeps its ID comment; for each
change scenario whose when_changing files or symbols the diff touches, the places it lists
under also_impacts still hold. A mismatch report your instructions name lists names the code
no longer matches: one this branch caused is blocking. No rules in the workspace: skip this.
Findings
Every finding needs file:line evidence (quoted code, test or contract clause, or the
absence of one) and the smallest safe recommendation:
- severity: blocking | major | minor
area: completeness | correctness | contract | security | compatibility | data | reliability | performance | ui | observability | tests
file: <path:line>
evidence: <quote or gap>
recommendation: <smallest safe change>
Each finding has one severity, the same in the report and the findings file:
blocking — must change before this code ships: a correctness, security, contract or data-loss
defect, a missing task, or a weakened test without a design basis;
major — a real problem worth fixing that does not make the change unsafe to ship;
minor — style, naming, a suggestion.
Sort blocking → major → minor. blocking is true exactly when a blocking finding is open or
upheld. Write the report outside the product worktree and record the reviewed commit at its top.
Findings file. When your instructions give a findings path, also write every finding there as
JSON — the workflow decides from this file, not from your prose:
{"schema_version": 1, "findings": [{"id", "severity": "blocking" | "major" | "minor", "area", "finding", "evidence", "status": "open" | "upheld" | "withdrawn" | "resolved"}]}. Keep ids stable
across rounds; new findings get new ids. A finding new in a re-review carries
"introduced_by_revision": true only when the revision since your last round caused it; when
your instructions give the changes since that round, review those rather than re-auditing
unchanged text. Raise everything you can see in the first round.
Re-review. When your instructions supply a previous review (a re-review after a fix), read it
first, with the author's resolutions when your instructions give them, and review only the diff
from the commit it records to the supplied commit. Mark a fixed finding resolved (or keep it
open if the fix falls short) and answer each contest: withdrawn when the author is right,
upheld with your reason when not. A contested finding is never silently dropped. Check the new
change for regressions; do not re-audit unchanged code or raise new minor findings on it.
Safety
Read-only. Never edit product code, push, or change the worktree; write only the report and the
findings file.
Output contract
Return review_path, literal boolean blocking, and a one-line summary (verdict and the
count of blocking findings) as last-line JSON.
1---2name: repo-review3description: Review one repository's exact implementation worktree and commit against its LLD and contract, with evidence-backed findings and a blocking verdict.4allowed-tools: Read, Grep, Glob, Bash, Write, Task5tags: [sdlc, review, repository]6metadata:7 source: https://skillmd.com/skills/keyvaluesoftwaresystems/repo-review8---910# repo-review1112Review only the exact `worktree` and `commit` supplied by the workflow. First verify its HEAD13equals the supplied commit and its current branch equals the supplied branch. If either14differs, report a blocking integrity finding instead of reviewing another checkout.1516## Method17181. **Scope the diff** — changed files, new endpoints, migrations, pages and components, and19 their blast radius in the codebase map.202. **Line it up** against the approved LLD, the shared contract and the repository's21 instructions. Where the harness supports it you may spawn one fresh read-only subagent22 following this skill for an independent pass.233. **Review every dimension below** that applies to this repository's technology. Read-only:24 never edit code.254. **Consolidate** findings by severity and decide `blocking`.2627## Checklist2829- **Completeness** — every task in the task list your instructions name is built, and nothing30 outside the LLD's scope is; a task marked as needing a human gate (migrations, permissions,31 payments, production config, dependencies) matches the LLD exactly.32- **Correctness** — logic matches the LLD and acceptance criteria; concurrency, transactions33 and idempotency for retried writes.34- **Contract** — endpoints, payloads, error shape and status codes match exactly; a consumer35 calls the API as published; breaking changes are flagged, never silent.36- **Security** — authorization on every operation; input validation and bounds; injection;37 output encoding and XSS; secrets and PII in code, logs or analytics; SSRF; tokens in client38 storage.39- **Compatibility and data** — additive changes; migrations expand → migrate → contract,40 reversible, indexed, with a safe backfill.41- **Reliability and performance** — timeouts, retries with backoff, rate limits and payload42 caps; no N+1 or unbounded queries; code-splitting and list virtualization in UIs.43- **UI** — every state reachable (loading, empty, success, validation error, API error,44 permission denied, retry); WCAG AA keyboard, focus, labels and contrast; double-submit and45 optimistic-update rollback; localizable strings.46- **Observability** — structured logs without PII, metrics and traces on new paths.47- **Tests** — branches, error paths and the acceptance-criteria edge cases are tested, and the48 assertions check behavior. Inspect every change to an existing test: when your instructions49 list changed test files, say for each whether the approved design justifies it. A weakened,50 skipped or deleted assertion without that basis is a blocker.51- **Domain rules** (only when the workspace has them: the `## Invariants and consistency` and52 `## Change scenarios` sections of `docs/technical/<domain>.md`, or53 `docs/impact/side-effects.yaml`) — the diff breaks no invariant (`<PREFIX>-INV-NNN`); a moved or54 renamed enforcing line keeps its ID comment; for each55 change scenario whose `when_changing` files or symbols the diff touches, the places it lists56 under `also_impacts` still hold. A mismatch report your instructions name lists names the code57 no longer matches: one this branch caused is blocking. No rules in the workspace: skip this.5859## Findings6061Every finding needs `file:line` evidence (quoted code, test or contract clause, or the62absence of one) and the smallest safe recommendation:6364```65- severity: blocking | major | minor66 area: completeness | correctness | contract | security | compatibility | data | reliability | performance | ui | observability | tests67 file: <path:line>68 evidence: <quote or gap>69 recommendation: <smallest safe change>70```7172Each finding has one severity, the same in the report and the findings file:7374- `blocking` — must change before this code ships: a correctness, security, contract or data-loss75 defect, a missing task, or a weakened test without a design basis;76- `major` — a real problem worth fixing that does not make the change unsafe to ship;77- `minor` — style, naming, a suggestion.7879Sort blocking → major → minor. `blocking` is true exactly when a `blocking` finding is open or80upheld. Write the report outside the product worktree and record the reviewed commit at its top.8182**Findings file.** When your instructions give a findings path, also write every finding there as83JSON — the workflow decides from this file, not from your prose:84`{"schema_version": 1, "findings": [{"id", "severity": "blocking" | "major" | "minor", "area",85"finding", "evidence", "status": "open" | "upheld" | "withdrawn" | "resolved"}]}`. Keep ids stable86across rounds; new findings get new ids. A finding new in a re-review carries87`"introduced_by_revision": true` only when the revision since your last round caused it; when88your instructions give the changes since that round, review those rather than re-auditing89unchanged text. Raise everything you can see in the first round.9091**Re-review.** When your instructions supply a previous review (a re-review after a fix), read it92first, with the author's resolutions when your instructions give them, and review only the diff93from the commit it records to the supplied commit. Mark a fixed finding `resolved` (or keep it94`open` if the fix falls short) and answer each contest: `withdrawn` when the author is right,95`upheld` with your reason when not. A contested finding is never silently dropped. Check the new96change for regressions; do not re-audit unchanged code or raise new minor findings on it.9798## Safety99100Read-only. Never edit product code, push, or change the worktree; write only the report and the101findings file.102103## Output contract104105Return `review_path`, literal boolean `blocking`, and a one-line `summary` (verdict and the106count of blocking findings) as last-line JSON.