htools-fresh-eyes-review

name

htools-fresh-eyes-review

description

A careful fresh-eyes bug review that reads the code, fixes genuine correctness and security defects with small contained changes, then dispatches independent review agents and loops until a pass comes back clean. Two modes — the entire repo, or just the changes made this session. Use when asked to review for bugs or security issues, hunt for bugs/errors/vulnerabilities/problems, sanity-check a change, or "look with fresh eyes".

htools-fresh-eyes-review

Read the code as if seeing it for the first time, fix the real defects, and loop until a pass finds nothing. Correctness and security first, then the small unambiguous wins for simplicity, readability, and maintainability. Every change is small and contained — this is a bug hunt, never a style rewrite. Tool- and language-agnostic: it adapts to whatever project it's run in.

Two modes

• repo — the entire repository. Triggers: repo, all, whole, everything.
• session — only the changes made this session: the uncommitted working tree (git status + git diff HEAD, untracked files included) — what was just edited. Triggers: session, changes, diff. To review a committed range instead (work was committed mid-session), pass a base ref: that mode's surface becomes git diff <base>.

No mode given: if the working tree has changes, do session; otherwise repo. State which you chose and how to force the other.

Baseline first

Before touching anything, learn the project and confirm it starts green:

• Read CLAUDE.md / AGENTS.md / contributing docs for conventions and the canonical check command. They override anything here.
• Find and run the project's own check/test command — a just ci/just test recipe, make check, npm test, cargo test, pytest, whatever it uses. A red baseline is itself the first finding: report it, don't stack changes on a broken tree.

Read with fresh eyes

Actually read — don't skim — and read enough context to judge each line against its callers and invariants (code is only correct relative to them).

• repo: map the tree (git ls-files), then read the source. For a large repo, fan out — dispatch read-only review agents partitioned by subsystem so each covers its area in depth, and keep their conclusions, not the file dumps.
• session: read the whole diff, plus the surrounding code of each touched file, plus the call sites of anything changed.

Hunt for genuine defects, in priority order:

1. Correctness — logic errors, off-by-ones, wrong conditions, panics on realistic input, broken round-trips, ordering/races, resource leaks, contracts violated. Each finding needs a concrete repro: inputs → wrong output.
2. Security — untrusted input reaching a dangerous sink (injection, command execution, path traversal, SSRF), missing authn/authz checks, secrets in source or logs, unsafe deserialization, crypto misuse, TOCTOU. Each finding needs a concrete attack: who controls the input → what they gain. No speculation about inputs that can't occur.
3. Clarity — comments that contradict the code, dead logic, a confusing name — but only where the fix is unambiguous, not a matter of taste.
4. Duplication — the same non-trivial logic repeated where one well-named helper would unify it. Abstract only when the copies share a single real reason to change; coincidental resemblance that will drift apart is better left duplicated than welded under the wrong abstraction. The unification has to remove more complexity than the indirection it introduces.

Fix small, prove it

• One contained change per defect. Match the surrounding code's idiom, naming, and comment density so the fix reads like it was always there.
• Where the project has tests, add a regression test that fails before and passes after — that's how a fix earns its place.
• An invariant a "fix" would break is a stop sign, not a thing to edit through: a change that contradicts how something is documented, or that you didn't write, gets surfaced, not forced. (Example: editing a shipped DB migration breaks its checksum — leave it and report instead.)
• Re-run the baseline check after each batch. Keep it green.

Stay in bounds

• No style/naming/refactor churn, no reformatting, no "while we're here" rewrites. Removing genuine duplication (above) is deliberate, not churn — but it stays as small and contained as any other fix, never a sweeping rework.
• No speculative hardening for inputs that can't occur, no new dependencies, no scope creep past the chosen mode.
• Don't commit. Leave changes in the working tree for review unless asked.

Converge

After fixing, run an independent verification pass — your own eyes are no longer fresh. Dispatch review agents (scale to surface area: one for a small session diff, several partitioned by subsystem for a whole repo), each scoped to correctness and security only, each told to answer with file:line — bug — repro lines or exactly NO BUGS FOUND, and forbidden to suggest style. Triage what they return; fix anything real, ignore the noise.

Then loop the whole review → fix → verify cycle until a pass makes no changes. Stop there — don't invent work to look busy.

Report

A terse close: per defect, file:line — what was wrong — the fix, then the baseline command and its green result. If a pass found nothing, say so plainly. Flag anything left unfixed and why — out of scope, needs your call, or too risky to touch blind.