code-review
Review a code change for correctness, simplification, and missing tests; produces a structured review summary keyed to the diff. Reviews a diff; not test-gap hunting (coverage-gap).
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- code-review
- description
- Review a code change for correctness, simplification, and missing tests; produces a structured review summary keyed to the diff. Reviews a diff; not test-gap hunting (coverage-gap).
03 SKILL.md 正文
code-review
Review a code change with two lenses: correctness (does it do what the PRD says?) and simplification (could it do the same with less?).
Mode: analytical — judgment inside a fixed frame. Keep the output shape; every verdict cites its evidence; unknowns are marked [TBD] or [VERIFY], never filled in.
When to use
- A workflow invokes
polymath-engineering:code-reviewafterfeature-dev. - The user says "review this", "look this over", "what would you change?".
Inputs
- The diff under review (typically the current git diff or the file set from
feature-dev). - PRD + acceptance criteria for the change (preferred).
- Project conventions.
Project localization
Before the procedure, resolve the project snapshot —
${POLYMATH_DATA_DIR:-$HOME/.polymath/data}/polymath-core/project-context.json
(ignore it if its _meta.source belongs to another repo; absent → read
.polymath/project.yaml directly; neither → built-in defaults). Then apply
(contract: polymath-core:project-context):
conventions_docs: read rolesreview-checklistplus the stack docs (backend-stack,frontend-stack,database) that match the diff; treat their Hard rules as review axes; surface[VERIFY: …]items only when they affect a finding.skill_overrides["polymath-engineering:code-review"]: read eachadditional_contextfile; apply eachadditional_axesentry as an extra review axis. Citeconventions.code_review_checklistin the review summary when set.
Procedure
- Establish intent. Read the PRD's acceptance criteria — each is a checkpoint the code must satisfy. No PRD? Derive intent from the PR description, linked issue, or commit messages, and state that assumption at the top of the review.
- Get the exact diff. Review against the merge base, not a moving branch tip:
git diff $(git merge-base origin/<base> HEAD)(default base: the remote's default branch), plus staged and unstaged changes when reviewing local work. Note untracked files the change depends on. - Read the diff in dependency order (config → models → core logic → API → UI), and read beyond it: for every changed signature, contract, or shared helper, open its callers. Many bugs live in the unchanged code that consumes the change.
- For each acceptance criterion, verify a test exists that would fail if the corresponding code were broken. If not, flag it as a missing test.
- Correctness pass:
- Off-by-one, signedness, encoding, time-zone, null/empty handling.
- Concurrency: races, ordering, atomicity, idempotency of retried paths.
- Error paths: do they leave the system in a recoverable state? Resources (files, connections, locks) released on every path?
- Boundary: empty input, single element, max input.
- Compatibility: does it break existing callers, persisted data, or a public API/schema?
- Performance on realistic sizes: N+1 queries, unbounded loops or memory, work inside hot paths.
- Simplification pass:
- Could two functions be one? (Only if one of them has no other caller.)
- Are there unused parameters, branches, or imports?
- Are abstractions premature?
- Are comments restating what the code already says?
- Security smell check:
- User input directly in SQL, HTML, shell, paths.
- Secrets in code or logs.
- Missing AuthN / AuthZ on new endpoints; object-level checks on user-supplied IDs.
- Test smell check:
- Tests asserting implementation details.
- Tests that pass without the code change (mock theater).
- Flaky test patterns (sleeps, time-of-day).
- Verify before reporting. For each correctness or security finding, trace a concrete input or path that triggers it. If you can't, downgrade it to a question. Separate issues the change introduced from pre-existing ones (report those last, as non-blocking).
Output
Structured summary keyed to the diff:
Verdict: REQUEST CHANGES (1 blocker, 1 major, 2 minor)
Intent source: PRD docs/prds/rate-limit.md (or: "derived from PR description")
Acceptance criteria coverage:
- AC1: PASS — test at <file>:<line>
- AC2: MISSING — no test for refund path
Correctness findings:
- [blocker] <file>:<line> — boundary: rate-limit window misses requests exactly at start
Trigger: request at t = window_start → counted in neither window.
Simplification findings:
- <file>:<line> — extracted helper has one caller; inline it
Security findings:
- <file>:<line> — user-supplied path concatenated without normalization
Test smell findings:
- [minor] <file>:<line> — assertion checks private member rather than observed behavior
Pre-existing (not introduced by this change, non-blocking):
- <file>:<line> — …
No emoji, no praise filler. Findings only.
Quality bar
- Every finding cites file:line and carries a severity (blocker / major / minor).
- Every correctness/security finding names the input or path that triggers it; unproven suspicions are phrased as questions.
- Every "MISSING" finding either nominates a missing test or proposes an alternative way to verify.
- No nit-style comments mixed in with correctness findings; pre-existing issues are separated from introduced ones.
- One verdict: APPROVE, APPROVE WITH NITS, or REQUEST CHANGES.
04 同仓库更多 Skills
runbook
Write or refresh an operational runbook for an alert/symptom; structured as TL;DR + Pre-checks + Steps + Verification + Rollback + Escalation.
rfc
Draft a lightweight design RFC to docs/rfcs/<slug>.md; Summary, Motivation, Detailed design, Drawbacks, Alternatives, Unresolved questions. A proposal to debate, not a recorded decision (adr).
editorial-pass
Review and tighten prose in a Markdown artifact for a target tone (terse, formal, friendly) without dropping information; preserve quotations and load-bearing constraints.
architecture-review-facilitation
Run an architecture review as a process — entry criteria, reviewer checklist, decision log, and follow-up actions — pairing the design artifact with a red-team pass.
architecture-doc
Write a C4-style architecture document; System Context + Containers (+ Components when interesting) with mermaid diagrams. Describes structure, not a decision (adr) or proposal (rfc).
adr
Write an Architecture Decision Record (Michael Nygard format) to docs/adrs/NNNN-<slug>.md; frontmatter validated by the ADR artifact schema. Records a made decision, not a proposal to debate (rfc).