augchan42/inkstone / skills/codex-review
codex-review
VerifiedRun an independent code review of any git scope — uncommitted changes, a commit range, a merge commit, a PR, or specific paths — via Codex CLI, opencode, or context-blind subagents, then triage every finding with an explicit disposition. Use when asked to "review this diff", "codex review", "review PR N", "review the merge commit", or to get a second opinion on changes before or after merge. For reviewing implementation plans rather than code, see plan-review-loop.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.8 KB |
| loop-mode.md | markdown | 7.2 KB |
| review-lanes.md | markdown | 6.1 KB |
| reviewer-backends.md | markdown | 16.9 KB |
| scripts/resolve-scope.shexecutable | script | 7.3 KB |
| scripts/rounds.pyexecutable | script | 28.9 KB |
| scripts/test_rounds.py | script | 20.2 KB |
review-lanes.md
View on GitHub# Review Lanes
A lane is one reviewer with one job. Lanes run in parallel and their findings are
deduplicated afterward. Fewer, sharper lanes beat many broad ones — a reviewer told
to check everything reports mostly noise.
Lane selection per run:
1. **Core lanes** — always on (below).
2. **Detected lanes** — added when the stack is detected in the target repo.
3. **Project lanes** — read verbatim from `.claude/code-review-lanes.md` in the target repo.
4. **Focus lane** — built from the `--focus "..."` argument.
5. **Holistic lane** — only with `--holistic`.
---
## Core lanes (always on)
### Lane: Correctness
The changed code, judged against what it is trying to do. Not style.
- Off-by-one and boundary errors — especially where the diff introduces or consumes an
index whose base or direction is a convention rather than a type (1-indexed vs
0-indexed, bottom-to-top vs top-to-bottom, inclusive vs exclusive ends). A wrong
convention here produces plausible-looking output, which is why it survives review.
- Null/undefined/empty paths through new branches.
- State that is read after it is mutated, or mutated during render.
- Effects: missing cleanup, wrong dependency arrays, effects doing work that belongs
in an event handler.
- Async: unawaited promises, races between concurrent writers, error paths that
swallow rejections.
- Error handling that catches too broadly or reports too little.
### Lane: Contracts & call sites
New or changed interfaces, and everyone who uses them.
- Every caller of a changed signature updated? Search for them; do not assume.
- Props/parameters whose meaning is carried by a name rather than a type — document
the convention at the definition, and verify each call site honors it.
- Removed exports, keys, or config values: is every consumer gone too?
- Data that crosses a boundary (server→client, API→UI, prompt→parser): does the
producer's shape still match the consumer's expectation?
### Lane: Tests
- Does each new behavior have a test that would fail without the change?
- For a bug fix: is there a regression test that reproduces the original bug?
- Edge cases: empty, null, boundary, error path.
- Do the tests assert behavior, or do they assert implementation details that will
break on the next refactor?
- Are new tests deterministic and isolated (no shared mutable state, no real clock,
no network)?
### Lane: Security
Scoped to the diff, not the whole codebase.
- Input validation and sanitization on anything user-supplied.
- Authorization checks on new routes, actions, and mutations — treat a server action
as a public endpoint.
- Injection surfaces: SQL, shell, path traversal, XSS via unescaped interpolation.
- Secrets: hardcoded credentials, tokens in logs, keys committed to the tree.
- Error messages that leak internals to users.
### Lane: Simplification
Findings here are advisory by default — flag, do not demand.
- Copy-pasted blocks that should be one function.
- Abstractions introduced for a single caller.
- Dead code and unreachable branches left by the change.
- Complexity that a smaller data structure would remove.
---
## Detected lanes
Add a lane when the marker is present in the target repo.
| Lane | Detection |
|---|---|
| Next.js / React | `next.config.*` or `"next"` in `package.json` |
| Browser UI / a11y | `app/`, `pages/`, `src/app/`, `src/pages/`, `public/`, or `index.html` |
| iOS / SwiftUI | `*.xcodeproj`, `Package.swift`, or `*.swift` in the diff |
| Database / migrations | migration directories, `*.sql` in the diff |
### Lane: Next.js & React
- Server Components by default; `'use client'` only where interactivity requires it.
- Data fetched in Server Components, not effects.
- `params`/`searchParams` awaited as Promises.
- Cache strategy explicit and correct; `revalidateTag`/`revalidatePath` after mutations.
- Server Actions validated and auth-checked.
- Derived state computed during render, not synced via effects.
- No barrel-file imports; heavy client-only components behind `next/dynamic`.
### Lane: Browser UI & accessibility
- Keyboard operability of anything newly interactive; visible focus indicators.
- Correct roles and ARIA for composite widgets (combobox, listbox, dialog, tabs) —
and `aria-activedescendant`/`aria-expanded` kept in sync with actual state.
- Color contrast on new or changed tokens.
- Touch target size; layout at small widths.
- Loading, empty, and error states for anything that can be slow or fail.
### Lane: Design tokens & theming
Add this lane whenever the diff touches a color, spacing, or typography token — this
is the classic "looked fine in the theme I was using" defect.
- Every changed token verified in **every** theme the project ships, not just the default.
- Semantic tokens used rather than raw values.
- Contrast re-checked per theme, not once.
---
## Project lanes
If `.claude/code-review-lanes.md` exists in the target repo, include its contents
verbatim as additional lanes. That file is where a project records the invariants
that have actually bitten it — the ADR its code must not violate, the token that
broke twice, the mobile constraint that regresses. It is maintained by the project,
not by this skill.
Suggested shape:
```markdown
# Code review lanes — <project>
## Standing invariants
- <rule that has been violated before, and what to check>
- <ADR number and the constraint it imposes>
## Known traps
- <the thing that looks correct but is not>
```
## Focus lane
Built from `--focus "..."`. Diff-specific emphasis that is not worth recording
permanently — "the new `changingLines` prop is 1-indexed bottom-to-top", "I removed
nine i18n keys, check nothing still references them". Passed to the reviewer as its
own lane so it is not diluted by the generic criteria.
## Holistic lane (`--holistic` only)
Whole-project structure: module boundaries, god files, dependency cycles, config
sprawl, agent-harness docs (`AGENTS.md`/`CLAUDE.md` coverage), observability.
Off by default on purpose. It reports on code the diff never touched, which
produces long reviews whose findings are all out of scope for the change under
review. Run it deliberately, on its own, not bundled with a diff review.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |