codebase-review
Before an upcoming feature, when merged work crosses the recorded review threshold, or when implementation exposes structural friction, review the codebase state with independent skepticism. Deliver the report while keeping unresolved adoption decisions tracked.
timharris707 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add timharris707/skills --skill codebase-reviewAbout this skill
name: codebase-review description: "Before an upcoming feature, when merged work crosses the recorded review threshold, or when implementation exposes structural friction, review the codebase state with independent skepticism. Deliver the report while keeping unresolved adoption decisions tracked."
Codebase review
Read the Codex desktop binding when this workflow needs harness mechanics, model routing, or recovery.
A review of what the codebase is, where adversarial-review reviews what a diff changes. It hunts deepening opportunities: places where structure taxes every change that passes through. The review completes with an evidence-backed report; adoption decisions can remain pending on the tracker.
This skill is the portable protocol: an entry gate, a read-only review lane of finders each named for the lens it looks through, a skeptic pass that kills candidates before the report exists, and the disposition loop. Everything repo-specific lives in binding slots the team-workflow setup interview fills: where reports land, the trigger threshold, where rejections are remembered, how the lane is run.
Read the team-workflow binding doc first. Full domain-modeling discipline (glossaries, decision records) lives in domain-memory, deliberately not here.
1. Triggers: an entry gate, never a calendar
The review runs when one of three gates opens, never on a schedule: a scheduled run reviews whatever the calendar happens to land on, and produces findings to match.
- Pre-feature. A spec is about to land in an area; review that area first, in the spirit of "make the change easy, then make the easy change."
- Lane-count threshold. N lanes have merged since the last review (N is a per-repo binding slot). Merged work is the pressure that degrades structure; the count measures the pressure.
- Reported friction. A lane or the orchestrator reports the code fought them: a change that should have been local sprawled, a test that could only be written past an interface. A structural cause surfaced by diagnose, the bug as symptom of a missing seam or a duplicated rule, arrives through this gate: the lane fixed the instance, and the structure is reported here.
Scope follows the trigger. Pre-feature reviews the spec's blast radius. Lane-count and friction reviews cover the areas churned since the last review, weighted by git history: recently-changed code is where deepening pays, because it is where the next change lands. Gates are not exclusive: a spec can land just as the lane count crosses N; when more than one is open, the report names them all and the scope is the union of what the open gates set. A full sweep runs only once: a repo's first-ever review, whatever gates opened it; every later run is scoped by its triggers.
2. Execution: a read-only lane
The review uses independent read-only reviewers. For a bounded review, coordinate them within the current task and return the report here. For existing tracked work, follow its claim and executor binding. Reviewers change no code and file no tickets; any later filing follows the user's authorization and disposition loop (§5).
Before any finder runs, the lane reads the repo's rejection memory (binding slot). Where the slot points at the domain-memory home, that means reading the decision records, since a rejection carries its nature in the record's own text, not in a separate ledger. A candidate the decider rejected reopens on new evidence, never on repetition. A rerun that re-proposes a recorded rejection without new evidence has ignored the decider once and the memory twice.
Finder agents run as parallel subagents that never see each other's output: isolation is what makes two lenses landing on the same code a signal instead of an echo. Each holds one named lens from the menu, stated in the report. Schedule separate reviewer contexts within the available agent slots, in batches if needed. All five lenses run by default; a scoped run may drop a lens its scope cannot reach, naming the drop and the reason in the report:
- shallow modules / seams: interfaces nearly as complex as the implementations behind them; seams placed where nothing varies, or missing where something does.
- duplicated concepts: one concept implemented in several places, so one change must be made N times and is made N−1.
- dead code: code the deletion test clears for removal: delete it and no complexity reappears anywhere.
- boundaries-vs-reality: the declared module layout versus how change actually flows: imports that cross seams, layers honored in the diagram and bypassed in the code.
- test-pain: code that can only be tested past its interface, and the setup-heavy tests that prove it.
The lane shapes candidates before any skeptic sees them, one claim per candidate, stated explicitly. Convergent findings, lenses making the same claim about the same code, merge into one candidate, with the convergence recorded as evidence; findings that share code but make different claims stay separate, the shared location recorded as evidence on each; bundled claims split into one candidate each. One skeptic per candidate.
Finders and the skeptic speak the shared design vocabulary defined in references/design-vocabulary.md: depth, seams, locality, the deletion test. Every claim in the report is phrased in those terms, in the codebase's own domain names.
3. The skeptic
A finder's candidate is a hypothesis. Every candidate goes to a built-in skeptic whose brief is to kill it before the report exists: a separate agent in its own context, handed the candidate and its evidence and nothing of the finder's reasoning, so the kill attempt starts from the code rather than from the argument: re-read the code, reproduce the claimed behavior read-onl
Read the complete source ↗