code-review

Code Review

Iron Law

FINDINGS FIRST. BLOCK ON CORRECTNESS, SAFETY, DATA LOSS, AND UNPROVEN CLAIMS.

When to Use

• Independent review of your diff in the workflow completion loop, after proof and before claiming done. Default for any non-trivial agent-generated change; use a fresh-context subagent, review agent, or separate session when the host provides one.
• Diff review: local, branch, or a GitHub PR through the host's GitHub surface.
• Review-comment follow-up on the user's own PRs.

When NOT to Use

• Commit grouping or history repair only; use git-workflow.
• A narrow domain-only review where security, database, api, or ui-design is sufficient.

Rules

1. Review owns defect discovery; proof owns checks. Find behavioral bugs, regressions, unsafe edge cases, missing evidence, and merge blockers.

2. Reports to the requester put findings first by severity. Each names a file/line or thread anchor, issue, impact, fix direction, and evidence or missing proof. Summaries follow. Ask only when uncertainty blocks a finding.

   Severity	When to use
   Critical	Exploitable security, data loss, broken auth, destructive migration, outage risk
   High	Incorrect behavior, broken contract, missing authorization, race, serious regression
   Medium	Maintainability, error handling, observability, compatibility, or test gaps likely to cause defects
   Low	Non-blocking clarity, skip unless asked

3. Every review includes a security pass and a proof-evidence pass. A claim the review cannot verify is reported as unproven. Red or absent CI makes the review unproven, not blocked from inspection. Missing intent on a non-trivial PR is a finding.

4. Repository constraints beat generic advice. Check declared runtime, framework, dependency, CI, and support policy before applying a language reference.

5. Maintainability findings need a concrete risk: hidden state, coupled effects, stale flags, duplicated rules with divergent meaning, dead compatibility, unreachable paths. Style is not blocking unless it hides ambiguity or unsafe control flow.

6. Agent-written code gets an AI-generated risk pass: speculative abstraction, unnecessary shims, dead defensive code, test theater, fabricated APIs, scope creep, refactor drift, and code too large or vague for the human to keep a mental model of. Hand-rolled versions of solved problems (HTTP clients, ORMs, parsers, retry loops, validators, crypto) are findings.

7. A diff the human cannot review in one sitting gets a declared partial scope, and split/scope becomes a finding. Bundled reformatting or unrelated edits are split before deep review. Sample generated, vendored, and lockfile churn only enough to detect obvious risk.

8. GitHub reads use host permissions; git-workflow owns access. Modify a PR only if it belongs to the user or the user asks. Get explicit permission for every published write: comment, review, thread resolution, or push. Address the smallest coherent set of feedback and surface conflicts before editing.

9. PR comments are courteous and specific: critique code, explain impact, and label required versus optional feedback. Ask genuine questions for clarification or alternatives; state verified blockers plainly. Suggest fixes and acknowledge specific strengths when useful. Match the GitHub review decision to requiredness.