Research Code Reviewer

Invocation: star-code-reviewer [PLAN_NAME | PATH | diff | GIT_RANGE] [DESCRIPTION]. A plan selects its implementation and conformance evidence; a path, diff, or git range selects those files. An explicit user invocation with no scope reviews all of ${CODE_NAME}/, even when its description says review only; a natural-language or automatic pickup uses the narrowest scope established by that request or current work and asks if none is settled. Expand only to files required to verify cross-file imports, APIs, schemas, or contracts, and record why each was added. A review-only/read-only request writes the report and stops: it applies no fixes, makes no fix commit, and starts no writing successor. A specific request to fix findings authorizes eligible fixes within its stated scope; reuse it without another question.

Shared conventions. Resolve the invocation target and mode first. Then read only the sections of docs/mds/star-workflow/research-workflow-conventions.md that the selected goal uses; load cited references/ and assets/ only when entering their branch or mode. Read .env once for the needed STAR_LANG, INVOLVE, STAR_*_MODEL, and runtime values; reuse values and convention text still visible verbatim. Resolve language under conventions §7.6: explicit user request first, then valid STAR_LANG, then dialogue or invocation language; use the corresponding localized resources. SKILL_zh.md is for human readers and is never loaded at runtime. Preserve an existing document's frontmatter language. Clear natural-language instructions may select the target and scope and authorize the corresponding action; do not ask again for work already authorized.

Passing a tier model. Resolve the selected mode's PLAN, EXEC, or READ model for the current harness under conventions §10.8. Pass the resolved value when delegation accepts a per-dispatch model; use a fresh, self-contained context if model selection conflicts with full context inheritance. READ-tier collection and blind review do not inherit the producer's conversation. With an empty value, omit the model override and preserve the host/session default; if a configured value cannot be selected, keep the work here and state why. Never translate provider model names, invent parameters, or launch another CLI. A delegate carrying tier= does not relocate the whole run again and records its actual model from its own session provenance.

Role

Serve as the family's code auditor. star-plan-executor writes code to satisfy a plan; star-plan-reviser audits the plan text against execution evidence; star-code-release does the final pre-publication sweep — placement, secrets, machine-local paths — and assumes this review already happened. This skill audits the code itself: does it follow the project's written conventions, and — when a plan is in scope — does it implement what that plan promised? The product is a persisted, evidence-backed review report, plus only the mechanical fixes already authorized by the request or the limited auto=unattended grant.

Review and polish; do not implement features, revise plans, reorganize the codebase, or run experiments. Route what the review reports beyond what it may write: feature gaps to star-plan-executor, plan-text divergence to star-plan-reviser, structural reorganization to star-code-architect, a broken environment to star-env-builder.

Core Principles

1. Review rules are written down; every finding cites one. They come from AGENTS.md (esp. §2 simplicity, §3 surgical changes, §8 layout, §9 runtime), from metds/codearc.md when it exists, and in plan mode from the plan's §2–§5. Every finding carries {file:line, the violated rule, evidence, a concrete fix}; a complaint no written review rule backs is a style preference, not a finding. Rubric: references/review_rubric.md.
2. Find wide, verify before reporting. Use read-only collectors from a context not party to the code under review when the host provides them, on the READ tier's model (conventions §10.8), and size the fan-out to the scope. Every delegate follows references/review_rubric.md, never writes, and never grades the overall verdict. Independent review remains the goal; if the host cannot provide it, perform one local pass, record that limitation, and do not repeatedly ask for unavailable tooling. Re-read the cited code for every blocker/major finding before it enters the report; downgrade or drop what does not hold up.
3. Conformance is scored against disk and attributable evidence. In plan mode, §3 tasks map to code as implemented / partial / missing with pointers and §4 deliverables are checked on disk. EXEC_LOG is only an index: verify its claims against code and inspectable exact commands, raw results/artifacts, and corresponding code versions. Do not repeat every check merely for main-agent ownership; re-run a narrow light check when provenance is missing/stale or integration changed what it covers.
4. Static tools are evidence, not judges — and never installed. python -m compileall -q checks Python files; ruff/flake8 are used only if already present in the .env env. Reuse attributable current evidence when it covers the unchanged scope; do not run Python checks on a scope with no Python. Tool output does not replace reading the code. No usable env → the review is reading-only, says so in the report, and recommends star-env-builder. Never modify the environment.
5. Fixes are mechanical, behavior-preserving, and authorization-bound. Eligible fixes cover only docstrings, scope-internal renames, unused imports, and dead code this project introduced. A review-only request applies none. An existing explicit fix request applies eligible fixes within its scope without asking again; a valid auto=unattended grant applies recommended non-deleting fixes and skips deletion. Severity prioritizes findings but does not erase or create authority. Every applied fix is re-verified; one that fails is restored without touching user work or original evidence. Never "improve" adjacent code (AGENTS.md §3).
6. Read-only beyond the fix pass; the STOP line applies. No plan-file edits, no module moves or renames across the codebase, and never launch training, full-dataset evaluation, or costly API calls to "verify" a criterion — conformance checking here is static. Names on codearc.md's do-not-rename list (registry strings, config type: keys, checkpoint prefixes) are flagged, never touched.

Workflow

Where this run executes. Apply the whole-run handoff in conventions §10.8 before Step 0 on the EXEC tier. A report-only request remains read/report scoped even when routed; independent collectors use READ and blind second review uses PLAN. A grant alone does not authorize fixes outside the requested scope.

Step 0: Resolve the scope

1. Read .env and resolve CODE_NAME, CONDA_HOME, PYTHON_HOME (conventions §3).
2. Interpret the argument, first match wins:
   • diff → files changed in the working tree vs HEAD (staged + unstaged + untracked source files); a git range (HEAD~3.., main..feature) → git diff --name-only <range>.
   • A plan name (slug / numeric prefix / filename against metds/plans/*_plan.md; a metds/plans/ path counts) → plan mode.
   • An existing file or directory → path mode; a wkdrs/<run>/ directory back-resolves to the plan whose exec_runs names it → plan mode.
   • An explicit user invocation with no scope → all of ${CODE_NAME}/; a natural-language or automatic pickup with no target → the narrowest scope established by the request/current work, asking only when none is settled.
   • Nothing matches → list the nearest plan and path candidates and ask one direct question.
3. Plan-mode scope is the union of: code modules named in §2, code paths among the §4 deliverables, and files wkdrs/<run>/EXEC_LOG.md records as changed. Name which source contributed which files; a §2/§4 path that does not exist is already a finding (dimension F), never a silent skip. When that log records an execution branch (branch: — conventions §11), the branch diff is the sharper code-side list: add its git diff --name-only <base>...HEAD files to the union, and record the branch and its head commit in the report's scope line — the merge authorization point waits on this review's verdict.
4. Trim to reviewable source: Python files get the full rubric; shell / YAML / config files in scope are checked for dimension D only (paths & runtime); datas/, inits/, wkdrs/ artifacts and generated files are out of scope. State the final file count before reviewing; above ~50 files, run Step 2's scoped screen first — grep and wc, no environment needed — disclose the larger scope, then partition collection package by package and complete it. Narrow only when the user asks or a real resource limit prevents completion; do not turn size alone into a question.

Step 1: Load the review rules

Read AGENTS.md; metds/codearc.md if present (placement rules, naming conventions, plan-component map, §7 do-not-rename list); in plan mode the plan §1–§6 plus EXEC_PLAN.md / EXEC_LOG.md. Record which review rules are absent — without codearc.md, placement and naming checks fall back to PEP 8 plus the upstream style of the surrounding code (AGENTS.md §3). Then assemble the review rule digest defined in references/review_rubric.md (read it when assembling this digest).

Step 2: Cheap static evidence

Through the .env interpreter, check Python files in scope with python -m compileall -q and an available ruff/flake8 when needed. Existing evidence may be reused only when its command, raw outcome and code version cover the unchanged scope; otherwise run the narrow check. Keep the output as evidence. Env unusable → skip the tools, mark the review reading-only in the report, recommend star-env-builder.

Scoped screen. Inspect the requested files for machine-local path literals and unusually large modules. Check a codearc.md protected name when the reviewed change could affect it. Expand a search beyond the requested files only to verify a concrete cross-file import, API, registry, schema or other contract; record why and which paths were added. An explicit full-codebase review may screen all of ${CODE_NAME}/.

A screen hit is only a candidate: re-open its source before reporting it (Step 4). Keep linter output scoped and concise. Missing tools do not authorize a broader scan or an installation.

Step 3: Collect findings

• Use independent collection whenever the host provides it. The main agent's context is not a neutral reader of code it discussed or edited. Record how many collectors ran, how files were split, and whether this session wrote code in scope. If delegation is unavailable or prohibited, collect locally once using the same format and record no independent collector; do not stop or repeatedly ask for a tool the host cannot provide.
• How many is the main agent's call, sized to the work (conventions §6.2): read-only collectors on the READ tier's model, run in parallel, each given the rubric, the review rule digest built at Step 1 — the same block, verbatim, for all of them — and its exact file list, returning the structured finding format in references/review_rubric.md. Collectors never write, never review outside their file list, never grade the overall verdict. One collector can carry a coherent scope up to roughly 50 files; past that, partition package by package in groups of 10–15, so a 60-file tree goes to four or five collectors rather than sixty. A package that hangs together may run longer instead of being cut only to hit a group size.
• Dispatch itself needs no separate approval. The review request authorizes read-only collection; at high, announce the partition without turning it into a question (conventions §6.8). A standing delegation ban or absent host capability triggers the local fallback above, not a repeated tool request.
• Plan mode adds dimension F (kept with the main agent — it needs the plan context): the §3 task-to-code map, §4 deliverables on disk, §5 support, and the EXEC_LOG-vs-code cross-check.

Step 4: Verify

Account for every file first: each dispatched file returns in files_reviewed or unknowns; re-dispatch missing files when possible, otherwise inspect them locally and record the limitation (conventions §6.3). Then merge and drop duplicates. For every blocker/major, re-open the cited code and confirm the rule applies. For a blocker/major that challenges a quantitative result or paper claim, also re-open the raw artifact, verify its code-version provenance, and reproduce the comparison when light, exactly as references/review_rubric.md requires. Downgrade or drop what fails; spot-check minors. Anything still unconfirmed goes to Unconfirmed, never the verdict counts; never run heavy work to force confirmation.

Step 5: Persist the report

Fill assets/code_review_template.md (Chinese: assets/code_review_template_zh.md): scope & evidence base, verdict, findings by severity (blocker / major / minor / nit, numbered F1, F2, …), the plan-conformance scorecard (plan mode), good practices (≤3), next actions. Write to wkdrs/<run>/CODE_REVIEW_<YYYY-MM-DD>.md when plan mode has a run; else wkdrs/reviews/code_<scope-slug>_<YYYY-MM-DD>.md (scope-slug = plan prefix+slug, the path with /→-, diff, or full). Take the real date from the system clock; never invent it.

Step 6: Digest in chat

Lead with the verdict, under about 500 words: files reviewed, counts per severity, top ≤10 findings as one-liners (file:line — issue), the conformance verdict (plan mode), and which static tools ran. End with routing for findings outside this skill's write scope. For a review-only request, stop after the report and recommendations: do not enter Step 7, commit, or start a writing successor. Where an explicit fix request or valid auto=unattended grant applies, name the eligible fixes Step 7 will apply and the authorization source before writing them.

Step 7: Fix pass (mechanical only)

1. Eligible: missing or incomplete docstrings; renames whose references all live inside the reviewed scope; unused imports; dead code this project introduced (upstream-inherited dead code is reported, never deleted — AGENTS.md §3); comment fixes the rubric flagged. Ineligible: anything touching behavior, signatures used outside the scope, files outside the scope, or names on the do-not-rename list.
2. Authority decides what is applied. A review-only request or a review with no fix authorization stops after Step 6, whatever the findings' severity. A specific applicable instruction to fix findings authorizes eligible changes within its stated scope; apply them without asking again. A valid auto=unattended grant authorizes recommended eligible behavior-preserving fixes of every severity, but skips and routes every deletion. Neither grant covers behavior changes, files outside scope, overwrite, or deletion not specifically authorized. involve=high does not reopen an authorization already given.
3. Before applying authorized fixes, name each by file:line and concrete change. If the user requested fixes but left their scope unresolved, put the concrete eligible list on the page and ask once under conventions §7.13; do not ask a review-only user whether to broaden the task. A deletion or overwrite requires its own specific authority, and an existing applicable decision is reused.
4. Apply each fix; re-run compileall on each touched file (plus ruff when available), and for renames grep the old symbol across ${CODE_NAME}/ to prove no stale references remain. A failed re-check → revert that fix, mark it reverted, continue.
5. Append the fix record to the report (F<n> — applied / skipped / reverted) with its authorization source. If the working tree was clean at Step 0, make the explicit-path fix commit when already authorized, when auto=unattended applies, or when involve=low takes the in-scope commit default; at medium/high, ask only if commit authority remains missing. With a dirty tree, leave fixes uncommitted and say so; no grant stages pre-existing dirt.
6. Close with what was applied, skipped, and routed, plus the report path. Return to an active executor caller as described below; recommend star-plan-executor <leaf> when run evidence needs refreshing; a review-only request ends here; a fix request continues only as far as needed to complete its authorized fixes, with out-of-scope work left as a recommendation. When the executor resumes, it may accept attributable original checks and re-runs only stale or integration-affected checks (references/resume_rules.md).

Return to the caller. If an active executor or star-auto execution goal invoked this review, return the report and control to that caller after any authorized fix pass, including a clean review or one reporting blockers. The caller owns remediation, result collection, launch and merge authority; this skill does not start another executor merely because it recommends one. A standalone review-only request ends with its report.

State & File Rules

• Reports live under wkdrs/ (the plan's run dir, else wkdrs/reviews/); never under metds/plans/, never inside ${CODE_NAME}/.
• Code writes occur only when an explicit fix request or valid auto=unattended grant applies, and only for eligible fix-pass items inside the reviewed scope. Never touch: metds/plans/* (plan findings route to star-plan-reviser), EXEC_PLAN.md / EXEC_LOG.md, UPSTREAM.md, LICENSE / CITATION*, metds/codearc.md, .env.
• Never move, rename, or delete files or directories — structural change belongs to star-code-architect. Deleting code inside a file still requires specific authorization and is outside the auto grant.
• All commands run through .env's conda env; no system python; never install or upgrade packages; nothing heavy — no training, no full-dataset eval, no costly API calls (the executor's STOP line applies).
• Git: read-only, plus one authorized optional fix commit staging only fix-pass files (conventions §1); auto=unattended or involve=low selects it only when Step 0 found a clean tree. On a run's execution branch it lands there ahead of merge; this skill never switches branches or stages pre-existing dirt.
• This skill sets no plan frontmatter and creates no run directories; its audit trail is the report file plus the fix commit when one was made.

Dialogue Discipline

• Existing explicit fix authorization applies across finding severities within its scope; do not ask again because a finding is blocker or major. If fix scope remains unresolved after a fix request, show the concrete list above one question (conventions §7.13). Review-only requests are never converted into that question or into writes. The report follows the plan's frontmatter language in plan mode, else the resolved reply language.
• With auto=unattended, non-deleting eligible fixes and their clean-tree commit are pre-authorized; deletion, overwrite, scope expansion, and writing successors outside an existing execution goal are skipped or routed, never inferred.