one-code-extension 0.4.1 → 0.5.0

package/skills/artifact-design/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: artifact-design
+description: Design guidance and fundamentals for Artifacts. Load before writing any page you will publish with the artifact tool.
+---
+
+Work the way the design lead at a small, versatile studio would: give each client a visual identity at the level of treatment the task calls for. Make deliberate choices about palette, typography, and layout that are specific to this subject, and avoid templated designs.
+
+## Read the request first
+
+Decide the treatment; designing is a given. A doc gets the same craft as a landing page; only the treatment differs. Format is a separate matter: author one self-contained HTML file. The artifact tool stores that one file, so the page's CSS, JS, data and images all live inside it.
+
+Many requests call for a more utilitarian treatment: a plan, a memo, a demo. Make it polished, with real typographic hierarchy, considered spacing, and a proper palette, but avoid over-designing. Most pages don't need a flashy, gigantic hero. Keep flourishes tasteful and limited.
+
+Some requests call for an editorial treatment: a landing page, a game, an app or tool they'll keep or share.
+
+If unsure: a well-composed page is always acceptable; an over-designed visual identity sometimes isn't.
+
+Fundamentals below apply to everything. Follow the editorial process after them only when that reading calls for it.
+
+## Fundamentals for every artifact
+
+**Respect what already exists.** Look for an existing design system first: CLAUDE.md, a tokens or theme file, existing component styles. When one exists, apply it; everything below fills gaps and never overrides. Precedence is always the user's own words, then the project's existing system, then your choices.
+
+**Ground it in the subject.** If the subject isn't already clear, define it: one concrete subject, its audience, and the page's single job. Distinctive choices come from the subject's own world: its materials, instruments, and vernacular. Whatever the treatment, include at least one detail only this subject would have (its real units and scales, its document conventions, its terms of art) as content rather than ornament; it costs nothing even on a plain page. Use real content throughout and never lorem ipsum.
+
+**Pair typefaces.** Typography determines how the page reads even when the page isn't about typography. Load web fonts from Google Fonts by linking it directly (`<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=...&display=swap">`). A face from anywhere else must be inlined as a @font-face data URI. In both cases, declare a real fallback stack: it is what a viewer without a network connection sees. Keep running text near 65 characters wide. Set a type scale and keep to it. Give headings `text-wrap: balance`, give body text comfortable spacing, and give uppercase labels a little letter-spacing.
+
+**Load libraries instead of inlining them.** When the page really needs a library (React, a charting or highlighting package), load its UMD build from cdnjs with one pinned `<script src="https://cdnjs.cloudflare.com/ajax/libs/...">` placed before the inline script that uses its global; don't inline the library's source or hand-write a substitute. cdn.jsdelivr.net is the one other script host to use. Only the script loads this way; inline a library's stylesheet. The page's own CSS and JS, its images (as data URIs), and its data ship inside the page. Most pages don't need any library; use one only when it does substantial work for the page.
+
+**Choose neutrals deliberately.** A pure mid-grey looks unconsidered; a grey with a slight hue bias toward the page's accent looks intentional. Pure white and near-black are fine backgrounds when they suit the subject, as long as you chose the neutral deliberately instead of inheriting a default.
+
+**Design both themes.** The page opens straight in the viewer's browser, which reports the operating system's theme through `prefers-color-scheme`. A page may also offer its own theme toggle, which sets `data-theme="dark"` or `data-theme="light"` on the root element; with no toggle used, there is *no* `data-theme` attribute. Structure the CSS at the token level for all three states. The bare `:root` block defines the complete light palette (for a deliberately dark-first design, swap light and dark consistently through this whole pattern); `@media (prefers-color-scheme: dark)` redefines only the tokens, guarded as `:root:not([data-theme="light"])` so an explicit light choice overrides a dark OS setting; `:root[data-theme="dark"]` redefines them again so the toggle also overrides in the other direction; set `color-scheme: light` on the bare `:root`, and wherever the dark palette applies - both dark blocks, or bare `:root` in a dark-first or single-dark design - set `color-scheme: dark`, so native form controls and scrollbars follow the palette. Style components through the tokens, never directly inside a media or `[data-theme]` block: a color defined only inside `[data-theme]` never applies when no `data-theme` attribute is set, and the page then shows one theme's text on the other theme's background. Two more rules keep each theme consistent. First, `body` must set an explicit `background` from a token; a transparent body shows the browser's default white under a dark palette, with no warning. Second, every element that sets a color takes it from the same token set as the surface behind it, never from a literal that works in only one theme. Declare every token in the bare `:root` block before any media or `[data-theme]` block redefines it; a color that exists only inside one of those blocks is the classic unreadable-artifact bug. Give the second theme the same care as the first: don't simply invert it; keep contrast legible and keep the accent working on both backgrounds. A design that deliberately commits to one visual world (a neon arcade screen, a letterpress invitation) may stay single-theme: then omit the media query and `[data-theme]` blocks entirely but still set the background and every color explicitly, so the page looks right whatever the viewer's theme; do this by choice, never by omission.
+
+**Use layout for spacing.** Lay out sibling groups with flex or grid and `gap` instead of per-element margins, which collapse or double without warning. Keep a side gutter of at least 16px at every width: set it once as side padding on `body` or one outer wrapper, whose vertical padding uses `padding-block` and never a `padding` shorthand that zeroes the sides. Let rows wrap or stack to one column at phone width (about 400px). Give images and any `aspect-ratio` box `max-width: 100%`, and don't give anything a `min-width` wider than the screen. Only wide tables, code, and diagrams may exceed it; give each `overflow-x: auto` on its own container so the page body never scrolls sideways. The page is stored exactly as written, with no skeleton added around it, so write a complete document: `<!doctype html>`, `<meta charset="utf-8">`, and `<meta name="viewport" content="width=device-width, initial-scale=1">`. Size a one-screen app with `height: 100%` on `html` and `body` instead of `100vh`. Use `font-variant-numeric: tabular-nums` wherever digits line up in columns.
+
+**Make repeated elements consistent.** For cards in a row, label/value pairs down a list, or badges on sibling items, use the same edges, baselines, and inner padding on each, and put any recurring element in the same place on each. Let content set a container's height and pick a column count the items fill, so nothing stretches over empty space or sits alone in a row. Make text that can outgrow its track wrap or scroll in its own container; clipped text is a bug.
+
+**Use card styling selectively.** Border, fill, radius, and shadow each mark an element as a separate object. Apply them by role, to set off the one element that needs it; applying the same radius and shadow to every block flattens the hierarchy. Open with big-number tiles only when those figures are the point of the page.
+
+**Draw charts to scale.** Place marks, ticks, and labels with one scale, and make every label name a value the chart actually reaches. Color chart text from the theme tokens so it is readable in both themes. Keep marks, labels, and edges clear of one another and inside the drawing's bounds; in SVG, leave room in the viewBox for the outermost labels and give every drawn shape an explicit fill.
+
+**Make the page complete at rest.** Everything meant to be read is visible once the page has loaded, with no scrolling to trigger it; that first still frame is what a thumbnail, a shared link, and a skimming reader all see. A section may animate in, but from a visible resting state, never left at `opacity: 0` waiting for an observer. Size a hero to its content instead of to the viewport; a `100vh` opener pushes the rest of the page out of that first frame. A tool or app opens in a realistic working state: the user's real data where it exists, otherwise example rows, a loaded sample, or a plausibly filled form, clearly marked as examples and never presented as the user's own figures. The first view shows what the tool does; an empty shell waiting for input shows nothing.
+
+**Avoid AI-generated design.** AI-generated design currently clusters around a few looks: warm cream (#F4F1EA) with a serif display and terracotta accent; near-black with a lone acid-green or vermilion pop; broadsheet hairline rules with dense columns; a purple-to-blue gradient hero on white; Inter or Space Grotesk as the "safe" face; emoji as section markers; everything centered; `rounded-lg` everywhere; accent bar/rail on rounded cards. When the user specifies a visual direction, follow it exactly; their words always win, including when they ask for one of these looks. When nothing is specified, don't use that freedom on one of these defaults.
+
+**Build cleanly.** Watch for overlapping elements, cascade collisions, and silent font fallbacks. Close every non-void element, double-quote attributes, give keyboard focus a visible state, and respect `prefers-reduced-motion`. Give every form control a stable `id` and a label. For generative or decorative graphics, use Canvas or WebGL instead of hand-writing long SVG path data.
+
+**CSS rules.** When writing the CSS, watch your selector specificity. It is easy to generate classes that cancel each other out, e.g. a type-based selector like `.section` and an element-based one like `.cta` both setting padding and margins between sections. Structure the cascade so it doesn't undo your spacing unnoticed.
+
+**Writing the copy.** Treat words as design material and never as decoration. Write from the user's side of the screen: name things by what people recognize instead of how the system is built (a person manages *notifications*; they don't manage *webhook config*). Use active voice; a control states exactly what happens ("Publish", then a toast that says "Published"). Errors explain what went wrong and how to fix it, without apologies or vagueness. Prefer specific to clever. Write plainly, the way a knowledgeable person would talk. Avoid mannered devices: asides set off by em-dashes, "not X, but Y" framing, colon-then-reveal sentences, scare quotes around invented labels, and stock phrases such as "worth noting" or "honest caveat". Prefer short, direct sentences over compressed or clever phrasing.
+
+**Name the page like a product; don't caption it.** The `<title>` is the artifact's name in the artifact gallery and the browser tab, and it gives the reader a first impression of the care taken. Give the page a real name: a short noun phrase, typically two to four words, specific to the subject; or, for a page that exists to answer one question, that question itself, which then is the page's name. Stop at the name; a title that adds its own explanation after a dash or colon reads as generated filler. The name must also identify the page among many: in the gallery it appears beside dozens of other artifacts, and a generic category label that could apply to any of them fails as a name just as an appended explanation does. When a candidate title combines the name with a generic word (a greeting, a category, a page-type label), keep the name; a trim that drops the identifying part and keeps the generic word produces a title that could apply to any page. This rule removes explanations and doesn't require brevity: a multi-word title that already reads as one specific name is finished, and shortening it further only makes it generic. Put the explanation in the one-sentence `description` you pass when publishing; the gallery shows it directly under the title.
+
+**Structure is information.** Structural devices (numbering, eyebrows, dividers, labels) should encode something true about the content instead of decorating it. Many generic designs use numbered markers (01 / 02 / 03), but those fit only if the content actually is a sequence, such as a real process or a typed timeline where the order is information the reader needs. Before adding numbered markers or similar devices, check that they actually make sense.
+
+**When the page is a UI (dashboard, tool).** It is scanned and operated instead of read top to bottom, so the craft shifts from typography to information design. Put the summary before the detail. Encode state in form as well as in numbers (a pill, a chip, a severity stripe) so that whatever needs attention is visible at a glance. Semantic color (good / warning / critical) is separate from the accent hue and doesn't count as your accent. Give sparklines and charts the same care as type: an area fill, a faint grid, an emphasized endpoint. Interactive elements should look interactive.
+
+## Process
+
+Start from what the viewer should be able to do on the page, in addition to what they will read. A local artifact has no runtime API: it cannot call Claude, read the user's connected data, or share state between viewers. A page that takes input keeps it only in the viewer's own browser storage, and that storage can be shared with other local pages or unavailable, so wrap every read and write in try/catch and make the page work without it.
+
+Before writing code, sketch a short design plan (a compact token system with color, type, and layout):
+- **Color**: describe the palette as 4-6 named hex values.
+- **Type**: typefaces for 2+ roles: a characterful display face used with restraint, a complementary body face, and a utility face for captions or data if needed.
+- **Layout**: a layout concept in one or two sentences.
+
+Then build, following the plan and deriving every color and type decision from it.
+
+**Write, look once, publish.** Before publishing you may look at the rendered page once, where this session can take a screenshot of the local file. Then make one pass of edits for what it shows, without a second look. For a page that charts real numbers, do take that look instead of skipping it, and use it on the chart. Don't build a test loop around your own file: no repeated screenshots, no pulling the script out to run it through node, no scripts that probe the DOM. Such a loop spends the session re-checking what a careful write already got right, while the user waits for the page. Then publish. Review happens on the published page in the user's browser, and further polish is for the user to request. If the user reports something visibly broken (a clipped column, unreadable text, a control that does nothing), fix that and republish once.
+
+**Updates.** Republishing the same file makes a new version at the same location and keeps the earlier ones. The browser tab does not reload by itself: tell the user to refresh it. If the page has state a viewer would miss on a refresh (a game, a long form), keep it in browser storage, guarded as above.
+
+## When the request is editorial
+
+The stance changes here: the client has already rejected proposals that felt templated, and is paying for a distinctive point of view. Make opinionated decisions, and take one real aesthetic risk where it serves the work.
+
+Review the design plan against the subject before building: if any part of it reads like the generic default you would produce for any similar page, revise that part, and note what you changed and why. Write the code only after confirming the plan is unique, following the revised plan exactly.
+
+**Principles** 
+
+- The hero states the thesis: open with the most characteristic thing in the subject's world (headline, image, live demo, interactive moment). 
+- Typography sets the personality of the page. Pair the display and body faces deliberately, avoiding the families you would use on any other project, and set a clear type scale with intentional weights, widths, and spacing. Make the type treatment itself a memorable part of the design instead of a neutral container for the content. 
+- Use motion deliberately. Think about whether and where animation can serve the subject: a page-load sequence, hover micro-interactions, ambient atmosphere. One orchestrated moment is usually more effective than scattered effects; choose what the direction calls for. However, sometimes less is more, and extra animation adds to the impression that the design is AI-generated. 
+- Match complexity to the vision. Maximalist directions need elaborate execution; minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.
+- Put your boldness in one place; keep everything around it quiet. If the accent clashes with the background, shift it toward an analogous hue or desaturate it instead of replacing it.

package/skills/code-review/SKILL.md

@@ -2,19 +2,19 @@
 name: code-review
 description: >
   Review the current diff, or a PR number/branch/path target, for correctness
-  bugs and reuse/simplification/efficiency cleanups. Pass --comment to post
-  findings as inline PR comments, or --fix to apply the findings to the working
-  tree after the review. Raise the reasoning effort (/effort) for broader,
-  recall-biased coverage; lower it for fewer, high-confidence findings.
+  bugs (plus reuse/simplification/efficiency cleanups where the model's review
+  recipe covers them) at the given effort level (low/medium: fewer,
+  high-confidence findings; high→max: broader coverage, may include uncertain
+  findings); with no level given, it follows the session's effort (/effort).
+  Pass --comment to post findings as inline PR comments, or --fix to apply the
+  findings to the working tree after the review.
+argument-hint: "[low|medium|high|xhigh|max] [--fix] [--comment] [<pr#>|<branch>|<path>]"
 ---
 
 `medium effort → 3+5 angles × 6 candidates → 1-vote verify → ≤8 findings`
 
-You are reviewing for **precision**: every finding you surface should be one a
-maintainer would act on. If the session is running at a higher reasoning effort,
-shift toward **recall** — catch every real bug a careful reviewer would catch in
-one sitting, err on the side of surfacing, and raise the finding cap and the
-number of finder angles accordingly.
+You are reviewing for **precision** at medium effort: every finding you surface
+should be one a maintainer would act on.
 
 ## Phase 0 — Gather the diff
 
@@ -29,9 +29,7 @@ review that target instead. Treat this diff as the review scope.
 
 Run **8 independent finder angles** via the Agent tool. Each
 surfaces **up to 6 candidate findings** with `file`, `line`, a one-line
-`summary`, and a concrete `failure_scenario`. If the Agent tool is not available
-in your current tool set, do not error — perform each angle (and each
-verification) yourself, sequentially, in this context.
+`summary`, and a concrete `failure_scenario`. If the Agent tool is not available in your current tool set, do not error — perform each angle (and each verification) yourself, sequentially, in this context.
 
 ### Angle A — line-by-line diff scan
 
@@ -81,10 +79,11 @@ alternative.
 
 ### Altitude
 
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix
-isn't deep enough — prefer generalizing the underlying mechanism over adding
-special cases.
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler, more
+general change to the underlying mechanism over adding special cases, and name
+that change.
 
 ### Conventions (CLAUDE.md)
 
@@ -127,8 +126,7 @@ Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
 
 ## Output
 
-Return findings as a JSON array of at most 8 objects (raise the cap when running
-at higher effort):
+Return findings as a JSON array of at most 8 objects:
 
 ```json
 [
@@ -141,8 +139,10 @@ at higher effort):
 ]
 ```
 
-Ranked most-severe first. If more than the cap survive, keep the most severe. If
-nothing survives verification, return `[]`.
+Ranked most-severe first. If more than 8 survive, keep the 8 most
+severe. If nothing survives verification, return `[]`. Do not call the
+ReportFindings tool even if it is available - this review's
+output contract is the JSON block above.
 
 ## Arguments and flags
 

package/skills/code-review/cells/arguments-and-flags.md

@@ -0,0 +1,19 @@
+## Arguments and flags
+
+Read the invocation arguments and adjust accordingly:
+
+- **A target** (`<pr#>`, `<branch>`, or `<path>`) replaces "the current diff" as
+  the review scope in Phase 0.
+- **`--comment`** — after producing the findings list, if the review target is a
+  GitHub PR, post each finding as an inline PR comment (one call per finding;
+  include a suggestion block only when it fully fixes the issue). Prefer a
+  GitHub inline-comment MCP tool if one is connected this session; otherwise use
+  `gh api repos/{owner}/{repo}/pulls/{pr}/comments`. If the target is not a PR,
+  print the findings to the terminal and note that `--comment` was ignored.
+- **`--fix`** — after producing the findings list, apply the findings to the
+  working tree instead of stopping at the report: fix each one directly —
+  correctness bugs and reuse/simplification/efficiency cleanups alike. Skip any
+  finding whose fix would change intended behavior, require changes well outside
+  the reviewed diff, or that you judge to be a false positive — note the skip
+  rather than arguing with it. Finish with a brief summary of what was fixed and
+  what was skipped.

package/skills/code-review/cells/high-3x5-recall-verify.md

@@ -0,0 +1,137 @@
+`high effort → 3+5 angles × 6 candidates → 1-vote verify (recall-biased) → ≤10 findings`
+
+You are reviewing for **recall** at high effort: catch every real bug a careful
+reviewer would catch in one sitting. At this level, catching real bugs matters
+more than avoiding false positives. Err on the side of surfacing.
+
+## Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Find candidates (3 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle, up to 6 each)
+
+Run **8 independent finder angles** via the Agent tool. Each
+surfaces **up to 6 candidate findings** with `file`, `line`, a one-line
+`summary`, and a concrete `failure_scenario`. If the Agent tool is not available in your current tool set, do not error — perform each angle (and each verification) yourself, sequentially, in this context.
+
+### Angle A — line-by-line diff scan
+
+Read every hunk in the diff, line by line. Then Read the enclosing function for
+each hunk — bugs in unchanged lines of a touched function are in scope (the PR
+re-exposes or fails to fix them). For every line ask: what input, state, timing,
+or platform makes this line wrong? Look for inverted/wrong conditions,
+off-by-one, null/undefined deref, missing `await`, falsy-zero checks,
+wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
+
+### Angle B — removed-behavior auditor
+
+For every line the diff DELETES or replaces, name the invariant or behavior it
+enforced, then search the new code for where that invariant is re-established.
+If you can't find it, that's a candidate: a removed guard, a dropped error
+path, a narrowed validation, a deleted test that was covering a real case.
+
+### Angle C — cross-file tracer
+
+For each function the diff changes, find its callers (Grep for the symbol) and
+check whether the change breaks any call site: a new precondition, a changed
+return shape, a new exception, a timing/ordering dependency. Also check callees:
+does a parallel change in the same PR make a call unsafe?
+
+### Reuse
+
+The angles above hunt for bugs; this one and the next two hunt for cleanup in
+the changed code. Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+### Altitude
+
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler, more
+general change to the underlying mechanism over adding special cases, and name
+that change.
+
+### Conventions (CLAUDE.md)
+
+Find the CLAUDE.md files that govern the changed code: the user-level
+~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
+CLAUDE.local.md in a directory that is an ancestor of a changed file (a
+directory's CLAUDE.md only applies to files at or below it). Read each one
+that exists, then check the diff for clear violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line
+that breaks it — no style preferences, no vague "spirit of the doc"
+inferences. In the finding, name the CLAUDE.md path and quote the rule so the
+report can cite it. If no CLAUDE.md applies, return nothing for this angle.
+
+Cleanup, altitude, and conventions candidates use the same
+`file`/`line`/`summary` shape; in `failure_scenario`, state the concrete
+cost (what is duplicated, wasted, harder to maintain, or which CLAUDE.md rule
+is broken) instead of a crash. Correctness bugs always outrank cleanup,
+altitude, and conventions findings when the output cap forces a cut.
+
+Pass every candidate with a nameable failure scenario through — finders that
+silently drop half-believed candidates bypass the verify step and are the
+dominant cause of misses.
+
+## Phase 2 — Verify (1-vote, recall-biased)
+
+Dedup near-duplicates (same defect, same location, same reason → keep one). For
+each remaining candidate, run **one verifier** via the Agent tool:
+give it the diff, the relevant file(s), and the candidate; it returns exactly
+one of **CONFIRMED / PLAUSIBLE / REFUTED**.
+
+**PLAUSIBLE by default** — do not refute a candidate for being "speculative" or
+"depends on runtime state" when the state is realistic: concurrency races,
+nil/undefined on a rare-but-reachable path (error handler, cold cache, missing
+optional field), falsy-zero treated as missing, off-by-one on a boundary the
+code does not exclude, retry storms / partial failures, regex/allowlist that
+lost an anchor. These are PLAUSIBLE.
+
+**REFUTED** only when constructible from the code: factually wrong (quote the
+actual line); provably impossible (type/constant/invariant — show it); already
+handled in this diff (cite the guard); or pure style with no observable effect.
+
+Keep **CONFIRMED and PLAUSIBLE**. Drop REFUTED.
+
+## Output
+
+Return findings as a JSON array of at most 10 objects:
+
+```json
+[
+  {
+    "file": "path/to/file.ext",
+    "line": 123,
+    "summary": "one-sentence statement of the bug",
+    "failure_scenario": "concrete inputs/state → wrong output/crash"
+  }
+]
+```
+
+Ranked most-severe first. If more than 10 survive, keep the 10 most
+severe. If nothing survives verification, return `[]`. Do not call the
+ReportFindings tool even if it is available - this review's
+output contract is the JSON block above.

package/skills/code-review/cells/high-8-inline.md

@@ -0,0 +1,122 @@
+`high effort → 8 inline angles → dedup (no verify) → ≤10 findings`
+
+You are reviewing for **recall** at high effort: catch every real bug a careful
+reviewer would catch in one sitting. At this level, catching real bugs matters
+more than avoiding false positives. Err on the side of surfacing.
+
+## Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Find candidates (3 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle, up to 6 each)
+
+Run **8 independent finder angles** in sequence yourself, in THIS context — do NOT spawn subagents for them. Each
+surfaces **up to 6 candidate findings** with `file`, `line`, a one-line
+`summary`, and a concrete `failure_scenario`.
+
+### Angle A — line-by-line diff scan
+
+Read every hunk in the diff, line by line. Then Read the enclosing function for
+each hunk — bugs in unchanged lines of a touched function are in scope (the PR
+re-exposes or fails to fix them). For every line ask: what input, state, timing,
+or platform makes this line wrong? Look for inverted/wrong conditions,
+off-by-one, null/undefined deref, missing `await`, falsy-zero checks,
+wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
+
+### Angle B — removed-behavior auditor
+
+For every line the diff DELETES or replaces, name the invariant or behavior it
+enforced, then search the new code for where that invariant is re-established.
+If you can't find it, that's a candidate: a removed guard, a dropped error
+path, a narrowed validation, a deleted test that was covering a real case.
+
+### Angle C — cross-file tracer
+
+For each function the diff changes, find its callers (Grep for the symbol) and
+check whether the change breaks any call site: a new precondition, a changed
+return shape, a new exception, a timing/ordering dependency. Also check callees:
+does a parallel change in the same PR make a call unsafe?
+
+### Reuse
+
+The angles above hunt for bugs; this one and the next two hunt for cleanup in
+the changed code. Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+### Altitude
+
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler, more
+general change to the underlying mechanism over adding special cases, and name
+that change.
+
+### Conventions (CLAUDE.md)
+
+Find the CLAUDE.md files that govern the changed code: the user-level
+~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
+CLAUDE.local.md in a directory that is an ancestor of a changed file (a
+directory's CLAUDE.md only applies to files at or below it). Read each one
+that exists, then check the diff for clear violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line
+that breaks it — no style preferences, no vague "spirit of the doc"
+inferences. In the finding, name the CLAUDE.md path and quote the rule so the
+report can cite it. If no CLAUDE.md applies, return nothing for this angle.
+
+Cleanup, altitude, and conventions candidates use the same
+`file`/`line`/`summary` shape; in `failure_scenario`, state the concrete
+cost (what is duplicated, wasted, harder to maintain, or which CLAUDE.md rule
+is broken) instead of a crash. Correctness bugs always outrank cleanup,
+altitude, and conventions findings when the output cap forces a cut.
+
+Pass every candidate with a nameable failure scenario through — finders that
+silently drop half-believed candidates are the dominant cause of misses.
+
+## Phase 2 — Dedup only (no verify)
+
+Pool all candidates. Dedup near-duplicates only (same defect, same location, same reason → keep one). Do NOT run verifiers; do NOT re-judge. Sort by severity.
+
+## Output
+
+Target **at least 5 findings**. If fewer genuine findings exist, emit what you have — do not invent to hit the floor.
+
+Return findings as a JSON array of at most 10 objects:
+
+```json
+[
+  {
+    "file": "path/to/file.ext",
+    "line": 123,
+    "summary": "one-sentence statement of the bug",
+    "failure_scenario": "concrete inputs/state → wrong output/crash"
+  }
+]
+```
+
+Ranked most-severe first. If more than 10 survive, keep the 10 most
+severe. If nothing survives, return `[]`. Do not call the
+ReportFindings tool even if it is available - this review's
+output contract is the JSON block above.

package/skills/code-review/cells/low-1-pass-max4.md

@@ -0,0 +1,27 @@
+`low effort → 1 diff pass → no verify → ≤4 findings`
+
+## Turn 1 — read
+
+One tool call: read the unified diff (`git diff @{upstream}...HEAD; git diff HEAD`
+to cover both committed and uncommitted changes, or `git diff main...HEAD` /
+the target passed as an argument). Skip test/fixture
+hunks (`test/`, `spec/`, `__tests__/`, `*_test.*`, `*.test.*`,
+`fixtures/`, `testdata/`) — test-file changes are not reviewed at this level.
+No subagents, no full-file reads.
+
+## Turn 2 — findings
+
+Flag runtime-correctness bugs visible from the hunk alone: inverted/wrong
+condition, off-by-one, null/undefined deref where adjacent lines show the value
+can be absent, removed guard, falsy-zero check, missing `await`,
+wrong-variable copy-paste, error swallowed in a catch that should propagate.
+Also flag — still from the hunk alone — new code that duplicates an existing
+helper visible in the diff context, and dead code the diff leaves behind.
+
+Do **not** flag style, naming, perf, missing tests, or anything outside the
+hunk.
+
+Output at most **4 findings**, most-severe first, one line each:
+`path/to/file.ext:123 — what's wrong and the concrete failure`. If nothing
+qualifies, output exactly `(none)`. Do not call the
+ReportFindings tool even if it is available.

package/skills/code-review/cells/low-1-pass-min-files-4.md

@@ -0,0 +1,28 @@
+`low effort → 1 diff pass → no verify → ≥min(files,4) findings`
+
+## Turn 1 — read
+
+One tool call: read the unified diff (`git diff @{upstream}...HEAD; git diff HEAD`
+to cover both committed and uncommitted changes, or `git diff main...HEAD` /
+the target passed as an argument). Skip test/fixture
+hunks (`test/`, `spec/`, `__tests__/`, `*_test.*`, `*.test.*`,
+`fixtures/`, `testdata/`) — test-file changes are not reviewed at this level.
+No subagents, no full-file reads.
+
+## Turn 2 — findings
+
+Flag runtime-correctness bugs visible from the hunk alone: inverted/wrong
+condition, off-by-one, null/undefined deref where adjacent lines show the value
+can be absent, removed guard, falsy-zero check, missing `await`,
+wrong-variable copy-paste, error swallowed in a catch that should propagate.
+Also flag — still from the hunk alone — new code that duplicates an existing
+helper visible in the diff context, and dead code the diff leaves behind.
+
+Do **not** flag style, naming, perf, missing tests, or anything outside the
+hunk.
+
+Target **min(files_changed, 4) findings**, most-severe first, one
+line each: `path/to/file.ext:123 — what's wrong and the concrete failure`.
+If you have fewer, do one more pass focused on the largest changed file
+and on any **removed** code blocks. Output `(none)` only if the diff is
+trivially correct after that pass.