code-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code review

Orchestrate two until-clean review phases for one target.

1. Phase 1: run `review-until-clean` in an external harness-native review
   session until native review is clean. Never substitute an in-chat subagent.
2. Phase 2: run `cold-pr-review-until-clean` in an in-chat subagent until cold
   review is clean. Do not create a separate top-level task for this phase.

Use `finding-discipline` and `review-guardrails`' autonomous fix bar throughout
both phases. A finding can be real without deserving an autonomous fix. Phase 1
must satisfy the native clean stop condition before Phase 2 begins. Phase 2 must
then stay in the cold-review loop until cold review is clean on the final target
after the last accepted cold-review fix and affected validation.

Phase 1 uses the harness-native review engine: bare `codex review` in Codex,
the built-in `code-review` workflow in Claude Code. If the user names an
engine, that engine wins. `review-until-clean` owns engine selection and
fallback rules.

Treat every external native-review session as temporary. Capture its task or
session ID when it is created, collect its result, then archive it in guaranteed
cleanup on success, failure, cancellation, or early stop. In Codex Desktop use
`set_thread_archived`; for standalone Codex sessions use `codex archive <id>`.
Do not rely on the final response to remember cleanup, and do not leave the
review task visible after its result has been incorporated.

Keep separate unless explicitly requested: repo-specific review bots, security
remediation workflows, OpenGrep, merge, and advisory writing.

`ask-codex` and `ask-claude` are user-invoked cross-harness tools, not review
engines or fallback reviewers. Never invoke either skill from this workflow
unless the current user explicitly requests that exact cross-harness session.

## Workflow

1. Resolve `<skill-dir>` to the directory containing this `SKILL.md`.

2. Select the review engine.

   Use the harness-native engine unless the user explicitly names another:
   Codex in Codex, Claude in Claude Code. Treat an explicit request for Fable
   as selecting Claude. Do not ask about or validate the unselected engine.
   When Codex is selected, confirm the current runtime identity can resolve and
   authenticate the standalone Codex CLI before review.

   Use the model configured by the selected harness. Do not hard-code or
   probe private model catalogues before review; the native command owns model
   availability and reports an actionable failure when its configuration is
   invalid.

3. Freeze the target and review scope.

   Record:

   ```text
   iteration = 0
   last_reviewed_head = <current HEAD or PR head SHA>
   last_reviewed_target = <base + committed HEAD>
   repo_display_name = <readable repo name, such as sample-app>
   findings_db_path = <local SQLite path, normally ~/.local/state/agent-review-findings/reviews.sqlite>
   review_started = <local timestamp>
   baseline_diff = <changed files and changed lines from the branch's first
                    user-authorized review baseline for this base branch>
   scope_baseline = <request, target, intended behavior, owner boundary>
   consult_queue = []
   findings_registry = <SQLite findings database>
   file_coverage = <changed files ranked by current valid review count>
   ```

   Require `HEAD` to resolve to a commit and `git status --porcelain` to be
   empty before `scope-start` or either review phase. Stop and ask for the
   staged, unstaged, and untracked changes to be committed or discarded when
   the checkout is dirty. Review never creates or certifies a temporary
   snapshot of uncommitted code.

   Read [references/guardrails-and-scope.md](references/guardrails-and-scope.md)
   for scope classification, budgets, consult queue, queue matching,
   and blocked-on-consult behavior. For a new run, persist or inherit the branch
   baseline before any review fix. A later run on the same branch and base must
   keep the first authorized LOC baseline and its remaining allowance;
   completing and restarting review never grants a fresh buffer:

   ```sh
   review_findings_bin="<skill-dir>/scripts/review-findings"
   "$review_findings_bin" schema
   "$review_findings_bin" scope-start \
     --repo <repo> --repo-path <repo-root> --branch <branch> \
     --target <target> --base <base> --head <head> \
     --scope-summary "<request, behavior, and owner boundary>"
   ```

   Treat `schema` output as the authoritative finding-record contract. On a
   resumed run, use `scope-status`; never rerun `scope-start` to move the
   baseline. Done when `review-guardrails` is loaded and the CLI has persisted
   the baseline.

4. Run one-time setup for the current target.

   Read [references/setup-and-lenses.md](references/setup-and-lenses.md). If
   its flow map identifies at least three substantially independent runtime
   flows, also read
   [references/large-diff-slices.md](references/large-diff-slices.md) once
   before Phase 1; do not slice a diff merely because it has many files. Done
   when the changed flows are mapped, required lenses have run, conditional
   lenses have run or been marked not applicable, the Fowler smell baseline has
   been considered on the Standards path, the neutral cold-review risk checklist
   exists, and validation targets are known.

5. Prepare the findings registry.

   Read [references/findings-registry.md](references/findings-registry.md).
   Load `speak-fking-english` and use its reader reset for each batch of finding
   cards and for the final owner summary.
   Done when the review-findings helper path is resolved and every accepted,
   rejected, deferred, provisional, reopened, user, lens, native-review, and
   cold-review finding can be recorded instead of reconstructed from chat.
   Query current file coverage before dispatching review agents, and give the
   least-covered changed files priority without describing prior verdicts or

From jesse-merhi/skills, MIT.

More from jesse-merhi/skills