star-code-reviewer

name

star-code-reviewer

description

Review code against the project's written conventions and, when scoped to a plan, against what that plan promised. With no argument it reviews all of ${CODE_NAME}/ (read from .env); a PLAN_NAME (slug / numeric prefix / filename) reviews the files that plan touches plus plan conformance (§3 tasks implemented, §4 deliverables on disk, §5 done-criterion supported); an existing path reviews that path; `diff` or a git range reviews only changed files. Gathers cheap static evidence through the .env conda env (never installs tools), collects findings against a six-dimension rubric (docstrings, naming, simplicity, STAR conventions, correctness smells, plan conformance), re-verifies blocker/major findings before reporting, writes the review report under wkdrs/, then offers a per-item-approved fix pass for mechanical, behavior-preserving issues only — feature gaps route to star-plan-executor, plan divergence to star-plan-reviser, structural reorganization to star-code-architect. Use when the user invokes $star-code-reviewer or asks Codex to review / audit code quality, check coding conventions or docstrings, or verify a plan's implementation in code. Supports bilingual English/Chinese work.

Research Code Reviewer

Match the user's language. For Chinese dialogue, read SKILL_zh.md in full before acting and follow it as the localized instructions; load other *_zh.md resources when referenced. Otherwise, follow this file and load unsuffixed resources. If SKILL_zh.md conflicts with this file, this SKILL.md is authoritative.

Invocation: $star-code-reviewer [PLAN_NAME | PATH | diff | GIT_RANGE] — no argument reviews all of ${CODE_NAME}/; a plan name (slug / numeric prefix / filename) reviews the code that plan touches plus its conformance; an existing file or directory reviews that path; diff reviews uncommitted changes and a git range (HEAD~3.., main..feature) reviews the files it changed.

Shared conventions. Read docs/mds/star-workflow/research-workflow-conventions.md (Chinese: research-workflow-conventions.zh-CN.md) before acting: §1 git, §2 the STOP line, §3 .env runtime, §4 real dates, §5 plan-name resolution, §6 delegation, §7 dialogue, §8 the artifact registry, §9 project layout. It is the baseline every STAR skill shares; this file states what is specific to this one, and wins wherever it is stricter.

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. 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; optionally, individually approved mechanical fixes.

Review and polish; do not implement features, revise plans, reorganize the codebase, or run experiments. Route what the review surfaces beyond the write boundary: 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. Yardsticks are written down; every finding cites one. The rules come from AGENTS.md (esp. §2 simplicity, §3 surgical changes, §5 layout, §6 runtime), from metds/codearc.md when it exists (placement rules, naming conventions, rename residuals), 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 yardstick backs is a style preference, not a finding. Rubric: references/review_rubric.md.
2. Find wide, verify before reporting. Review locally by default; delegate collection selectively — only when bounded, independent, read-only review of several packages materially helps — with every delegate following the finding contract in references/review_rubric.md, never writing, and never grading the overall verdict. Re-read the cited code for every blocker/major finding before it enters the report; downgrade or drop what does not hold up. A review is judged by the precision of its findings, not their count — one wrong blocker costs the report its credibility.
3. Conformance is scored against disk, never against logs. In plan mode, §3 tasks map to code as implemented / partial / missing with pointers, §4 deliverables are checked on disk, and the §5 done-criterion is checked for supporting machinery — EXEC_LOG's claims are corroborated against actual code, never trusted (the reviser's discipline, applied to code).
4. Static tools are evidence, not judges — and never installed. python -m compileall -q always (zero dependencies); ruff/flake8 only if already present in the .env env. Tool output feeds findings; it does not replace reading the code. No usable env → the review degrades to reading-only, says so in the report, and recommends $star-env-builder. Never modify the environment.
5. Fixes are mechanical, individually approved, behavior-preserving. After the report, offer a fix pass covering only docstrings, scope-internal renames, unused imports, and dead code this project introduced. Each item is approved through one direct question at a time before it is applied — one finding (or one same-type batch) per question, recommendation marked — and re-verified after application. Never bundle-approve silently; 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 rename-residual list (registry strings, config type: keys, checkpoint prefixes) are flagged, never touched.

Workflow

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.
   • No argument → all of ${CODE_NAME}/.
   • 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.
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, say so and offer to narrow (one sub-package, or diff mode) with one direct question.

Step 1: Load the yardsticks

Read AGENTS.md; metds/codearc.md if present (placement rules, naming conventions, plan-component map, §7 residual list); in plan mode the plan §1–§6 plus EXEC_PLAN.md / EXEC_LOG.md. Record which yardsticks 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).

Step 2: Cheap static evidence

Through the .env conda env: run python -m compileall -q over the scope, always. If ruff (preferred) or flake8 is already installed in that env, run it on the scope and keep the output as evidence input. Never install or upgrade anything (that is $star-env-builder's). Env unusable → skip the tools, mark the review reading-only in the report, recommend $star-env-builder.

Step 3: Collect findings

• Small scope (≤ ~20 files — a diff-mode review usually is): read every file and apply references/review_rubric.md directly.
• Larger scope: work package by package, delegating selectively per Core Principle 2 — each delegate gets the rubric, a yardstick digest, and its exact file list, and returns the structured finding contract in review_rubric.md. Delegates never write, never review outside their file list, never grade the overall verdict.
• 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

Merge and dedup. For every blocker/major: re-open the cited file at the cited lines and confirm the issue is real and the rule applies; downgrade or drop what fails. Spot-check minors. Findings worth flagging but not confirmed go to the report's Unconfirmed list — never into the verdict counts.

Step 5: Persist the report

Fill assets/code_review_template.md (Chinese: assets/code_review_template_zh.md; the report follows the plan's language in plan mode, else the dialogue language): 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). Real dates only, never invented.

Step 6: Digest in chat

Lead with the verdict, under about 400 words: files reviewed, counts per severity, top ≤10 findings as one-liners (file:line — issue), the conformance verdict (plan mode), which static tools ran. End with the routing for out-of-boundary findings ($star-plan-executor / $star-plan-reviser / $star-code-architect), then offer the fix pass if mechanical findings exist — the user may also stop here; the persisted report is a complete deliverable on its own.

Step 7: Optional 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 residual-list names.
2. Walk the eligible findings in report order, one direct question at a time — apply as proposed / apply adjusted / skip, recommendation marked, one finding per question. More than 4 same-type findings (e.g. 12 missing docstrings) may be batched into one question: apply all / select which (name the numbers) / skip all.
3. Apply each approved fix; after each touched file re-run compileall on it (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.
4. Append the fix record to the report (F<n> — applied / skipped / reverted). If the working tree was clean at Step 0, ask one final question: commit the fixes (stage only the files this pass touched; message star-code-reviewer: apply review fixes — <scope>) or leave them uncommitted. With a dirty tree, leave them uncommitted and say so.
5. Close with what was applied, skipped, and routed, plus the report path.

State Rules

• Reports live under wkdrs/ (the plan's run dir, else wkdrs/reviews/); never under metds/plans/, never inside ${CODE_NAME}/.
• The only code writes are individually approved 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. Residual-list names are flagged, never renamed.
• 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 the single optional fix commit staging only fix-pass files (conventions §1).
• 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.
• Ask fix-pass approvals one at a time and require an explicit answer before any write. The report follows the plan's frontmatter language in plan mode, else the dialogue language.