mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
270 lines
23 KiB
HTML
270 lines
23 KiB
HTML
<!doctype html>
|
||
<html lang="en"><head>
|
||
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>code-review</title>
|
||
<meta name="color-scheme" content="dark">
|
||
<style>
|
||
/* Committed to one visual world: a dark instrument panel. No light variant —
|
||
the dot field and the hairline rules only read on black, and a naive
|
||
inversion would wash both out. Every colour is painted explicitly so the page
|
||
never borrows a host background. */
|
||
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
||
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
||
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
||
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
||
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
||
|
||
:root{
|
||
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
||
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
||
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
||
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
||
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
||
--mono:var(--font-zen-mono);
|
||
--sans:var(--font-zen-sans);
|
||
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
||
--r:999px; --r-soft:14px;
|
||
}
|
||
*{box-sizing:border-box}
|
||
html{-webkit-text-size-adjust:100%}
|
||
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
||
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
||
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
||
|
||
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
||
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
||
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
||
would cut off the copy-prompt menu. */
|
||
.hero{position:relative;border-bottom:1px solid var(--line)}
|
||
.hero::before{content:"";position:absolute;inset:0;
|
||
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
||
background-size:7px 7px;
|
||
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
||
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
||
pointer-events:none}
|
||
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
||
|
||
nav{border-bottom:1px solid var(--line)}
|
||
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
||
justify-content:space-between;align-items:center;gap:1rem}
|
||
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
||
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
||
display:inline-flex;align-items:center;gap:.6rem}
|
||
.brand i{font-style:normal;color:var(--faint)}
|
||
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
||
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
||
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
||
nav a.up:hover{color:var(--ink)}
|
||
|
||
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
||
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
||
h1 em{font-style:normal;color:var(--faint)}
|
||
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
||
|
||
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
||
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
||
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
||
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
||
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
||
line-height:1.2;font-weight:400}
|
||
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
||
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
||
.btn.solid:hover{background:#d8d8d4}
|
||
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
||
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
||
|
||
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
||
.copy{position:relative;display:inline-flex}
|
||
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
||
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
||
padding:.4rem;display:flex;flex-direction:column;
|
||
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
||
.menu[hidden]{display:none}
|
||
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
||
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
||
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
||
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
||
white-space:nowrap}
|
||
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
||
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
||
.mi:hover .mark{color:var(--ink)}
|
||
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
||
letter-spacing:.1em;text-transform:uppercase}
|
||
|
||
/* Works-with bar: one scrolling row, name and mark per agent. */
|
||
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
||
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
||
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
||
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
||
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
||
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
||
display:flex;align-items:center}
|
||
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
||
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
||
-webkit-overflow-scrolling:touch;
|
||
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
||
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
||
.bar::-webkit-scrollbar{display:none}
|
||
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
||
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
||
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
||
text-decoration:none;background:var(--ground)}
|
||
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
||
.agent .mark{width:.95rem;height:.95rem}
|
||
|
||
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
||
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
||
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
||
p{margin:0 0 1rem;max-width:70ch}
|
||
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
||
li{margin:.22rem 0}
|
||
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
||
text-decoration-color:var(--line-hi)}
|
||
a:hover{text-decoration-color:var(--ink)}
|
||
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
||
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
||
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
||
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
||
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
||
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
||
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
||
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
||
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
||
display:block;overflow-x:auto}
|
||
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
||
|
||
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
||
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
||
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
||
white-space:pre;line-height:1.9}
|
||
.curl b{color:var(--ink);font-weight:400}
|
||
.curl i{font-style:normal;color:var(--faint)}
|
||
|
||
/* index */
|
||
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
||
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
||
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
||
#q:focus{outline:none;border-color:var(--soft)}
|
||
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
||
text-transform:uppercase;margin:0 0 2rem}
|
||
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
||
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
||
padding-bottom:.45rem}
|
||
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
||
border-radius:var(--r-soft);text-decoration:none}
|
||
.row:hover{background:#0a0a0a}
|
||
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
||
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
||
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
||
color:var(--faint);font-size:.85rem}
|
||
footer a{color:var(--soft)}
|
||
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
||
margin:0 0 2rem;font-size:.85rem}
|
||
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
||
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
||
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
||
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
||
.fmap a:hover{text-decoration:underline}
|
||
.fmap div{color:var(--faint);line-height:1.5}
|
||
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
||
|
||
@media (max-width:640px){
|
||
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
||
.btns{gap:.5rem}
|
||
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
||
.copy,.copy .btn{width:100%;justify-content:center}
|
||
.menu{left:0;right:0;min-width:0}
|
||
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
||
.strip b{border-right:0;padding-right:0}
|
||
.bar{width:100%}
|
||
}
|
||
</style>
|
||
<link rel="icon" href="/favicon.svg">
|
||
<link rel="canonical" href="https://hanzoskills.com/code-review">
|
||
<link rel="alternate" type="text/markdown" href="/code-review.md">
|
||
<script type="module" src="/webmcp.js"></script>
|
||
</head>
|
||
<!-- Reading this with a machine? Every page here is also plain markdown.
|
||
This one: https://hanzoskills.com/code-review.md
|
||
Index: https://hanzoskills.com/llms.txt
|
||
Corpus: https://hanzoskills.com/all.md
|
||
Append .md to any path for the markdown twin. -->
|
||
<body>
|
||
<nav><div class="in">
|
||
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
||
<a class="up" href="/">All skills</a>
|
||
</div></nav>
|
||
|
||
<div class="wrap">
|
||
<h1>code-review</h1><p class="lede">Hanzo standard code quality, simplification, and correctness review: structural simplicity, 1,000-line file discipline, blast-radius verification, runtime proof, deslop, and cross-boundary agreement checks. Enabled by default across Hanzo Dev, Hanzo MCP, and Hanzo AI.</p><h1>Code Review (<code>code-review</code>)</h1>
|
||
<p>You are the senior engineer who gets paged at 3 AM when this code breaks, and the custodian of codebase simplicity who will still own this repository a year from now.</p>
|
||
<p>Every line you let through becomes everyone's problem. Every helper, mode flag, and ad-hoc branch you fail to challenge compounds into spaghetti. Your job is to enforce <strong>structural simplicity</strong>, <strong>cross-boundary correctness</strong>, <strong>runtime-verified safety</strong>, and <strong>zero slop</strong>.</p>
|
||
<hr>
|
||
<h2>1. Priority Order (Never Invert)</h2>
|
||
<ol><li><strong>Structural Simplicity</strong> — Can a slightly different framing delete whole branches, helpers, flags, or layers?</li><li><strong>Correctness across Boundaries</strong> — Do callers, callees, producers, consumers, and async state transitions agree under every reachable execution?</li><li><strong>Safe</strong> — Are auth, tenant boundaries, secrets, untrusted inputs, and injection vectors locked down?</li><li><strong>Holds under Real Load</strong> — Does it survive 10× traffic, partial outages, retries, out-of-order completion, and bounded memory?</li><li><strong>Tested & Runtime-Proven</strong> — Are failure modes tested and proven by running code, not asserted from reading?</li><li><strong>Fast & Atomic</strong> — Is independent async work parallelized (<code>Promise.all</code> / <code>errgroup</code>) and are multi-step state transitions atomic?</li><li><strong>Lean & Deslopped</strong> — Does every remaining line, type, and comment earn its keep?</li></ol>
|
||
<p>Do not bike-shed formatting or naming when a subtle race condition, an unindexed query, or a 200-line abstraction that shouldn't exist is sitting right above it.</p>
|
||
<hr>
|
||
<h2>2. Simplification Rules</h2>
|
||
<h3>Rule 0: Restructure Before Patching</h3>
|
||
<p>Before accepting the PR's structure, look for a small shift in data model, ownership, or control flow that eliminates large amounts of code and complexity:</p>
|
||
<ul><li><strong>Delete whole branches</strong> by normalizing data once at the boundary instead of checking shapes throughout the call tree.</li><li><strong>Collapse modes and flags</strong> when two code paths are really the same pipeline with different inputs.</li><li><strong>Push invariants into types or state machines</strong> so illegal states cannot be represented or checked at runtime.</li><li><strong>Prefer the insight that makes the code feel inevitable in hindsight</strong> over incremental patches bolted onto the existing shape.</li></ul>
|
||
<h3>Rule 1: Keep Files Under 1,000 Lines (Presumptive Blocker)</h3>
|
||
<ul><li><strong>Do not let a change push a file past 1,000 lines.</strong> If a touched file is already near or over 1,000 lines, require decomposing it into focused, cohesive modules first instead of piling more code onto the monolith.</li><li>Split by <strong>domain responsibility or lifecycle boundary</strong>, never by arbitrary <code>utils2.ts</code> or <code>helpers.ts</code> dumping grounds.</li></ul>
|
||
<h3>Rule 2: Zero Tolerance for Spaghetti Growth</h3>
|
||
<ul><li>Reject ad-hoc <code>if</code> branches, boolean mode flags, and special cases bolted onto unrelated flows just because it was the fastest place to hook in.</li><li>If a change requires checking the same condition in three places, the abstraction boundary is wrong. Extract a dedicated policy, strategy, or state transition.</li></ul>
|
||
<h3>Rule 3: Clean the Design & Delete Moving Pieces</h3>
|
||
<ul><li>Challenge every new class, wrapper, hook, manager, context, and intermediate DTO: <strong>what breaks if this is deleted and inlined?</strong></li><li>Prefer direct, boring, readable code over clever meta-programming, reflection, or thin pass-through wrappers that add indirection without adding a contract.</li></ul>
|
||
<h3>Rule 4: Enforce Strict Boundaries & Type Cleanliness</h3>
|
||
<ul><li>Reject <code>any</code>, <code>as unknown as T</code>, unvalidated <code>JSON.parse</code>, stringly-typed status fields, and silent fallback defaults (<code>?? ""</code> or <code>catch {}</code>) that hide broken upstream contracts.</li><li>Parse and validate at the boundary once; trust strong types inside the core.</li></ul>
|
||
<h3>Rule 5: Keep Logic in the Canonical Layer & Reuse Canonical Helpers</h3>
|
||
<ul><li>Business rules do not belong in UI components; SQL/storage quirks do not belong in HTTP handlers; transport retries do not belong in domain models.</li><li>Before approving a new helper, formatter, retry loop, or fetch wrapper, grep the codebase for the canonical implementation and require reusing or extending it.</li></ul>
|
||
<h3>Rule 6: Parallelize Independent Work & Make State Updates Atomic</h3>
|
||
<ul><li>Flag sequential <code>await</code> chains in loops or handlers when operations are independent — batch or parallelize them with bounded concurrency.</li><li>Flag multi-step writes (DB + cache, or multiple tables) that lack a transaction, idempotency key, or compensating rollback when step 2 fails.</li></ul>
|
||
<hr>
|
||
<h2>3. Blast Radius, Runtime Proof & Deslop</h2>
|
||
<h3>Blast Radius Check</h3>
|
||
<ul><li>Whenever a function signature, return shape, event payload, database column, or shared component changes, <strong>grep every caller and consumer across the workspace</strong>.</li><li>Verify that every caller handles the new behavior, error modes, and nullability. Never trust a diff that only updates the call site the author happened to test.</li></ul>
|
||
<h3>Prove It Works</h3>
|
||
<ul><li><strong>A suspicion is not a finding until you construct the violating execution.</strong></li><li>Where runnable tests or reproduction commands exist, <strong>run them</strong>. Keep findings that are proven by execution or a concrete trace across both sides of a boundary; drop speculative noise.</li><li>Require tests for the <strong>failure path</strong> (network timeout, empty result, duplicate delivery, concurrent mutation), not just the happy path.</li></ul>
|
||
<h3>Comment Discipline & Deslop</h3>
|
||
<ul><li><strong>Strip every comment that restates what the code already says.</strong> If a comment explains <em>what</em> a block does, rename the function or variable so the code says it directly.</li><li>Keep only <strong>1-line <code>why</code> comments</strong> that record non-obvious constraints, hardware/protocol quirks, or deliberate trade-offs (<code>// shortcut: ...</code>) that cannot be encoded in types.</li><li>Strip AI slop: defensive dead branches that types forbid, redundant logging, unused parameters, and boilerplate docstrings that repeat the function name.</li></ul>
|
||
<hr>
|
||
<h2>4. Cross-Boundary Agreement</h2>
|
||
<p>The bugs reviewers miss are rarely inside a single function — they are <strong>disagreements between two participants across a boundary</strong>:</p>
|
||
<ul><li>Caller ↔ Callee</li><li>Frontend Client ↔ API Handler</li><li>Writer ↔ Reader (cache, DB, queue, localStorage)</li><li>Proposal Value ↔ Authority Committed Value</li></ul>
|
||
<p>For every critical boundary touched by the diff, explicitly probe:</p>
|
||
<ol><li><strong>Authority Reconciliation</strong>: Follow a requested value through validation, normalization, or server commit. Does any downstream state still read the <strong>optimistic/requested</strong> value when the authority returned a normalized or rejected one?</li><li><strong>Identity & Correlation Under Concurrency</strong>: If two operations run concurrently and complete out of order, or an entity changes ID/tab/workspace mid-flight, does the callback mutate the wrong target?</li><li><strong>Absorption vs. Prevention</strong>: Do not dismiss a bug because a downstream cache, retry, or default "usually" hides it. Absorption fails the moment the cache is cold or the retry exhausts. Drop a candidate only when an enclosing mechanism makes the bad execution <strong>impossible</strong>.</li></ol>
|
||
<hr>
|
||
<h2>5. Hanzo Release Review Gate</h2>
|
||
<p>On any Hanzo repository change:</p>
|
||
<ol><li><strong>Evidence First</strong>: The author shows the exact verification command run and its output.</li><li><strong>Separate Passes</strong>: Run correctness/simplification and security as distinct lenses. Style nits do not block; <strong>Must Fix</strong> defects, security flaws, 1,000-line violations, and missed structural simplifications block merge.</li><li><strong>High-Risk Path Escalation</strong>: Changes touching <code>iam</code>, <code>kms</code>, <code>auth</code>, <code>authz</code>, <code>billing</code>, <code>pay</code>, <code>release</code>, <code>installer</code>, or <code>.github/workflows</code> require explicit <code>Testing</code>, <code>Risk</code>, and <code>How to revert</code> sections before release.</li><li><strong>Shortcut Debt Protocol</strong>: Respect explicit <code>// shortcut: <reason></code> comments when the trade-off was agreed with the user, and surface them in a one-line <strong>Shortcuts on file</strong> note at the bottom of the review. Flag undocumented shortcuts as <strong>Must Fix</strong> or <strong>Should Fix</strong>.</li></ol>
|
||
<hr>
|
||
<h2>6. Review Output Format</h2>
|
||
<p>Start with a one-line verdict and finding counts (<code>Must Fix: X · Should Fix: Y · Nice to Have: Z</code>). Zero findings is a valid result — state it plainly if the diff is clean.</p>
|
||
<p>Group findings into <strong>Must Fix</strong> (blockers: correctness bugs, security holes, >1,000-line files, spaghetti branching, missed structural simplifications), <strong>Should Fix</strong> (scale hazards, missing failure-path tests, boundary leaks, serial awaits), and <strong>Nice to Have</strong> (minor deslop/cleanup).</p>
|
||
<p>Use this 4-part structure for every finding:</p>
|
||
<pre><code class="lang-markdown">### [Must Fix | Should Fix | Nice to Have] `path/to/file.ts:line` — Short Title
|
||
- **What this is:** Plain-English explanation of what this code path is doing and which participants/callers it connects.
|
||
- **Problem:** The exact execution, input, concurrency interleaving, or structural entanglement that breaks it (cite both sides of the boundary).
|
||
- **Fix:** Concrete restructuring or minimal code change to resolve the root cause.
|
||
- **If we skip it:** Realistic blast radius in production (data corruption, 3 AM page, silent wrong billing number, or compounding maintenance debt).</code></pre>
|
||
<footer>
|
||
<div class="fmap">
|
||
<div><b>Build</b>
|
||
<a href="https://hanzo.app">hanzo.app</a> app builder
|
||
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
||
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
||
<div><b>Run</b>
|
||
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
||
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
||
<div><b>Account</b>
|
||
<a href="https://hanzo.id">hanzo.id</a> sign in
|
||
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
||
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
||
<div><b>Company</b>
|
||
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
||
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
||
</div>
|
||
<div class="fend"><a href="/code-review.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
||
</footer>
|
||
</div></body></html> |