Update to Qodo
Snapshot Nov 18, 2026 · 18:11 UTC · version 2.3.2
Collection source: downloaded plugin package.
Instructions updated for qodo-review
Full description — Now says: after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Full description
Nov 9, 2026 · 12:07 UTC
during substantive coding milestones and before a PR or completed-work handoff. Use light background checkpoints while coding, collect and assess findings with session context, and run a final review before handing off.
Nov 18, 2026 · 18:11 UTC
after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch authorized fixes and stop unproductive review loops.
Skill instructions
Nov 9, 2026 · 12:07 UTC
during substantive coding milestones and before a PR or completed-work handoff. Use light background checkpoints while coding, collect and assess findings with session context, and run a final review before handing off. Also use for "rev...
Nov 18, 2026 · 18:11 UTC
after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch authorized fixes and stop unproductive review loops. Also use for "review my local ...
Supporting files
Nov 9, 2026 · 12:07 UTC
[{"relative_path":"agents/openai.yaml","size_in_bytes":343},{"relative_path":"references/connected-progress.md","size_in_bytes":2293},{"relative_path":"references/context-delivery.md","size_in_bytes":1954},{"relative_path":"references/fi...
Nov 18, 2026 · 18:11 UTC
[{"relative_path":"agents/openai.yaml","size_in_bytes":343},{"relative_path":"references/cli-execution.md","size_in_bytes":9259},{"relative_path":"references/connected-progress.md","size_in_bytes":4094},{"relative_path":"references/conte...
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -1,10 +1,10 @@ --- name: qodo-review -description: Review local changes with Qodo during substantive coding milestones and before a PR or completed-work handoff. Use light background checkpoints while coding, collect and assess findings with session context, and run a final review before handing off. Also use for "review my local diff", "pre-PR review", or "run qodo review". Use qodo-review-resolver for findings already posted on a PR. +description: Review local changes with Qodo after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch authorized fixes and stop unproductive review loops. Also use for "review my local diff", "pre-PR review", or "run qodo review". Use qodo-review-resolver for findings already posted on a PR. owner: Qodo metadata: vendor: qodo - version: "1.10.15" + version: "1.10.16" recommended: "true" package: "qodo" distribution: "marketplace" @@ -15,483 +15,297 @@ ## Description -Review **local changes during coding and before handing off completed work**. `qodo review` sends your diff, new/untracked files and coding-session context to Qodo. Evaluate its structured findings and apply authorized fixes. Only the base commit must be on the remote; the command never pushes or creates a PR. - -Use this skill for local changes, including unpushed work on an existing PR. Use `qodo-review-resolver` to work on findings from the PR's remote review; do not duplicate that review for an unchanged pushed snapshot. +Use local review to improve the intended change, not to accumulate clean-looking runs. +The workflow is: finish a useful slice → test → review with context → assess findings +→ apply authorized fixes → test again → review changed work when useful. + +`qodo review` collects local changes without pushing, commenting or opening a PR. +Only the comparison base must exist on the remote. +Use `qodo-review-resolver` for findings already posted on a PR. +Do not duplicate remote review for an unchanged pushed snapshot. ## Prerequisites -- An authenticated Qodo CLI is available, or a connected QAR MCP server and a tested local input collector are available; review capability is enabled. -- The comparison base exists on the remote; local changes and context need not be pushed. -- The coding-session context and any ticket or design references are ready to attach. - -## Choose when and how deeply to review - -| Situation | Selection | -|---|---| -| A coherent milestone during substantive coding | `--fast --async`: light checkpoint; continue useful coding and collect the result. | -| Ordinary final review before opening/updating a PR or handing off completed work | Omit both depth flags: auto. Collect and assess the result before claiming review completion. | -| User intent calls for unusually thorough scrutiny, or a known high blast radius warrants it | `--deep`, with a brief reason tied to the request or affected behavior. | - -Automatic coding checkpoints always use `--fast`. A deliberate deep review can happen earlier when -one of the exceptions above applies. A request such as "examine subtle races thoroughly" can justify -it without the word "deep"; generic "review" or "double-check" does not. Identify concrete impact, -such as shared authorization, a destructive migration, or a contract used by multiple services. -Diff size, session length, PR readiness, or a security-related filename alone do not justify deep. - -With **no flag**, the CLI omits depth and the reviewer/deployment selects it. Auto can select deep; -it is not guaranteed standard and does not impose a spending cap. There is no `--standard` flag. -`--fast` and `--deep` are mutually exclusive; depth is selected anew for each invocation. - -## Checkpoints and final handoff - -- Review a completed, testable slice when its feedback can guide the remaining work. Do not review - unfinished exploration, every edit, trivial changes automatically, or simply because time passed. - Respect the user's review scope and budget. A pause for a question or approval is not a final handoff. -- Keep at most one automatic checkpoint active per task. Retain its operation ID, submitted scope - and snapshot/context association in the task's existing state. Poll status at natural pauses while - doing useful work; do not launch another review to check progress or re-review unchanged inputs. -- Collect every submitted result within its retention window. Recheck findings against current code - before acting: the working tree may have changed. A superseded result cannot certify newer work. - Use the existing CLI lifecycle; no separate sub-agent or scheduler is required. -- Before final review, collect the outstanding checkpoint and reconcile its findings. Review the - full intended change with auto, or justified deep, rather than handing off on a light checkpoint. - Remove temporary path restrictions that would leave part of the intended change unreviewed. - If the same snapshot already has completed final coverage with compatible context, use that result. -- Batch authorized fixes, verify them, then re-review changed work. Keep `--fast` for checkpoint - fixes; retain the requested auto or justified deep mode for final-review fixes. Let the engine - determine incremental eligibility; auto may route differently on each pass. Do not manually switch - final fixes to `--fast` or force `--deep` just to pin auto routing. If work returns to substantial - implementation, resume light checkpoints and establish final coverage again before handoff. -- If another pass repeats the same concern without actionable progress, stop the automatic loop and - report the remaining issue and needed decision/check. Do not buy repeated passes to chase zero. - Pending, failed, partial or superseded review is not clean; surface remaining findings and coverage. - -## Prepare a PR handoff - -During coding, commit only changes made for this task before every local review, including the first fast checkpoint and reviews of fixes. Follow the user's commit policy; leave pre-existing or unrelated edits untouched. A local commit is sufficient; pushing is not required. -Retain the submitted HEAD (`git rev-parse HEAD`) with each review's operation ID. Before opening or updating a PR, compare its intended head with the completed final review's SHA; if they differ, review the intended head first. Commit and review later edits again, preserving earlier reviewed commits in branch history so the handoff can trace findings to their original code. -For review-only tasks, when commits are not authorized, or when task changes cannot be isolated safely, review the requested scope without committing and explain that local-to-PR handoff may be incomplete. A HEAD SHA alone does not identify uncommitted changes. -For authorized notes maintenance, use `qodo-review-notes` during planning and development to retain decisions, constraints and evidence changes, publish existing-HEAD PR notes before opening, refresh if HEAD changes, and bind afterward; retain local review context and verify consumption separately. - -## Instructions -### Choose the execution path - -Prefer `qodo review` when available: it gathers and filters tracked and untracked local changes, resolves the remote base, attaches context, and manages checkpoint state. The QAR MCP -`start-pre-pr-review` tool instead accepts a prepared `diff`, `base_sha`, repository locator, and context; it cannot read this worktree. Use that MCP tool only when a tested local collector -has produced the same intended scope and exclusions, reported omitted files, and verified that the base SHA is fetchable. Do not assemble an ad hoc `git diff` and call it equivalent coverage. -If no collector is available, report that MCP-only local review cannot safely cover this worktree; do not claim a completed review. - -For a prepared MCP review, inspect the live schema. Set `review_scope.stream_id` to exactly 64 lowercase hexadecimal characters: SHA-256 of a JSON array containing the resolved real worktree root, plus the resolved working directory for path-limited reviews. Reuse it across checkpoints; a UUID is invalid. -Retain the same `request_id` and exact arguments for an uncertain start: `request_id` is this start tool's logical-action retry key, and no separate `idempotency_key` argument is declared. Poll `get-managed-agent-operation` at its advertised interval, then fetch all `get-managed-agent-result` chunks and verify their reported digest and byte count before interpreting the artifact. -These are short lifecycle calls, not MCP Tasks. Check `isError` before reading a receipt. Apply the same context, depth, coverage, finding, and authority rules below. CLI version, identity, and command instructions below apply only to the CLI path. - -Preserve notices, attach self-contained context, show progress, use a suitable timeout, -read the structured result, and act on findings. - -## Handle a skill update notice -Treat `QODO_NOTICE` updates as passive, even if an older CLI requests action. Continue the task -without inventory or update questions; mention each event at most once. Dismissal leaves recorded maintenance -policy and opt-outs unchanged. Updated skills load next session; do not interrupt this one. -For user-requested updates, follow the [manual-update procedure](references/skill-updates.md). - -## Execution - -- MCP: use live schema arguments; skip CLI shell steps. -- CLI: use complete UTF-8 files without a BOM (`--args-file` for tools, `--context-file` for reviews); examples are POSIX. -- Windows CLI: read [shell guidance](references/windows-shells.md) before the first call; [launcher recovery](references/windows-launcher.md) only if invocation fails. Reuse the resolved invocation. +- The intended repository, comparison target and review scope are known. +- Qodo review is available through the CLI, or through MCP with a tested local collector. +- The user's edit, commit and review-budget constraints are known. +- Relevant coding-session context is available. Do not require the user to reconstruct the session. ## Runtime compatibility gate -Resolve the executable using this skill's command-not-found fallback, then run `<qodo> --version` -with no provenance flags. This skill requires Qodo CLI **2.0.0 or newer** and a runtime with review API v2. -Only when the runtime needs an update, before any update check/change, test whether `QODO_UPDATE_BASE_URL` is set; -never print its value. If set, stop for the user to resolve the source override before proceeding; -do not change it yourself or assume it matches the recorded origin. -If the version is older or cannot be parsed, do not run `whoami`, `login`, a review, or a managed tool and -do not describe the failure as an authentication problem. Choose one deployment-approved upgrade -route, explain it, and reuse covering runtime-update authorization or ask once before changing the -installation. For parsed 1.x, normal `qodo update` can reach approved 2.x when its recorded origin enables migration. -If legacy aliases still serve 1.x, check the supported same-origin `latest-2` recovery route first. -Require a compatible newer 2.x target from the selected route's supported check; missing/failed checks stop. -Propose `qodo update --channel latest-2` only for that verified recovery route; never assume activation. -This exception covers only deployment-approved 1.x to stable 2.x; it does not authorize other -major migrations or change the existing automatic-update policy for future majors. -For every route, preserve origin, explicit version choices and update holds; never substitute a channel for an exact version. -For an unparseable runtime or no supported updater, use a checksum-pinned installer supplied by -Qodo or the organization with covering installation authorization; never switch to public service or invent a digest. -Make one approved runtime attempt, then rerun the unadorned version probe and continue only when it satisfies the minimum. On denial, failure or continued -incompatibility, stop with skill and user files unchanged; do not retry through another route. - -## Quick start -You just wrote the code, so you hold the one input the reviewer can't get anywhere else: **why**. -Attach it on every run — write the session context first, then review: -Before each new submission, read [Session context](references/review-turn-context.md) and refresh `recent_work`. -Examples use `notes`; check `qodo review --help`. If it advertises only `summary`, use that field -for the same narrative, keeping `decisions` and `recent_work` unchanged. + +Prefer the CLI because it collects and filters the worktree and manages review checkpoints. +Before CLI use, read [CLI execution](references/cli-execution.md#preflight). +In every command example, replace `qodo` with that resolved invocation, including the version probe. +On Windows, also read [shell guidance](references/windows-shells.md) before the first command. +Use [launcher recovery](references/windows-launcher.md) only when invocation fails. +Require Qodo CLI **2.0.0 or newer** and a runtime with review API v2. +Start with the unadorned probe: ```sh qodo --version -qodo read whoami --json --skill qodo-review --skill-version 1.10.15 --distribution marketplace --host codex ``` -See [illustrative CLI examples](references/review-turn-context.md#cli-examples) for context, base and depth choices. +If compatible, verify identity unless a successful check still covers this execution context: -You can also keep `.qodo/session-context.json` (same JSON shape) updated at the repo root — it is auto-attached to every run, so even a bare `qodo review` carries your context. An explicit -`--context-file` overrides it; the file itself is never part of the reviewed diff. Don't commit it -(add `.qodo/` to `.gitignore` or `.git/info/exclude`). -Add `--json` to anything you parse. For connected execution, allow a multi-minute timeout or -background the process; async submission and status collection are separate short calls. -**Confirm the exact flags with `qodo review --help`** (offline) — the examples here are illustrative. - -## Choose execution for the selected review - -Use `--async` for coding checkpoints: submit, continue useful work, then collect with `review status`. -For a final review, async is also valid, but collect and assess it before the handoff. If live progress -is useful, read [connected progress](references/connected-progress.md) and use `--json --progress` -with a host-native background process. Never combine `--progress` with `--async`. -A review can take minutes; keep a connected process alive or use async so client exit cannot cancel it. -If async is unavailable in the installed CLI, keep the selected depth and use the connected fallback. - -For connected progress, the canonical execution rules are: - -- Attach context through a file; stdin heredocs are unsuitable for background execution. -- Use a unique per-run temporary directory. Separate the single result JSON on stdout from NDJSON - progress on stderr. Poll the growing progress file through the host's nonblocking process tools; - never run a foreground `tail` that blocks the agent until completion. -- Relay short status messages, not raw JSON or model output. Translate events by `kind`: - `cli.status` gives a readable message; `tool.activity` gives tool name and outcome; - `task.delta` and unknown kinds are occasional generic heartbeats, not one message per event. -- For `qar.client.reconnecting`, relay attempt/delay and structured close/error codes when present. - `qar.client.reconnected` means transport opened; `resubscribeAttempts` counts reattached live tasks. - `qar.client.reconnect_failed` signals exhausted retries, not the final error explanation. -- On `task.done`, inspect `payload.status`; on failure/cancellation or `error`, stop progress relay - but keep waiting for process exit. Always read the result envelope, including on nonzero exit: - actionable messages/hints such as `closed_preview` may appear only there. Progress is not findings. -- Capture the process exit status, reap the child and disarm its PID before parsing. On interruption, - terminate and reap the active child. Clean up only that run's directory on exit/failure/interruption; - never reuse or remove a shared `.qodo/review.*` path. -- If background progress is unavailable, run foreground with a multi-minute timeout, preserving - selected depth and context. Missing progress is not a reason to fail review or downgrade depth. - -**`qodo: command not found`?** On POSIX retry `"${QODO_HOME:-$HOME/.qodo}/bin/qodo"`; -on Windows follow the linked guide. Keep the resolved invocation; report unusable launchers. -For missing installs, obtain Qodo's or the administrator's checksum-pinned installer; never invent a digest or pipe scripts into a shell. - -**Sandbox auth diagnostic.** Missing credentials can mean inaccessible keychain access. When that -is plausible, request one exact read-only `qodo read whoami` retry through the host's approval -flow before recommending login. Stop on denial; that approval covers no other command. Reuse a -successful check in the same executable/workspace/deployment and execution context; request each -required host approval. Network, TLS, service, and explicit authorization failures retain their -own diagnosis, not a login recommendation or an automatic sandbox bypass. - -## Submit and collect with `--async` - -Check support with `qodo review --help`. The following example submits a coding checkpoint. For final -review omit `--fast`; add `--deep` only under the selection policy above. Attach the same context in -all modes. Shell snippets illustrate the CLI protocol; use the host's own nonblocking wait mechanism. - -`--async` removes the connection from the critical path. It submits the review over HTTP, prints an -**operation id**, and exits 0 immediately. The run continues server-side whether or not your process -is alive; you collect the result later with `qodo review status <operation-id>`. - -``` -command -v jq >/dev/null 2>&1 || { printf '%s\n' 'This async recipe requires jq; install it or use the live qodo review flow.' >&2; exit 1; } -QODO_REVIEW_CONTEXT="${QODO_REVIEW_CONTEXT:-.qodo/session-context.json}" -[ -f "$QODO_REVIEW_CONTEXT" ] || { printf '%s\n' "Write the required review context to $QODO_REVIEW_CONTEXT (or set QODO_REVIEW_CONTEXT to its path)." >&2; exit 1; } -QODO_REVIEW_BASE="$(git merge-base HEAD origin/main)" || { printf '%s\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # substitute the intended target -if ! submission="$(qodo review --base "$QODO_REVIEW_BASE" --context-file "$QODO_REVIEW_CONTEXT" --async --json --fast)"; then printf '%s\n' "$submission" >&2; exit 1; fi -if ! id="$(printf '%s\n' "$submission" | jq -er '.operation_id | select(type == "string" and length > 0)')"; then printf '%s\n' "$submission" >&2; exit 1; fi -qodo review status "$id" --json # collect it +```sh +qodo read whoami --json --skill qodo-review --skill-version 1.10.16 --distribution marketplace --host codex ``` -Poll the existing operation until it finishes; do useful work between status checks. Submission -exit 0 means accepted, not reviewed. Collection uses these exit codes; read any returned retry delay: +An old or unparseable version stops authenticated calls. +Follow the reference's bounded compatibility recovery without changing deployment or update policy. +Confirm available review flags with `qodo review --help`. +Do not infer installed capability from an open PR or newer source checkout. + +MCP cannot read this worktree. Before an MCP review, read [MCP execution](references/mcp-review.md). +Without a tested collector matching the intended scope and exclusions, report the coverage blocker. +An ad hoc `git diff` is not equivalent collection. MCP users skip CLI preflight. + +## Execution and recovery policy + +These are the canonical gates. References supply command syntax, result dictionaries and platform recipes; +they do not select different authority, compatibility or recovery policy. + +- **Trusted runtime:** retain the resolved installed invocation for every call, including `--version`. + Never run repository-local launchers. If neither installed invocation works, stop the CLI path. + Installation requires covering approval and a Qodo/organization-supplied checksum-pinned installer. + Never invent a digest, pipe an installer into a shell, or switch deployments. +- **Compatibility recovery:** old or unparseable versions stop identity, login, reviews and managed tools. + Check only whether `QODO_UPDATE_BASE_URL` is set; never print its value. If set, stop for the user. + Preserve the recorded origin, exact version choices and update holds. Choose one approved route. + Every updater route, including ordinary update, needs a successful check offering a newer compatible 2.x target. + Failure, no update or an incompatible target stops before any runtime change; do not switch routes. + Same-origin `latest-2` is only a selected, verified legacy 1.x-to-stable-2.x route, not another-major approval. + For an unparseable runtime or no supported updater, use the separately authorized checksum-pinned installer route. + Make one approved runtime attempt, then probe the version again. Denial, failure or incompatibility stops. +- **Identity and discovery:** reuse identity only for the same invocation, workspace, deployment and execution context. + Possible sandbox keychain failure permits one explicitly approved read-only identity retry; denial stops. + Only explicit missing credentials justify login. Preserve TLS, network, service and authorization failures. + Missing catalog or an unknown managed command permits one catalog refresh, not another account. + A still-unavailable capability is a blocker. An unknown built-in command needs compatible runtime support. +- **Collection and retry:** preserve the accepted operation and exact uncertain-start request. + A status transport failure permits one collection retry after the returned delay, otherwise 15 seconds. + Failed identity or integrity verification is not a status transport failure. + Preserve the rejected evidence; retry collection only when an applicable recovery gate permits it. + A confirmed recoverable terminal failure permits one cause-corrected resubmission, not another retry per symptom. + User/task no-auto-retry instructions or a returned retry prohibition require explicit approval first. + A repository-identity correction preserves base, scope, context and effort and uses that same retry allowance. + Permission, authentication, entitlement, rate-limit or further failure stops. A pending run is never restarted. + Keep a connected client alive; reap its child before parsing. Progress is not a result. + Retain the final envelope even after nonzero exit and before deleting only this invocation's temporary files. +- **MCP:** require the tested collector, safety exclusions, omission report and fetchable base above. + Preserve request identity after uncertain admission; collect and verify every result chunk before interpreting it. + Keep result-view arguments unchanged while following pagination cursors. + Never invent an unsupported collector mode, retry-key field or substitute checkout. +- **Finding-status writes:** fixing code does not authorize a dismissal. An authorized local dismissal uses original + finding IDs and their actual local-review IDs, grouped by review, reason and explanation. + Never substitute a run ID or PR URL for a missing local-review ID, or omit advertised replay protection. + Read back each stored outcome. A prior disposition or conflict is not a new successful write. + Report status persistence separately from downstream synchronization: `reconciled: false` can mean the + status was saved but synchronization is incomplete. Do not report that as a failed stored transition. + Recover an uncertain invocation with its original request and transport key. + On MCP, a completed same-key replay returns the stored result without retrying synchronization. + After verified storage, a separately authorized synchronization attempt needs a new invocation and a new retained transport key. + Keep the business arguments unchanged. Verify each new outcome. + An unknown outcome does not authorize key rotation. Report unavailable recovery instead of claiming synchronization. + Collect only a returned, supported operation handle. A synchronous tool result does not establish polling support. +- **Requested maintenance:** preview the complete affected installation scope and apply only covering approval. + Runtime approval is not skills-installation approval. Do not widen owners, packages, origins or update policy. -| Exit | Meaning | Do | -|---|---|---| -| `0` | Finished. Findings rendered — **identical** output to a live run (`{findings, meta}` under `--json`). | Act on the findings as usual. | -| `2` | Still running or polling throttled. | Respect `retry_after` when present, then poll the same ID. | -| `1` | Failed, canceled, expired, or no such operation. Read the `error` envelope. | Follow the bounded recovery below; never assume clean. | - -``` -# This collection attempt returns failures to the host for classification under Recover a review. -# On nonzero exit, preserve the operation ID and emitted error; apply bounded recovery there. -QODO_REVIEW_TMP="$(mktemp -d "${TMPDIR:-/tmp}/qodo-review.XXXXXX")" -cleanup_qodo_review() { [ -n "${QODO_REVIEW_TMP:-}" ] && [ -d "$QODO_REVIEW_TMP" ] && rm -r -- "$QODO_REVIEW_TMP"; } -trap cleanup_qodo_review EXIT; trap 'exit 130' INT; trap 'exit 143' TERM -while :; do - status=0; qodo review status "$id" --json > "$QODO_REVIEW_TMP/result.json" || status=$? - case "$status" in - 0) cat "$QODO_REVIEW_TMP/result.json" || exit 1; break ;; - 2) delay=$(jq -r 'if (.retry_after | type) == "number" and .retry_after > 0 then .retry_after else 15 end' "$QODO_REVIEW_TMP/result.json") || exit 1 - sleep "$delay" ;; - *) cat "$QODO_REVIEW_TMP/result.json" >&2; exit "$status" ;; - esac -done -``` - -**What it costs — know these before you choose it:** +## Instructions -- **No streaming progress.** There are no progress events on this path — the run isn't attached to - your process — so `--async` and `--progress` are rejected together rather than emitting a stream - that never arrives. There is no intermediate status beyond "still running". If the user is - watching and wants to see life, use the [connected progress](references/connected-progress.md) recipe instead. -- **No human-in-the-loop.** This surface runs deterministic agents only; a review that asks for - input fails instead of waiting. (`qodo review status` says so and tells you to re-run without - `--async`.) -- **The result is kept for 1 hour** after the review finishes, then it is discarded. Collect it - inside that window. Past it, `qodo review status` cannot tell "expired" from "never existed" or - "belongs to someone else" — the runtime answers all three identically, on purpose — so it reports - all of them. Report the missing review evidence before deciding whether a new run is needed. -- **Do not assume a new submission is free or deduplicated.** Use `review status` to collect an - accepted run. If admission is uncertain, follow the CLI's returned recovery command (on versions - that support it, `--async --retry-submission <id>`); never substitute a fresh `qodo review` to poll. - Preserve the retained request during recovery instead of gathering the changing working tree again. -- **Retain the operation id.** It identifies the accepted run; a submission-recovery ID has a different - purpose. Do not throw away either handle before collecting or reconciling its outcome. - -**The operation id is not the `trace` id.** `qodo` prints a `trace <id>` line on failures — that's -an OpenTelemetry id for support to diagnose a run with, and it cannot fetch anything. The -`operation_id` from `--async` is the resumable handle. Don't pass one where the other is wanted. - -## Preflight - -1. **Auth and catalog.** Run `qodo read whoami` unless a successful check still covers this - execution context. After the sandbox diagnostic when applicable, only explicit missing credentials - call for login: preserve the organization's exact login command/endpoint, never guess or switch - a customer deployment to Cloud. `No tool catalog cached` is not proof of missing credentials; - refresh once with `qodo tools --refresh` and retry the check. Other failures retain their error - and stop this workflow. After identity succeeds, an unknown managed command permits one catalog - refresh and schema recheck. If still absent or `tool_unavailable`, report the missing capability; - do not repeat login or refresh. - An unknown built-in `qodo review` needs runtime recovery, not login or catalog refresh. -2. **Resolve the base.** Select the intended target (`origin/main` unless the change targets another - branch). Fetch that target before reviewing current remote history; if unavailable or deliberately - offline/pinned, disclose that the review uses locally fetched history rather than claim it is current. - Compute `git merge-base HEAD <target-ref>` and pass that SHA as `--base` on every - submission, including checkpoints and connected runs. This also protects older CLIs whose - default compares the target tip. An explicit `--base` is exact; passing the target branch itself - can misattribute newer target-only changes. Honor a user-requested exact comparison. - If no common ancestor is available, fetch missing history or report the blocker; never fall - back silently to the target tip. The base must be pushed; review authority does not allow a push. - Local edits and untracked files are included without committing or pushing them. -3. **Write your context.** Capture actual choices and natural-language ownership in `decisions`, - review context/evidence in `notes`, and this round's work in `recent_work`. Refresh facts and - verification results before review. Follow the SessionContext guidance below; leave unknown - ownership or rationale explicit. - -## What gets reviewed - -`qodo review` gathers, all client-side: - -- The **tracked diff** vs the base, plus **new/untracked files** (secrets, binaries, oversized, - and gitignored files are filtered out and reported — never silently dropped). -- The **branch name**, **HEAD commit**, and a **description** synthesized from your commit messages. -- Any **ticket refs** and **session context** you attach (below). - -`--json` returns each finding once in `findings`; `finding_state` buckets reference IDs. Assess `.introduced` -**and** `.still_open`; report detected fixes in `.resolved` and stored dismissals in `.dismissed`. Older buckets contain full objects. -Default fields: `id`, `title`, `description`, `category`, `action_level`, `attribution_status`, `git_sha`, -`location`, `evidence.citations`. Inspect the code location and evidence; preserve the original finding ID. -`--extended` adds stored supporting detail; it changes neither review depth nor execution. -Local `review_agent_comment` is stored reviewer feedback in both views; reuse carries it forward without new execution. Read it alongside findings and coverage. -For authorized status writes, group IDs by `meta.local_review_ids[id]`; report unavailable references. -Fix instructions and reviewer internals are excluded. See the [field guide](references/finding-results.md) for field details. -If `finding_state.complete` or `meta.coverage.complete` is false, report the incomplete coverage. -`meta.analysis.mode` is `full`, `incremental`, or `reused`. Reused means the same reviewed snapshot -and compatible context; earlier open findings remain open. The CLI privately saves the submitted patch. -It advances its checkpoint after collecting an eligible result, including via `review status`; failed or older completions cannot replace a newer checkpoint. -Keep the same base, path scope, requested depth mode and context during a fix loop. Changed context, expired or -unverifiable checkpoints, and unsupported deltas fall back to full review. Never fabricate a checkpoint. -For a deliberately fresh assessment use `--full` (confirm support with `--help`). It controls scope, -not depth; it is not needed on every fix. Changing the requested depth mode invalidates compatible -checkpoint coverage. Auto does not promise a fixed effective tier; rely on returned analysis/coverage. -Older engines omit these fields: use their findings and coverage without claiming reuse. -Prefer `meta.run.passes` for actual outcomes; legacy `meta.reviewers` describes configured dimensions. Report failed/skipped components and missing metadata; reuse has no new execution. - -## Attach coding-session context - -Use `--ticket <full-url>` for fetchable ticket context; a bare key is only detected metadata. -Use `.qodo/session-context.json` at the repo root for ambient context, or `--context-file <path>` -to override it (`-` reads JSON from stdin). Capture context as it emerges and refresh before review: - -```json -{ - "decisions": ["The user selected optimistic locking to avoid contention."], - "notes": "src/orders.ts:updateOrder enforces the version check. Order tests passed; production contention was not tested.", - "recent_work": ["Added optimistic locking; this round includes new behavior."] -} -``` +### 1. Review at a useful moment -**Decisions:** Record actual choices and known rationale in natural language. Identify explicit -user requirements, user-selected/approved options, and coding-agent choices. A user-selected agent -proposal is user-selected. Include a source/quote when useful; -no fixed source tags are required. Leave unknown ownership/rationale explicit; never invent it. -Put undecided proposals in notes. - -**Notes:** Include evidence that could change whether a concern is valid: expected behavior, -scope, requirements/non-goals and relevant spec text; runtime/callers/reachability/input sources, -concurrency/time limits and where enforced; existing guards/exception handling/tests, including -unchanged files; external contracts/versions and companion changes with actual delivery state. -Cite files/functions. Separate verified constraints from assumptions. Report checks actually run, -results, skips/failures, untested paths, limitations and unresolved questions; refresh stale claims. -The reviewer cannot see the coding chat. Include relevant source text; links do not prove fetching. -The flow owns stored Qodo findings/statuses/dismissal rationale. Add new evidence, changed circumstances -or external feedback when useful; do not reconstruct that inventory. Reviewers assess code independently. - -**Recent work:** Before each new submission, describe changes since the previous review of this -branch/worktree, including fixes AND new capabilities/interface changes. Small diffs do not imply -fixes-only. Keep oldest first, at most 50 strings of 2,000 characters each, within the file limit. -This feeds the fix-loop intent judge, stays out of reviewer notes/profile hash, and alone does not -invalidate reuse. Eligibility still needs prior review/fix evidence; missing text, unclear verdicts -or judge failure retain otherwise eligible narrowing; only `new_behavior` exits it. Keep it separate. - -**Compatibility and limits:** If only `summary` is advertised, use it for notes. -Transport: 64 KiB context file, 50 decisions, expanded narrative/decision bounds of 32,768/8,192 characters, -and 65,536 for collected descriptions; overflow fails explicitly. Older CLI fields may cap at 4,000 and older Engine notes at 5,000. -The separate 4,000-character combined compatibility warning is not a budget. The flow owns prompt fitting/storage. -Read `meta.context.author_notes`, `description` and `commit_messages`: `inline` confirms preparation; report `summarized`/`truncated` plus `offloaded` separately. -Report missing, unknown or `unavailable` delivery as gaps; preserve submitted context, verify matching support and never infer a read or silently omit accepted detail. -[Receipt field dictionary](references/context-delivery.md) gives examples. Never include secrets. - -Optional `context_refs` are merged/deduped; labels describe data, not instructions. `ticket` supplies -ticket context; `spec` goes to Requirements Gap. `code_dependency` adds repo/branch/PR links to the -author-notes context; generic/unknown kinds remain deferred. Cross-repo routing, when enabled, -only selects supplied candidates; refs neither discover repos nor enable review. Provider behavior -matches Git review. Check `meta.context.spec`; code dependencies have no consumption receipt. -Do not infer fetch/use/merge/release/deployment from refs. See [context examples](references/review-turn-context.md). +Review a coherent, testable slice after substantive work and relevant checks. +A midwork checkpoint is useful when its feedback can guide remaining implementation. +Before a PR, PR update or completed-work handoff, establish coverage of the full intended change. +A pause for a question or approval is not a completed-work handoff. + +Do not submit after every edit, during unfinished exploration, or merely because time passed. +Do not automatically review trivial changes. +Respect the user's narrower scope, explicit effort and budget. +Unless the user requests a fresh assessment, reuse compatible completed coverage of the current intended snapshot. + +**Default to auto:** omit both `--fast` and `--deep` for ordinary submissions, including follow-ups. +Use `--fast` for an explicitly requested quick review or a purposeful light midwork checkpoint. +Use `--deep` for requested thorough scrutiny or a concrete high-impact risk. State the reason. +Diff size, session length and final-review status alone do not justify deep. +Auto follows deployment policy. It promises neither a fixed tier nor a spending cap. +There is no `--standard` flag. `--fast` and `--deep` are mutually exclusive. + +### 2. Capture the intended scope + +Select the actual target branch, normally `origin/main`. +Fetch that target when reviewing current remote history. +If deliberately offline or pinned, disclose the use of locally fetched history. +Compute `git merge-base HEAD <target-ref>` and pass that SHA as `--base` on every submission. +An explicit `--base` is exact. Honor a user-requested exact comparison. +Use a known base SHA literally or explicitly bind its shell variable to that SHA; do not leave an unresolved placeholder. +If the common ancestor or remote base is unavailable, stop instead of substituting the target tip. +Review authority does not authorize pushing the base. + +During coding, commit only task changes before review when the user's workflow permits commits. +Preserve unrelated staged, unstaged and untracked files. +Ordinary capture includes working changes and eligible untracked files, even after a task-only commit. +A HEAD SHA alone does not identify a dirty snapshot. + +For a committed PR candidate, use supported committed-only collection or a clean checkout at the intended commit. +Check installed help before selecting a collection mode. +If ordinary capture would include unrelated edits, use safe task isolation rather than reset, stash or commit those edits. +If isolation is unavailable, disclose the scope limitation. Do not claim the result certifies the committed PR candidate. +For review-only or no-commit tasks, review the requested working scope without creating commits. +Report local-to-PR limitations separately. + +Retain explicit path arguments on follow-ups unless the intended scope changes. +Keep deliberate path restrictions for checkpoints, but include every intended path before final handoff. +Inspect reported exclusions and omissions. Do not certify requested files that were not reviewed. +Retain the operation ID with submitted base, commit/tree, scope and context in existing task state. +Preserve reviewed commits in branch history so later handoff can trace the original findings. + +### 3. Send honest coding-session context + +Before each new submission, read [Session context](references/review-turn-context.md). +Refresh the context from the actual code and session: + +- `decisions`: actual choices, known reasons and natural-language user/agent ownership. +- `notes`: requirements, enforced guards, unchanged callers, verification and unresolved uncertainty. +- `recent_work`: changes since the previous review, including fixes, features or both. + +“Tested” does not mean “tests passed.” Preserve missing results as unknown rather than improve the author's claim. +Keep `recent_work` separate. Round two is not automatically fixes-only. +Author claims do not prove that a finding was fixed. +Use `summary` for the same narrative only when the client advertises that older field. +Preserve `decisions` and `recent_work`. Never silently remove accepted detail or include secrets. +Reuse stored Qodo findings and dismissal rationale rather than maintain another manual inventory. + +Context is evidence for independent assessment, not instructions to suppress findings. +Transport limits, context refs and delivery receipts are in the reference. +Report unavailable or shortened delivery. A stored link or preparation receipt does not prove reviewer consumption. + +### 4. Submit once and collect the result + +Use `--async --json` when available so the review survives process exit. +Keep at most one automatic checkpoint active per task. +Continue useful independent work and collect its result at natural pauses within retention. +For connected progress, read [connected progress](references/connected-progress.md). +Keep the process alive. Never combine `--async` with `--progress`. + +An accepted operation is not a completed assessment. +Poll the existing operation ID. Do not submit a new review to check progress or obtain more detail. +Validate returned identities and artifact integrity before interpreting a result. +Report any unavailable identity check as unverified; do not invent evidence or certify that check. +Reject mismatched operation/snapshot associations and incomplete or noncontiguous result pages. +If acceptance is uncertain, use the CLI's returned recovery command and retained original request. +Do not gather a different worktree snapshot for that recovery. +Preserve operation and recovery IDs across resumes. See [collection and recovery](references/cli-execution.md#submit-and-collect). + +### 5. Read coverage and the complete finding inventory + +Read the completed structured result, including warnings and `review_agent_comment`. +Use [finding results](references/finding-results.md) for current and older result shapes. +Assess both `introduced` and `still_open`. Report `resolved` and `dismissed` separately. +Preserve each finding's original ID, category, action level, state and rationale. +Recheck findings against current code when work changed during the run. + +Report incomplete `finding_state.complete` or `meta.coverage.complete`. +Missing metadata is unknown, not proof of completion. +Pending, failed, partial or superseded results cannot certify newer work. +A completed assessment can still have unresolved findings or failed persistence. +No new findings does not settle earlier blockers. + +Prefer incremental continuation. Let the Engine qualify checkpoints and report `full`, `incremental` or `reused`. +Do not add `--full` merely because notes changed, findings remain open, or the review precedes a PR. +Use it for a user-requested fresh assessment or when the previous assessment was incomplete. +Keep base, intended scope and requested effort stable when appropriate. Refresh context truthfully. +If the Engine cannot reuse evidence, report its actual fallback or missing coverage. +Do not fabricate checkpoints or suppress meaningful policy/instruction changes to obtain reuse. +Intent, reviewer selection, code scope, effort and fix attribution are separate decisions. +The Engine's intent judge owns eligibility. Do not infer it from the round number or price. ## Present the review result -After reading the completed result, explain each finding as **practical impact → assessment -using the code and coding-session context → your decision and recommended action**. -Credit Qodo naturally once for the concerns its review surfaced. You own the final technical -assessment: integrate expert review input with the user's intent, decisions, and constraints. -Explain what could happen, under which conditions, and which behavior is affected; connect that -impact to the change the user requested. Do not invent production conditions or affected users. -For example: “Qodo identified [risk]. Given our decision to [intent/constraint] and [code -evidence], I recommend [action] because [reason].” Adapt the wording to the actual evidence. - -Keep each issue's explanation coherent, cite supporting code, and preserve its reference and -reported category/level separately from your recommendation. Group overlapping findings only -when all references remain visible and individually selectable. Use short impact-based titles -or lists when useful; no branded headings, emoji banners, slogans, footers, or repeated summaries. -Report only known counts and coverage. Lead with material skipped/failed reviewers or incomplete -coverage; zero findings alone is not a clean verdict. A complete review with no findings can be -one sentence. For gated/failed runs, report the actual limitation rather than a completed result. +Credit Qodo naturally once for the concerns its review surfaced. +Explain each material finding as practical impact → assessment against code and session context → recommended action. +State the triggering condition and affected behavior. Cite supporting code. +Preserve reported category/level separately from your recommendation. +Group duplicates only when every finding reference remains visible and individually selectable. +Keep the tone factual. Do not turn an unsupported finding into a broad judgment about Qodo. + +Lead with material coverage failures or missing evidence. +Separate new findings, earlier open backlog and settled findings so old work does not appear newly discovered. +A complete review with no findings can take one sentence. +Use no branded headings, banners or repeated summaries. Do not call zero findings alone clean. ## Act on the findings -Independently evaluate every finding and own its disposition and rationale: **fix** a supported -issue (your fix may differ from Qodo's suggestion), **dismiss** an unsupported concern with code -evidence, or **investigate** uncertainty by naming the check needed. A session decision supports -dismissal only when the code enforces its assumptions. Keep the tone collaborative and factual; -do not routinely qualify Qodo's capability or turn a wrong finding into a broader judgment. -Your technical recommendation does not grant permission; apply the user's existing scope below. - -**Report-only.** For an explicit request to review without changes, return the assessment and stop; -do not solicit edit approval. - -**Missing edit authority.** If the intended fix scope is ambiguous, use the assessment above for every finding, keeping its -`[category/level]` and your recommendation, then ask **in a single prompt** which findings to apply. Use whatever the -host gives you: a multi-select if it has one (Claude Code's `AskUserQuestion`, say), otherwise a -numbered list and "reply with the numbers to apply". One prompt either way — don't ask per finding. -**Nothing is pre-selected.** Mark which ones you recommend, but the user must actively choose: this -prompt is the last thing standing between a finding and an edit, so a bare Enter must apply nothing. -Apply only what the user picks (edit as normal, matching the surrounding style); report the rest as -skipped with your reason. Do not edit any code before the user has chosen. - -**Authorized fixes.** `autofix`, an explicit request to fix findings, or existing implementation -authority covering the necessary correction permits fixes within that scope. State the assessment -and apply supported fixes without asking again. A review-only request grants no edit authority; -ask once if the intended scope is ambiguous. Preserve narrower user constraints. Fix authority -does not authorize stored dismissals, pushes, or unrelated changes. Report applied and skipped fixes. - -When the user explicitly authorizes declining a local finding, follow -[Record local triage](references/local-triage.md) to persist the decision. A conversational -"skip" alone is not a stored dismissal and must not be reported as one. -On MCP, use the live `pr-review-dismiss` schema with finding IDs and `local_review_id` from that completed review, an authorized reason and explanation, and a stable `idempotency_key` for the batch; read back each stored outcome. The reference's CLI commands apply only to the CLI path. - -After a batch of authorized fixes, verify and re-review changed work using the lifecycle policy above. -Assess outstanding findings and coverage before calling the result clean; stop an unproductive loop. -Commit/push per the user's workflow — ask before pushing unless they've told you to. - -## Recover a review - -For an accepted async run, collect by operation ID. On a status transport error, retry once after the returned delay (or 15 seconds). -If collection still fails, preserve the ID and report the gap; never resubmit just to poll. On a terminal failure, correct a -recoverable cause and retry once with the same mode and context. Stop on entitlement, auth, permission, rate-limit, or further failure; report expired results and coverage gaps. - -On `repo_not_connected`, `MT-REPO-NO-CREDENTIAL`, or “could not obtain repository credentials”, inspect `origin` without exposing URL credentials; an SSH alias may differ from the connected host. -Use a known exact repository `full_name` (self-hosted names may include a host); Codebase Wisdom suggestions do not prove connectivity. -Confirm `qodo review --help` supports `--repo`. If automatic retries are forbidden, stop and get explicit user approval for the corrected command. -Retry the original submission once with `--repo <full_name>`, preserving all other flags; collect a new async operation ID if applicable. -If the identity is uncertain or the retry fails, stop and report; ask an admin to check Git integration rather than assert disconnection. - -For connected CLI execution, keep the process alive throughout the review; a killed client can -cause server cancellation after a short grace period. If the host cannot sustain it, use async -instead of repeated timeouts. Use [connected progress](references/connected-progress.md) to -background a connected run while retaining status. - -**Concurrent reviews can complete independently.** For the same owner/repository/branch, only the -newest checkpoint run can publish finding updates; an older result may report `superseded`. - -Distinguish a killed client, server cancellation after connection loss, a missing `task.done` -after a dropped stream, and a backend `review failed: <detail>` response. Read the actual -failure and retained-result hint before choosing recovery; do not infer a size or complexity -limit from a connection failure. - -For the first three, collect any retained result using the CLI's recovery hint before submitting again. -If the run is confirmed canceled or unrecoverable, retry at most once with uninterrupted execution -and the same selected depth/context. A pending run is not a reason to restart. Further failure means -reporting incomplete review, not looping, dropping context or downgrading depth to obtain a result. - -## If the run is gated: closed preview - -`qodo review` is currently in **closed preview** — the server rejects runs from organizations that -aren't enrolled. A gated run exits non-zero with a stable machine-readable error: `--json` emits -`{"error": {"code": "closed_preview", "message": ..., "hint": ...}}`; without `--json` the same -message and hint print as prose. - -On `closed_preview`: - -1. **Surface the `message` and `hint` to the user unchanged** (don't paraphrase or truncate; - the `--json` payload carries them verbatim, while the CLI's prose output strips terminal - control characters), then -2. **STOP.** The gate is an entitlement, not a transient fault — retrying, backing off, watching, - or looping **cannot** succeed until the user's organization is enrolled. Do not re-run - `qodo review` unless the user says enrollment happened (after enrollment, access activates - within ~10 minutes; no re-login needed). - -Only the review itself is gated — auth (`qodo read whoami`) and the other qodo commands are unaffected. +Independently assess each finding: fix a supported issue, recommend dismissal with evidence, or investigate uncertainty. +A session decision supports the assessment only when the code enforces its assumptions. +Your recommendation does not grant authority. + +- **Report-only:** assess and stop. Do not edit or solicit permission to turn the task into implementation. +- **Authorized implementation/fixes:** batch supported corrections within the existing scope without asking again. +- **Ambiguous edit scope:** present all findings and ask once which to apply. Preselect nothing. + +Keep uncertain and out-of-scope findings visible. +Do not expand the task with optional refactors merely to reduce the finding count. +Fix authority does not authorize stored dismissals, pushes or unrelated changes. +For explicitly authorized finding-status writes, read [local triage](references/local-triage.md) and verify each stored outcome. +A conversational skip is not a stored dismissal. Do not manually mark a fix merely because the quote disappeared. + +After authorized fixes, run relevant checks and review changed work when useful. +Describe actual new behavior in `recent_work`, even during a fix loop. +Do not force fast or deep merely to control routing. + +## Stop and hand off + +Another assessment needs a concrete reason: + +- Changed code awaiting review or meaningful new evidence. +- Missing required final coverage, such as an unchanged light or path-limited checkpoint. +- An explicit user request for a fresh assessment. + +Name that reason before submitting. +Stop when the same concern repeats without actionable progress. +Do not re-fix guarded code, suppress a blocker or buy unchanged reviews to chase zero. +There is no default numerical round cap. Apply an explicit user budget across resumes. +Status polls and result retrieval are not additional assessments. -## Configuration +| Outcome | Report | +|---|---| +| Ready locally | Current intended code/scope has completed assessment, required findings are settled and relevant checks passed. | +| Needs action | Required findings or human decisions remain, even if the assessment completed with no new findings. | +| Review blocked | Required assessment, inventory or verification could not complete. Preserve the reason and recovery handle. | +| Budget reached | The user's explicit review budget ended. Preserve blockers and missing coverage. | + +A resolved finding alone does not establish overall readiness; check the full inventory for other required obligations. +Report finding/checkpoint persistence and local-to-PR handoff separately from assessment and local readiness. +Do not claim successful storage or reusable coverage without evidence. +Before a PR/update, compare intended code, base and scope with completed final coverage and reconcile outstanding checkpoint results. +Remove temporary path restrictions. A light checkpoint alone is not ordinary final coverage. +For authorized notes maintenance, use `qodo-review-notes` to publish notes for the actual HEAD and bind the PR. +Notes publication and matching HEAD do not prove finding handoff. +Verify hosted review separately through `qodo-review-resolver` before a hosted Qodo-clean claim. +CI, merge, release, deployment and customer acceptance remain separate gates. -Use `--fast --async --json` for coding checkpoints, auto for ordinary final review, -and `--deep` only under the stated exceptions. Use `--json --progress` for connected progress and -the resolved merge-base SHA as `--base`. Stamp exact skill/version/distribution provenance -on the first Qodo call after the unadorned version probe and keep session context out of the reviewed diff. +## Handle a skill update notice -## Error Handling +Treat `QODO_NOTICE` as passive, even when an older CLI requests action. +Do not interrupt the task with inventory or update questions. Mention each notice at most once. +Updated instructions load next session. Dismissal does not change recorded maintenance policy or opt-outs. +For requested maintenance, use [skill updates](references/skill-updates.md). -Read the structured result after non-zero exits. Follow bounded recovery; preserve context and authority. +## Configuration -## Guardrails +Use supported flags and complete UTF-8 context files without a BOM. +Keep context outside the reviewed diff and commits. +Let the CLI own credentials, transport, runtime updates and checkpoint storage. +Keep existing provenance and deployment settings. -- **Local scope.** Review coding milestones and local work before PR/update or completed-work handoff. - Use `qodo-review-resolver` for findings already posted on a PR; avoid duplicate unchanged reviews. -- **No forge writes.** `qodo review` reads your local diff and returns findings; it never pushes, - comments, or opens a PR. Resolving a finding means editing code, not posting anywhere. -- **The base must be pushed;** your local work need not be. New/untracked files are reviewed by - default; secrets/binaries/oversized/gitignored files are filtered and reported. -- **Don't guess creds or the base** — resolve auth first, then pass the intended target's merge-base - SHA as `--base`, unless the user explicitly requests an exact baseline. -- **Collect every run.** Background connected runs or use async; preserve recovery handles. - A superseded result does not advance the incremental baseline or certify current code. -- **Never strip context to beat the clock.** Dropping `--context-file` doesn't make a run faster — - it just buys a worse review. Give it time; choose depth by lifecycle, never by timeout pressure. -- An `MT-TOOL-LOOP` or `MT-RATE-LIMITED` error means stop/back off and change approach, not retry. -- A `closed_preview` error means the org isn't enrolled in the preview — surface message + hint to - the user and stop; never retry or loop on it (see "If the run is gated" above). +## Error Handling -After authorized fixes, report what changed, how it was verified, and what remains with reasons. +Read structured errors even after a nonzero exit. +Follow [bounded recovery](references/cli-execution.md#recover-a-review), not another automatic assessment loop. +Preserve context, selected effort and authority. +Stop on permission/auth/entitlement failures and tool-loop or rate-limit errors. +For `closed_preview`, show the returned message and hint unchanged and stop. +A new run requires confirmation that enrollment occurred. +Do not switch accounts/deployments, strip context or lower effort to obtain a passing result.
Full technical diff · 3 changed fields
changed /description
"Review local changes with Qodo during substantive coding milestones and before a PR or completed-work handoff. Use light background checkpoints while coding, collect and assess findings with session context, and run a final review before handing off. Also use for \"review my local diff\", \"pre-PR review\", or \"run qodo review\". Use qodo-review-resolver for findings already posted on a PR."
"Review local changes with Qodo after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch authorized fixes and stop unproductive review loops. Also use for \"review my local diff\", \"pre-PR review\", or \"run qodo review\". Use qodo-review-resolver for findings already posted on a PR."
changed /included_files
[
{
"relative_path": "agents/openai.yaml",
"size_in_bytes": 343
},
{
"relative_path": "references/connected-progress.md",
"size_in_bytes": 2293
},
{
"relative_path": "references/context-delivery.md",
"size_in_bytes": 1954
},
{
"relative_path": "references/finding-results.md",
"size_in_bytes": 3661
},
{
"relative_path": "references/local-triage.md",
"size_in_bytes": 2896
},
{
"relative_path": "references/review-turn-context.md",
"size_in_bytes": 4242
},
{
"relative_path": "references/skill-updates.md",
"size_in_bytes": 1685
},
{
"relative_path": "references/windows-launcher.md",
"size_in_bytes": 1203
},
{
"relative_path": "references/windows-shells.md",
"size_in_bytes": 917
}
][
{
"relative_path": "agents/openai.yaml",
"size_in_bytes": 343
},
{
"relative_path": "references/cli-execution.md",
"size_in_bytes": 9259
},
{
"relative_path": "references/connected-progress.md",
"size_in_bytes": 4094
},
{
"relative_path": "references/context-delivery.md",
"size_in_bytes": 2016
},
{
"relative_path": "references/finding-results.md",
"size_in_bytes": 5482
},
{
"relative_path": "references/local-triage.md",
"size_in_bytes": 4780
},
{
"relative_path": "references/mcp-review.md",
"size_in_bytes": 2701
},
{
"relative_path": "references/review-turn-context.md",
"size_in_bytes": 8811
},
{
"relative_path": "references/skill-updates.md",
"size_in_bytes": 1685
},
{
"relative_path": "references/windows-launcher.md",
"size_in_bytes": 1203
},
{
"relative_path": "references/windows-shells.md",
"size_in_bytes": 917
}
]changed /skill_md_contents
"---\nname: qodo-review\ndescription: Review local changes with Qodo during substantive coding milestones and before a PR or completed-work handoff. Use light background checkpoints while coding, collect and assess findings with session context, and run a final review before handing off. Also use for \"review my local diff\", \"pre-PR review\", or \"run qodo review\". Use qodo-review-resolver for findings already posted on a PR.\nowner: Qodo\nmetadata:\n vendor: qodo\n version: \"1.10.15\"\n recommended: \"true\"\n package: \"qodo\"\n distribution: \"marketplace\"\n instruction_mode: \"embedded\"\n---\n\n# Local Review\n\n## Description\n\nReview **local changes during coding and before handing off completed work**. `qodo review` sends your diff, new/untracked files and coding-session context to Qodo. Evaluate its structured findings and apply authorized fixes. Only the base commit must be on the remote; the command never pushes or creates a PR.\n\nUse this skill for local changes, including unpushed work on an existing PR. Use `qodo-review-resolver` to work on findings from the PR's remote review; do not duplicate that review for an unchanged pushed snapshot.\n\n## Prerequisites\n\n- An authenticated Qodo CLI is available, or a connected QAR MCP server and a tested local input collector are available; review capability is enabled.\n- The comparison base exists on the remote; local changes and context need not be pushed.\n- The coding-session context and any ticket or design references are ready to attach.\n\n## Choose when and how deeply to review\n\n| Situation | Selection |\n|---|---|\n| A coherent milestone during substantive coding | `--fast --async`: light checkpoint; continue useful coding and collect the result. |\n| Ordinary final review before opening/updating a PR or handing off completed work | Omit both depth flags: auto. Collect and assess the result before claiming review completion. |\n| User intent calls for unusually thorough scrutiny, or a known high blast radius warrants it | `--deep`, with a brief reason tied to the request or affected behavior. |\n\nAutomatic coding checkpoints always use `--fast`. A deliberate deep review can happen earlier when\none of the exceptions above applies. A request such as \"examine subtle races thoroughly\" can justify\nit without the word \"deep\"; generic \"review\" or \"double-check\" does not. Identify concrete impact,\nsuch as shared authorization, a destructive migration, or a contract used by multiple services.\nDiff size, session length, PR readiness, or a security-related filename alone do not justify deep.\n\nWith **no flag**, the CLI omits depth and the reviewer/deployment selects it. Auto can select deep;\nit is not guaranteed standard and does not impose a spending cap. There is no `--standard` flag.\n`--fast` and `--deep` are mutually exclusive; depth is selected anew for each invocation.\n\n## Checkpoints and final handoff\n\n- Review a completed, testable slice when its feedback can guide the remaining work. Do not review\n unfinished exploration, every edit, trivial changes automatically, or simply because time passed.\n Respect the user's review scope and budget. A pause for a question or approval is not a final handoff.\n- Keep at most one automatic checkpoint active per task. Retain its operation ID, submitted scope\n and snapshot/context association in the task's existing state. Poll status at natural pauses while\n doing useful work; do not launch another review to check progress or re-review unchanged inputs.\n- Collect every submitted result within its retention window. Recheck findings against current code\n before acting: the working tree may have changed. A superseded result cannot certify newer work.\n Use the existing CLI lifecycle; no separate sub-agent or scheduler is required.\n- Before final review, collect the outstanding checkpoint and reconcile its findings. Review the\n full intended change with auto, or justified deep, rather than handing off on a light checkpoint.\n Remove temporary path restrictions that would leave part of the intended change unreviewed.\n If the same snapshot already has completed final coverage with compatible context, use that result.\n- Batch authorized fixes, verify them, then re-review changed work. Keep `--fast` for checkpoint\n fixes; retain the requested auto or justified deep mode for final-review fixes. Let the engine\n determine incremental eligibility; auto may route differently on each pass. Do not manually switch\n final fixes to `--fast` or force `--deep` just to pin auto routing. If work returns to substantial\n implementation, resume light checkpoints and establish final coverage again before handoff.\n- If another pass repeats the same concern without actionable progress, stop the automatic loop and\n report the remaining issue and needed decision/check. Do not buy repeated passes to chase zero.\n Pending, failed, partial or superseded review is not clean; surface remaining findings and coverage.\n\n## Prepare a PR handoff\n\nDuring coding, commit only changes made for this task before every local review, including the first fast checkpoint and reviews of fixes. Follow the user's commit policy; leave pre-existing or unrelated edits untouched. A local commit is sufficient; pushing is not required.\nRetain the submitted HEAD (`git rev-parse HEAD`) with each review's operation ID. Before opening or updating a PR, compare its intended head with the completed final review's SHA; if they differ, review the intended head first. Commit and review later edits again, preserving earlier reviewed commits in branch history so the handoff can trace findings to their original code.\nFor review-only tasks, when commits are not authorized, or when task changes cannot be isolated safely, review the requested scope without committing and explain that local-to-PR handoff may be incomplete. A HEAD SHA alone does not identify uncommitted changes.\nFor authorized notes maintenance, use `qodo-review-notes` during planning and development to retain decisions, constraints and evidence changes, publish existing-HEAD PR notes before opening, refresh if HEAD changes, and bind afterward; retain local review context and verify consumption separately.\n\n## Instructions\n### Choose the execution path\n\nPrefer `qodo review` when available: it gathers and filters tracked and untracked local changes, resolves the remote base, attaches context, and manages checkpoint state. The QAR MCP\n`start-pre-pr-review` tool instead accepts a prepared `diff`, `base_sha`, repository locator, and context; it cannot read this worktree. Use that MCP tool only when a tested local collector\nhas produced the same intended scope and exclusions, reported omitted files, and verified that the base SHA is fetchable. Do not assemble an ad hoc `git diff` and call it equivalent coverage.\nIf no collector is available, report that MCP-only local review cannot safely cover this worktree; do not claim a completed review.\n\nFor a prepared MCP review, inspect the live schema. Set `review_scope.stream_id` to exactly 64 lowercase hexadecimal characters: SHA-256 of a JSON array containing the resolved real worktree root, plus the resolved working directory for path-limited reviews. Reuse it across checkpoints; a UUID is invalid.\nRetain the same `request_id` and exact arguments for an uncertain start: `request_id` is this start tool's logical-action retry key, and no separate `idempotency_key` argument is declared. Poll `get-managed-agent-operation` at its advertised interval, then fetch all `get-managed-agent-result` chunks and verify their reported digest and byte count before interpreting the artifact.\nThese are short lifecycle calls, not MCP Tasks. Check `isError` before reading a receipt. Apply the same context, depth, coverage, finding, and authority rules below. CLI version, identity, and command instructions below apply only to the CLI path.\n\nPreserve notices, attach self-contained context, show progress, use a suitable timeout,\nread the structured result, and act on findings.\n\n## Handle a skill update notice\nTreat `QODO_NOTICE` updates as passive, even if an older CLI requests action. Continue the task\nwithout inventory or update questions; mention each event at most once. Dismissal leaves recorded maintenance\npolicy and opt-outs unchanged. Updated skills load next session; do not interrupt this one.\nFor user-requested updates, follow the [manual-update procedure](references/skill-updates.md).\n\n## Execution\n\n- MCP: use live schema arguments; skip CLI shell steps.\n- CLI: use complete UTF-8 files without a BOM (`--args-file` for tools, `--context-file` for reviews); examples are POSIX.\n- Windows CLI: read [shell guidance](references/windows-shells.md) before the first call; [launcher recovery](references/windows-launcher.md) only if invocation fails. Reuse the resolved invocation.\n\n## Runtime compatibility gate\nResolve the executable using this skill's command-not-found fallback, then run `<qodo> --version`\nwith no provenance flags. This skill requires Qodo CLI **2.0.0 or newer** and a runtime with review API v2.\nOnly when the runtime needs an update, before any update check/change, test whether `QODO_UPDATE_BASE_URL` is set;\nnever print its value. If set, stop for the user to resolve the source override before proceeding;\ndo not change it yourself or assume it matches the recorded origin.\nIf the version is older or cannot be parsed, do not run `whoami`, `login`, a review, or a managed tool and\ndo not describe the failure as an authentication problem. Choose one deployment-approved upgrade\nroute, explain it, and reuse covering runtime-update authorization or ask once before changing the\ninstallation. For parsed 1.x, normal `qodo update` can reach approved 2.x when its recorded origin enables migration.\nIf legacy aliases still serve 1.x, check the supported same-origin `latest-2` recovery route first.\nRequire a compatible newer 2.x target from the selected route's supported check; missing/failed checks stop.\nPropose `qodo update --channel latest-2` only for that verified recovery route; never assume activation.\nThis exception covers only deployment-approved 1.x to stable 2.x; it does not authorize other\nmajor migrations or change the existing automatic-update policy for future majors.\nFor every route, preserve origin, explicit version choices and update holds; never substitute a channel for an exact version.\nFor an unparseable runtime or no supported updater, use a checksum-pinned installer supplied by\nQodo or the organization with covering installation authorization; never switch to public service or invent a digest.\nMake one approved runtime attempt, then rerun the unadorned version probe and continue only when it satisfies the minimum. On denial, failure or continued\nincompatibility, stop with skill and user files unchanged; do not retry through another route.\n\n## Quick start\nYou just wrote the code, so you hold the one input the reviewer can't get anywhere else: **why**.\nAttach it on every run — write the session context first, then review:\nBefore each new submission, read [Session context](references/review-turn-context.md) and refresh `recent_work`.\nExamples use `notes`; check `qodo review --help`. If it advertises only `summary`, use that field\nfor the same narrative, keeping `decisions` and `recent_work` unchanged.\n\n```sh\nqodo --version\nqodo read whoami --json --skill qodo-review --skill-version 1.10.15 --distribution marketplace --host codex\n```\nSee [illustrative CLI examples](references/review-turn-context.md#cli-examples) for context, base and depth choices.\n\n\nYou can also keep `.qodo/session-context.json` (same JSON shape) updated at the repo root — it is auto-attached to every run, so even a bare `qodo review` carries your context. An explicit\n`--context-file` overrides it; the file itself is never part of the reviewed diff. Don't commit it\n(add `.qodo/` to `.gitignore` or `.git/info/exclude`).\nAdd `--json` to anything you parse. For connected execution, allow a multi-minute timeout or\nbackground the process; async submission and status collection are separate short calls.\n**Confirm the exact flags with `qodo review --help`** (offline) — the examples here are illustrative.\n\n## Choose execution for the selected review\n\nUse `--async` for coding checkpoints: submit, continue useful work, then collect with `review status`.\nFor a final review, async is also valid, but collect and assess it before the handoff. If live progress\nis useful, read [connected progress](references/connected-progress.md) and use `--json --progress`\nwith a host-native background process. Never combine `--progress` with `--async`.\nA review can take minutes; keep a connected process alive or use async so client exit cannot cancel it.\nIf async is unavailable in the installed CLI, keep the selected depth and use the connected fallback.\n\nFor connected progress, the canonical execution rules are:\n\n- Attach context through a file; stdin heredocs are unsuitable for background execution.\n- Use a unique per-run temporary directory. Separate the single result JSON on stdout from NDJSON\n progress on stderr. Poll the growing progress file through the host's nonblocking process tools;\n never run a foreground `tail` that blocks the agent until completion.\n- Relay short status messages, not raw JSON or model output. Translate events by `kind`:\n `cli.status` gives a readable message; `tool.activity` gives tool name and outcome;\n `task.delta` and unknown kinds are occasional generic heartbeats, not one message per event.\n- For `qar.client.reconnecting`, relay attempt/delay and structured close/error codes when present.\n `qar.client.reconnected` means transport opened; `resubscribeAttempts` counts reattached live tasks.\n `qar.client.reconnect_failed` signals exhausted retries, not the final error explanation.\n- On `task.done`, inspect `payload.status`; on failure/cancellation or `error`, stop progress relay\n but keep waiting for process exit. Always read the result envelope, including on nonzero exit:\n actionable messages/hints such as `closed_preview` may appear only there. Progress is not findings.\n- Capture the process exit status, reap the child and disarm its PID before parsing. On interruption,\n terminate and reap the active child. Clean up only that run's directory on exit/failure/interruption;\n never reuse or remove a shared `.qodo/review.*` path.\n- If background progress is unavailable, run foreground with a multi-minute timeout, preserving\n selected depth and context. Missing progress is not a reason to fail review or downgrade depth.\n\n**`qodo: command not found`?** On POSIX retry `\"${QODO_HOME:-$HOME/.qodo}/bin/qodo\"`;\non Windows follow the linked guide. Keep the resolved invocation; report unusable launchers.\nFor missing installs, obtain Qodo's or the administrator's checksum-pinned installer; never invent a digest or pipe scripts into a shell.\n\n**Sandbox auth diagnostic.** Missing credentials can mean inaccessible keychain access. When that\nis plausible, request one exact read-only `qodo read whoami` retry through the host's approval\nflow before recommending login. Stop on denial; that approval covers no other command. Reuse a\nsuccessful check in the same executable/workspace/deployment and execution context; request each\nrequired host approval. Network, TLS, service, and explicit authorization failures retain their\nown diagnosis, not a login recommendation or an automatic sandbox bypass.\n\n## Submit and collect with `--async`\n\nCheck support with `qodo review --help`. The following example submits a coding checkpoint. For final\nreview omit `--fast`; add `--deep` only under the selection policy above. Attach the same context in\nall modes. Shell snippets illustrate the CLI protocol; use the host's own nonblocking wait mechanism.\n\n`--async` removes the connection from the critical path. It submits the review over HTTP, prints an\n**operation id**, and exits 0 immediately. The run continues server-side whether or not your process\nis alive; you collect the result later with `qodo review status <operation-id>`.\n\n```\ncommand -v jq >/dev/null 2>&1 || { printf '%s\\n' 'This async recipe requires jq; install it or use the live qodo review flow.' >&2; exit 1; }\nQODO_REVIEW_CONTEXT=\"${QODO_REVIEW_CONTEXT:-.qodo/session-context.json}\"\n[ -f \"$QODO_REVIEW_CONTEXT\" ] || { printf '%s\\n' \"Write the required review context to $QODO_REVIEW_CONTEXT (or set QODO_REVIEW_CONTEXT to its path).\" >&2; exit 1; }\nQODO_REVIEW_BASE=\"$(git merge-base HEAD origin/main)\" || { printf '%s\\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # substitute the intended target\nif ! submission=\"$(qodo review --base \"$QODO_REVIEW_BASE\" --context-file \"$QODO_REVIEW_CONTEXT\" --async --json --fast)\"; then printf '%s\\n' \"$submission\" >&2; exit 1; fi\nif ! id=\"$(printf '%s\\n' \"$submission\" | jq -er '.operation_id | select(type == \"string\" and length > 0)')\"; then printf '%s\\n' \"$submission\" >&2; exit 1; fi\nqodo review status \"$id\" --json # collect it\n```\n\nPoll the existing operation until it finishes; do useful work between status checks. Submission\nexit 0 means accepted, not reviewed. Collection uses these exit codes; read any returned retry delay:\n\n| Exit | Meaning | Do |\n|---|---|---|\n| `0` | Finished. Findings rendered — **identical** output to a live run (`{findings, meta}` under `--json`). | Act on the findings as usual. |\n| `2` | Still running or polling throttled. | Respect `retry_after` when present, then poll the same ID. |\n| `1` | Failed, canceled, expired, or no such operation. Read the `error` envelope. | Follow the bounded recovery below; never assume clean. |\n\n```\n# This collection attempt returns failures to the host for classification under Recover a review.\n# On nonzero exit, preserve the operation ID and emitted error; apply bounded recovery there.\nQODO_REVIEW_TMP=\"$(mktemp -d \"${TMPDIR:-/tmp}/qodo-review.XXXXXX\")\"\ncleanup_qodo_review() { [ -n \"${QODO_REVIEW_TMP:-}\" ] && [ -d \"$QODO_REVIEW_TMP\" ] && rm -r -- \"$QODO_REVIEW_TMP\"; }\ntrap cleanup_qodo_review EXIT; trap 'exit 130' INT; trap 'exit 143' TERM\nwhile :; do\n status=0; qodo review status \"$id\" --json > \"$QODO_REVIEW_TMP/result.json\" || status=$?\n case \"$status\" in\n 0) cat \"$QODO_REVIEW_TMP/result.json\" || exit 1; break ;;\n 2) delay=$(jq -r 'if (.retry_after | type) == \"number\" and .retry_after > 0 then .retry_after else 15 end' \"$QODO_REVIEW_TMP/result.json\") || exit 1\n sleep \"$delay\" ;;\n *) cat \"$QODO_REVIEW_TMP/result.json\" >&2; exit \"$status\" ;;\n esac\ndone\n```\n\n**What it costs — know these before you choose it:**\n\n- **No streaming progress.** There are no progress events on this path — the run isn't attached to\n your process — so `--async` and `--progress` are rejected together rather than emitting a stream\n that never arrives. There is no intermediate status beyond \"still running\". If the user is\n watching and wants to see life, use the [connected progress](references/connected-progress.md) recipe instead.\n- **No human-in-the-loop.** This surface runs deterministic agents only; a review that asks for\n input fails instead of waiting. (`qodo review status` says so and tells you to re-run without\n `--async`.)\n- **The result is kept for 1 hour** after the review finishes, then it is discarded. Collect it\n inside that window. Past it, `qodo review status` cannot tell \"expired\" from \"never existed\" or\n \"belongs to someone else\" — the runtime answers all three identically, on purpose — so it reports\n all of them. Report the missing review evidence before deciding whether a new run is needed.\n- **Do not assume a new submission is free or deduplicated.** Use `review status` to collect an\n accepted run. If admission is uncertain, follow the CLI's returned recovery command (on versions\n that support it, `--async --retry-submission <id>`); never substitute a fresh `qodo review` to poll.\n Preserve the retained request during recovery instead of gathering the changing working tree again.\n- **Retain the operation id.** It identifies the accepted run; a submission-recovery ID has a different\n purpose. Do not throw away either handle before collecting or reconciling its outcome.\n\n**The operation id is not the `trace` id.** `qodo` prints a `trace <id>` line on failures — that's\nan OpenTelemetry id for support to diagnose a run with, and it cannot fetch anything. The\n`operation_id` from `--async` is the resumable handle. Don't pass one where the other is wanted.\n\n## Preflight\n\n1. **Auth and catalog.** Run `qodo read whoami` unless a successful check still covers this\n execution context. After the sandbox diagnostic when applicable, only explicit missing credentials\n call for login: preserve the organization's exact login command/endpoint, never guess or switch\n a customer deployment to Cloud. `No tool catalog cached` is not proof of missing credentials;\n refresh once with `qodo tools --refresh` and retry the check. Other failures retain their error\n and stop this workflow. After identity succeeds, an unknown managed command permits one catalog\n refresh and schema recheck. If still absent or `tool_unavailable`, report the missing capability;\n do not repeat login or refresh.\n An unknown built-in `qodo review` needs runtime recovery, not login or catalog refresh.\n2. **Resolve the base.** Select the intended target (`origin/main` unless the change targets another\n branch). Fetch that target before reviewing current remote history; if unavailable or deliberately\n offline/pinned, disclose that the review uses locally fetched history rather than claim it is current.\n Compute `git merge-base HEAD <target-ref>` and pass that SHA as `--base` on every\n submission, including checkpoints and connected runs. This also protects older CLIs whose\n default compares the target tip. An explicit `--base` is exact; passing the target branch itself\n can misattribute newer target-only changes. Honor a user-requested exact comparison.\n If no common ancestor is available, fetch missing history or report the blocker; never fall\n back silently to the target tip. The base must be pushed; review authority does not allow a push.\n Local edits and untracked files are included without committing or pushing them.\n3. **Write your context.** Capture actual choices and natural-language ownership in `decisions`,\n review context/evidence in `notes`, and this round's work in `recent_work`. Refresh facts and\n verification results before review. Follow the SessionContext guidance below; leave unknown\n ownership or rationale explicit.\n\n## What gets reviewed\n\n`qodo review` gathers, all client-side:\n\n- The **tracked diff** vs the base, plus **new/untracked files** (secrets, binaries, oversized,\n and gitignored files are filtered out and reported — never silently dropped).\n- The **branch name**, **HEAD commit**, and a **description** synthesized from your commit messages.\n- Any **ticket refs** and **session context** you attach (below).\n\n`--json` returns each finding once in `findings`; `finding_state` buckets reference IDs. Assess `.introduced`\n**and** `.still_open`; report detected fixes in `.resolved` and stored dismissals in `.dismissed`. Older buckets contain full objects.\nDefault fields: `id`, `title`, `description`, `category`, `action_level`, `attribution_status`, `git_sha`,\n`location`, `evidence.citations`. Inspect the code location and evidence; preserve the original finding ID.\n`--extended` adds stored supporting detail; it changes neither review depth nor execution.\nLocal `review_agent_comment` is stored reviewer feedback in both views; reuse carries it forward without new execution. Read it alongside findings and coverage.\nFor authorized status writes, group IDs by `meta.local_review_ids[id]`; report unavailable references.\nFix instructions and reviewer internals are excluded. See the [field guide](references/finding-results.md) for field details.\nIf `finding_state.complete` or `meta.coverage.complete` is false, report the incomplete coverage.\n`meta.analysis.mode` is `full`, `incremental`, or `reused`. Reused means the same reviewed snapshot\nand compatible context; earlier open findings remain open. The CLI privately saves the submitted patch.\nIt advances its checkpoint after collecting an eligible result, including via `review status`; failed or older completions cannot replace a newer checkpoint.\nKeep the same base, path scope, requested depth mode and context during a fix loop. Changed context, expired or\nunverifiable checkpoints, and unsupported deltas fall back to full review. Never fabricate a checkpoint.\nFor a deliberately fresh assessment use `--full` (confirm support with `--help`). It controls scope,\nnot depth; it is not needed on every fix. Changing the requested depth mode invalidates compatible\ncheckpoint coverage. Auto does not promise a fixed effective tier; rely on returned analysis/coverage.\nOlder engines omit these fields: use their findings and coverage without claiming reuse.\nPrefer `meta.run.passes` for actual outcomes; legacy `meta.reviewers` describes configured dimensions. Report failed/skipped components and missing metadata; reuse has no new execution.\n\n## Attach coding-session context\n\nUse `--ticket <full-url>` for fetchable ticket context; a bare key is only detected metadata.\nUse `.qodo/session-context.json` at the repo root for ambient context, or `--context-file <path>`\nto override it (`-` reads JSON from stdin). Capture context as it emerges and refresh before review:\n\n```json\n{\n \"decisions\": [\"The user selected optimistic locking to avoid contention.\"],\n \"notes\": \"src/orders.ts:updateOrder enforces the version check. Order tests passed; production contention was not tested.\",\n \"recent_work\": [\"Added optimistic locking; this round includes new behavior.\"]\n}\n```\n\n**Decisions:** Record actual choices and known rationale in natural language. Identify explicit\nuser requirements, user-selected/approved options, and coding-agent choices. A user-selected agent\nproposal is user-selected. Include a source/quote when useful;\nno fixed source tags are required. Leave unknown ownership/rationale explicit; never invent it.\nPut undecided proposals in notes.\n\n**Notes:** Include evidence that could change whether a concern is valid: expected behavior,\nscope, requirements/non-goals and relevant spec text; runtime/callers/reachability/input sources,\nconcurrency/time limits and where enforced; existing guards/exception handling/tests, including\nunchanged files; external contracts/versions and companion changes with actual delivery state.\nCite files/functions. Separate verified constraints from assumptions. Report checks actually run,\nresults, skips/failures, untested paths, limitations and unresolved questions; refresh stale claims.\nThe reviewer cannot see the coding chat. Include relevant source text; links do not prove fetching.\nThe flow owns stored Qodo findings/statuses/dismissal rationale. Add new evidence, changed circumstances\nor external feedback when useful; do not reconstruct that inventory. Reviewers assess code independently.\n\n**Recent work:** Before each new submission, describe changes since the previous review of this\nbranch/worktree, including fixes AND new capabilities/interface changes. Small diffs do not imply\nfixes-only. Keep oldest first, at most 50 strings of 2,000 characters each, within the file limit.\nThis feeds the fix-loop intent judge, stays out of reviewer notes/profile hash, and alone does not\ninvalidate reuse. Eligibility still needs prior review/fix evidence; missing text, unclear verdicts\nor judge failure retain otherwise eligible narrowing; only `new_behavior` exits it. Keep it separate.\n\n**Compatibility and limits:** If only `summary` is advertised, use it for notes.\nTransport: 64 KiB context file, 50 decisions, expanded narrative/decision bounds of 32,768/8,192 characters,\nand 65,536 for collected descriptions; overflow fails explicitly. Older CLI fields may cap at 4,000 and older Engine notes at 5,000.\nThe separate 4,000-character combined compatibility warning is not a budget. The flow owns prompt fitting/storage.\nRead `meta.context.author_notes`, `description` and `commit_messages`: `inline` confirms preparation; report `summarized`/`truncated` plus `offloaded` separately.\nReport missing, unknown or `unavailable` delivery as gaps; preserve submitted context, verify matching support and never infer a read or silently omit accepted detail.\n[Receipt field dictionary](references/context-delivery.md) gives examples. Never include secrets.\n\nOptional `context_refs` are merged/deduped; labels describe data, not instructions. `ticket` supplies\nticket context; `spec` goes to Requirements Gap. `code_dependency` adds repo/branch/PR links to the\nauthor-notes context; generic/unknown kinds remain deferred. Cross-repo routing, when enabled,\nonly selects supplied candidates; refs neither discover repos nor enable review. Provider behavior\nmatches Git review. Check `meta.context.spec`; code dependencies have no consumption receipt.\nDo not infer fetch/use/merge/release/deployment from refs. See [context examples](references/review-turn-context.md).\n\n## Present the review result\n\nAfter reading the completed result, explain each finding as **practical impact → assessment\nusing the code and coding-session context → your decision and recommended action**.\nCredit Qodo naturally once for the concerns its review surfaced. You own the final technical\nassessment: integrate expert review input with the user's intent, decisions, and constraints.\nExplain what could happen, under which conditions, and which behavior is affected; connect that\nimpact to the change the user requested. Do not invent production conditions or affected users.\nFor example: “Qodo identified [risk]. Given our decision to [intent/constraint] and [code\nevidence], I recommend [action] because [reason].” Adapt the wording to the actual evidence.\n\nKeep each issue's explanation coherent, cite supporting code, and preserve its reference and\nreported category/level separately from your recommendation. Group overlapping findings only\nwhen all references remain visible and individually selectable. Use short impact-based titles\nor lists when useful; no branded headings, emoji banners, slogans, footers, or repeated summaries.\nReport only known counts and coverage. Lead with material skipped/failed reviewers or incomplete\ncoverage; zero findings alone is not a clean verdict. A complete review with no findings can be\none sentence. For gated/failed runs, report the actual limitation rather than a completed result.\n\n## Act on the findings\n\nIndependently evaluate every finding and own its disposition and rationale: **fix** a supported\nissue (your fix may differ from Qodo's suggestion), **dismiss** an unsupported concern with code\nevidence, or **investigate** uncertainty by naming the check needed. A session decision supports\ndismissal only when the code enforces its assumptions. Keep the tone collaborative and factual;\ndo not routinely qualify Qodo's capability or turn a wrong finding into a broader judgment.\nYour technical recommendation does not grant permission; apply the user's existing scope below.\n\n**Report-only.** For an explicit request to review without changes, return the assessment and stop;\ndo not solicit edit approval.\n\n**Missing edit authority.** If the intended fix scope is ambiguous, use the assessment above for every finding, keeping its\n`[category/level]` and your recommendation, then ask **in a single prompt** which findings to apply. Use whatever the\nhost gives you: a multi-select if it has one (Claude Code's `AskUserQuestion`, say), otherwise a\nnumbered list and \"reply with the numbers to apply\". One prompt either way — don't ask per finding.\n**Nothing is pre-selected.** Mark which ones you recommend, but the user must actively choose: this\nprompt is the last thing standing between a finding and an edit, so a bare Enter must apply nothing.\nApply only what the user picks (edit as normal, matching the surrounding style); report the rest as\nskipped with your reason. Do not edit any code before the user has chosen.\n\n**Authorized fixes.** `autofix`, an explicit request to fix findings, or existing implementation\nauthority covering the necessary correction permits fixes within that scope. State the assessment\nand apply supported fixes without asking again. A review-only request grants no edit authority;\nask once if the intended scope is ambiguous. Preserve narrower user constraints. Fix authority\ndoes not authorize stored dismissals, pushes, or unrelated changes. Report applied and skipped fixes.\n\nWhen the user explicitly authorizes declining a local finding, follow\n[Record local triage](references/local-triage.md) to persist the decision. A conversational\n\"skip\" alone is not a stored dismissal and must not be reported as one.\nOn MCP, use the live `pr-review-dismiss` schema with finding IDs and `local_review_id` from that completed review, an authorized reason and explanation, and a stable `idempotency_key` for the batch; read back each stored outcome. The reference's CLI commands apply only to the CLI path.\n\nAfter a batch of authorized fixes, verify and re-review changed work using the lifecycle policy above.\nAssess outstanding findings and coverage before calling the result clean; stop an unproductive loop.\nCommit/push per the user's workflow — ask before pushing unless they've told you to.\n\n## Recover a review\n\nFor an accepted async run, collect by operation ID. On a status transport error, retry once after the returned delay (or 15 seconds).\nIf collection still fails, preserve the ID and report the gap; never resubmit just to poll. On a terminal failure, correct a\nrecoverable cause and retry once with the same mode and context. Stop on entitlement, auth, permission, rate-limit, or further failure; report expired results and coverage gaps.\n\nOn `repo_not_connected`, `MT-REPO-NO-CREDENTIAL`, or “could not obtain repository credentials”, inspect `origin` without exposing URL credentials; an SSH alias may differ from the connected host.\nUse a known exact repository `full_name` (self-hosted names may include a host); Codebase Wisdom suggestions do not prove connectivity.\nConfirm `qodo review --help` supports `--repo`. If automatic retries are forbidden, stop and get explicit user approval for the corrected command.\nRetry the original submission once with `--repo <full_name>`, preserving all other flags; collect a new async operation ID if applicable.\nIf the identity is uncertain or the retry fails, stop and report; ask an admin to check Git integration rather than assert disconnection.\n\nFor connected CLI execution, keep the process alive throughout the review; a killed client can\ncause server cancellation after a short grace period. If the host cannot sustain it, use async\ninstead of repeated timeouts. Use [connected progress](references/connected-progress.md) to\nbackground a connected run while retaining status.\n\n**Concurrent reviews can complete independently.** For the same owner/repository/branch, only the\nnewest checkpoint run can publish finding updates; an older result may report `superseded`.\n\nDistinguish a killed client, server cancellation after connection loss, a missing `task.done`\nafter a dropped stream, and a backend `review failed: <detail>` response. Read the actual\nfailure and retained-result hint before choosing recovery; do not infer a size or complexity\nlimit from a connection failure.\n\nFor the first three, collect any retained result using the CLI's recovery hint before submitting again.\nIf the run is confirmed canceled or unrecoverable, retry at most once with uninterrupted execution\nand the same selected depth/context. A pending run is not a reason to restart. Further failure means\nreporting incomplete review, not looping, dropping context or downgrading depth to obtain a result.\n\n## If the run is gated: closed preview\n\n`qodo review` is currently in **closed preview** — the server rejects runs from organizations that\naren't enrolled. A gated run exits non-zero with a stable machine-readable error: `--json` emits\n`{\"error\": {\"code\": \"closed_preview\", \"message\": ..., \"hint\": ...}}`; without `--json` the same\nmessage and hint print as prose.\n\nOn `closed_preview`:\n\n1. **Surface the `message` and `hint` to the user unchanged** (don't paraphrase or truncate;\n the `--json` payload carries them verbatim, while the CLI's prose output strips terminal\n control characters), then\n2. **STOP.** The gate is an entitlement, not a transient fault — retrying, backing off, watching,\n or looping **cannot** succeed until the user's organization is enrolled. Do not re-run\n `qodo review` unless the user says enrollment happened (after enrollment, access activates\n within ~10 minutes; no re-login needed).\n\nOnly the review itself is gated — auth (`qodo read whoami`) and the other qodo commands are unaffected.\n\n## Configuration\n\nUse `--fast --async --json` for coding checkpoints, auto for ordinary final review,\nand `--deep` only under the stated exceptions. Use `--json --progress` for connected progress and\nthe resolved merge-base SHA as `--base`. Stamp exact skill/version/distribution provenance\non the first Qodo call after the unadorned version probe and keep session context out of the reviewed diff.\n\n## Error Handling\n\nRead the structured result after non-zero exits. Follow bounded recovery; preserve context and authority.\n\n## Guardrails\n\n- **Local scope.** Review coding milestones and local work before PR/update or completed-work handoff.\n Use `qodo-review-resolver` for findings already posted on a PR; avoid duplicate unchanged reviews.\n- **No forge writes.** `qodo review` reads your local diff and returns findings; it never pushes,\n comments, or opens a PR. Resolving a finding means editing code, not posting anywhere.\n- **The base must be pushed;** your local work need not be. New/untracked files are reviewed by\n default; secrets/binaries/oversized/gitignored files are filtered and reported.\n- **Don't guess creds or the base** — resolve auth first, then pass the intended target's merge-base\n SHA as `--base`, unless the user explicitly requests an exact baseline.\n- **Collect every run.** Background connected runs or use async; preserve recovery handles.\n A superseded result does not advance the incremental baseline or certify current code.\n- **Never strip context to beat the clock.** Dropping `--context-file` doesn't make a run faster —\n it just buys a worse review. Give it time; choose depth by lifecycle, never by timeout pressure.\n- An `MT-TOOL-LOOP` or `MT-RATE-LIMITED` error means stop/back off and change approach, not retry.\n- A `closed_preview` error means the org isn't enrolled in the preview — surface message + hint to\n the user and stop; never retry or loop on it (see \"If the run is gated\" above).\n\nAfter authorized fixes, report what changed, how it was verified, and what remains with reasons.\n""---\nname: qodo-review\ndescription: Review local changes with Qodo after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch authorized fixes and stop unproductive review loops. Also use for \"review my local diff\", \"pre-PR review\", or \"run qodo review\". Use qodo-review-resolver for findings already posted on a PR.\nowner: Qodo\nmetadata:\n vendor: qodo\n version: \"1.10.16\"\n recommended: \"true\"\n package: \"qodo\"\n distribution: \"marketplace\"\n instruction_mode: \"embedded\"\n---\n\n# Local Review\n\n## Description\n\nUse local review to improve the intended change, not to accumulate clean-looking runs.\nThe workflow is: finish a useful slice → test → review with context → assess findings\n→ apply authorized fixes → test again → review changed work when useful.\n\n`qodo review` collects local changes without pushing, commenting or opening a PR.\nOnly the comparison base must exist on the remote.\nUse `qodo-review-resolver` for findings already posted on a PR.\nDo not duplicate remote review for an unchanged pushed snapshot.\n\n## Prerequisites\n\n- The intended repository, comparison target and review scope are known.\n- Qodo review is available through the CLI, or through MCP with a tested local collector.\n- The user's edit, commit and review-budget constraints are known.\n- Relevant coding-session context is available. Do not require the user to reconstruct the session.\n\n## Runtime compatibility gate\n\nPrefer the CLI because it collects and filters the worktree and manages review checkpoints.\nBefore CLI use, read [CLI execution](references/cli-execution.md#preflight).\nIn every command example, replace `qodo` with that resolved invocation, including the version probe.\nOn Windows, also read [shell guidance](references/windows-shells.md) before the first command.\nUse [launcher recovery](references/windows-launcher.md) only when invocation fails.\nRequire Qodo CLI **2.0.0 or newer** and a runtime with review API v2.\nStart with the unadorned probe:\n\n```sh\nqodo --version\n```\n\nIf compatible, verify identity unless a successful check still covers this execution context:\n\n```sh\nqodo read whoami --json --skill qodo-review --skill-version 1.10.16 --distribution marketplace --host codex\n```\n\nAn old or unparseable version stops authenticated calls.\nFollow the reference's bounded compatibility recovery without changing deployment or update policy.\nConfirm available review flags with `qodo review --help`.\nDo not infer installed capability from an open PR or newer source checkout.\n\nMCP cannot read this worktree. Before an MCP review, read [MCP execution](references/mcp-review.md).\nWithout a tested collector matching the intended scope and exclusions, report the coverage blocker.\nAn ad hoc `git diff` is not equivalent collection. MCP users skip CLI preflight.\n\n## Execution and recovery policy\n\nThese are the canonical gates. References supply command syntax, result dictionaries and platform recipes;\nthey do not select different authority, compatibility or recovery policy.\n\n- **Trusted runtime:** retain the resolved installed invocation for every call, including `--version`.\n Never run repository-local launchers. If neither installed invocation works, stop the CLI path.\n Installation requires covering approval and a Qodo/organization-supplied checksum-pinned installer.\n Never invent a digest, pipe an installer into a shell, or switch deployments.\n- **Compatibility recovery:** old or unparseable versions stop identity, login, reviews and managed tools.\n Check only whether `QODO_UPDATE_BASE_URL` is set; never print its value. If set, stop for the user.\n Preserve the recorded origin, exact version choices and update holds. Choose one approved route.\n Every updater route, including ordinary update, needs a successful check offering a newer compatible 2.x target.\n Failure, no update or an incompatible target stops before any runtime change; do not switch routes.\n Same-origin `latest-2` is only a selected, verified legacy 1.x-to-stable-2.x route, not another-major approval.\n For an unparseable runtime or no supported updater, use the separately authorized checksum-pinned installer route.\n Make one approved runtime attempt, then probe the version again. Denial, failure or incompatibility stops.\n- **Identity and discovery:** reuse identity only for the same invocation, workspace, deployment and execution context.\n Possible sandbox keychain failure permits one explicitly approved read-only identity retry; denial stops.\n Only explicit missing credentials justify login. Preserve TLS, network, service and authorization failures.\n Missing catalog or an unknown managed command permits one catalog refresh, not another account.\n A still-unavailable capability is a blocker. An unknown built-in command needs compatible runtime support.\n- **Collection and retry:** preserve the accepted operation and exact uncertain-start request.\n A status transport failure permits one collection retry after the returned delay, otherwise 15 seconds.\n Failed identity or integrity verification is not a status transport failure.\n Preserve the rejected evidence; retry collection only when an applicable recovery gate permits it.\n A confirmed recoverable terminal failure permits one cause-corrected resubmission, not another retry per symptom.\n User/task no-auto-retry instructions or a returned retry prohibition require explicit approval first.\n A repository-identity correction preserves base, scope, context and effort and uses that same retry allowance.\n Permission, authentication, entitlement, rate-limit or further failure stops. A pending run is never restarted.\n Keep a connected client alive; reap its child before parsing. Progress is not a result.\n Retain the final envelope even after nonzero exit and before deleting only this invocation's temporary files.\n- **MCP:** require the tested collector, safety exclusions, omission report and fetchable base above.\n Preserve request identity after uncertain admission; collect and verify every result chunk before interpreting it.\n Keep result-view arguments unchanged while following pagination cursors.\n Never invent an unsupported collector mode, retry-key field or substitute checkout.\n- **Finding-status writes:** fixing code does not authorize a dismissal. An authorized local dismissal uses original\n finding IDs and their actual local-review IDs, grouped by review, reason and explanation.\n Never substitute a run ID or PR URL for a missing local-review ID, or omit advertised replay protection.\n Read back each stored outcome. A prior disposition or conflict is not a new successful write.\n Report status persistence separately from downstream synchronization: `reconciled: false` can mean the\n status was saved but synchronization is incomplete. Do not report that as a failed stored transition.\n Recover an uncertain invocation with its original request and transport key.\n On MCP, a completed same-key replay returns the stored result without retrying synchronization.\n After verified storage, a separately authorized synchronization attempt needs a new invocation and a new retained transport key.\n Keep the business arguments unchanged. Verify each new outcome.\n An unknown outcome does not authorize key rotation. Report unavailable recovery instead of claiming synchronization.\n Collect only a returned, supported operation handle. A synchronous tool result does not establish polling support.\n- **Requested maintenance:** preview the complete affected installation scope and apply only covering approval.\n Runtime approval is not skills-installation approval. Do not widen owners, packages, origins or update policy.\n\n## Instructions\n\n### 1. Review at a useful moment\n\nReview a coherent, testable slice after substantive work and relevant checks.\nA midwork checkpoint is useful when its feedback can guide remaining implementation.\nBefore a PR, PR update or completed-work handoff, establish coverage of the full intended change.\nA pause for a question or approval is not a completed-work handoff.\n\nDo not submit after every edit, during unfinished exploration, or merely because time passed.\nDo not automatically review trivial changes.\nRespect the user's narrower scope, explicit effort and budget.\nUnless the user requests a fresh assessment, reuse compatible completed coverage of the current intended snapshot.\n\n**Default to auto:** omit both `--fast` and `--deep` for ordinary submissions, including follow-ups.\nUse `--fast` for an explicitly requested quick review or a purposeful light midwork checkpoint.\nUse `--deep` for requested thorough scrutiny or a concrete high-impact risk. State the reason.\nDiff size, session length and final-review status alone do not justify deep.\nAuto follows deployment policy. It promises neither a fixed tier nor a spending cap.\nThere is no `--standard` flag. `--fast` and `--deep` are mutually exclusive.\n\n### 2. Capture the intended scope\n\nSelect the actual target branch, normally `origin/main`.\nFetch that target when reviewing current remote history.\nIf deliberately offline or pinned, disclose the use of locally fetched history.\nCompute `git merge-base HEAD <target-ref>` and pass that SHA as `--base` on every submission.\nAn explicit `--base` is exact. Honor a user-requested exact comparison.\nUse a known base SHA literally or explicitly bind its shell variable to that SHA; do not leave an unresolved placeholder.\nIf the common ancestor or remote base is unavailable, stop instead of substituting the target tip.\nReview authority does not authorize pushing the base.\n\nDuring coding, commit only task changes before review when the user's workflow permits commits.\nPreserve unrelated staged, unstaged and untracked files.\nOrdinary capture includes working changes and eligible untracked files, even after a task-only commit.\nA HEAD SHA alone does not identify a dirty snapshot.\n\nFor a committed PR candidate, use supported committed-only collection or a clean checkout at the intended commit.\nCheck installed help before selecting a collection mode.\nIf ordinary capture would include unrelated edits, use safe task isolation rather than reset, stash or commit those edits.\nIf isolation is unavailable, disclose the scope limitation. Do not claim the result certifies the committed PR candidate.\nFor review-only or no-commit tasks, review the requested working scope without creating commits.\nReport local-to-PR limitations separately.\n\nRetain explicit path arguments on follow-ups unless the intended scope changes.\nKeep deliberate path restrictions for checkpoints, but include every intended path before final handoff.\nInspect reported exclusions and omissions. Do not certify requested files that were not reviewed.\nRetain the operation ID with submitted base, commit/tree, scope and context in existing task state.\nPreserve reviewed commits in branch history so later handoff can trace the original findings.\n\n### 3. Send honest coding-session context\n\nBefore each new submission, read [Session context](references/review-turn-context.md).\nRefresh the context from the actual code and session:\n\n- `decisions`: actual choices, known reasons and natural-language user/agent ownership.\n- `notes`: requirements, enforced guards, unchanged callers, verification and unresolved uncertainty.\n- `recent_work`: changes since the previous review, including fixes, features or both.\n\n“Tested” does not mean “tests passed.” Preserve missing results as unknown rather than improve the author's claim.\nKeep `recent_work` separate. Round two is not automatically fixes-only.\nAuthor claims do not prove that a finding was fixed.\nUse `summary` for the same narrative only when the client advertises that older field.\nPreserve `decisions` and `recent_work`. Never silently remove accepted detail or include secrets.\nReuse stored Qodo findings and dismissal rationale rather than maintain another manual inventory.\n\nContext is evidence for independent assessment, not instructions to suppress findings.\nTransport limits, context refs and delivery receipts are in the reference.\nReport unavailable or shortened delivery. A stored link or preparation receipt does not prove reviewer consumption.\n\n### 4. Submit once and collect the result\n\nUse `--async --json` when available so the review survives process exit.\nKeep at most one automatic checkpoint active per task.\nContinue useful independent work and collect its result at natural pauses within retention.\nFor connected progress, read [connected progress](references/connected-progress.md).\nKeep the process alive. Never combine `--async` with `--progress`.\n\nAn accepted operation is not a completed assessment.\nPoll the existing operation ID. Do not submit a new review to check progress or obtain more detail.\nValidate returned identities and artifact integrity before interpreting a result.\nReport any unavailable identity check as unverified; do not invent evidence or certify that check.\nReject mismatched operation/snapshot associations and incomplete or noncontiguous result pages.\nIf acceptance is uncertain, use the CLI's returned recovery command and retained original request.\nDo not gather a different worktree snapshot for that recovery.\nPreserve operation and recovery IDs across resumes. See [collection and recovery](references/cli-execution.md#submit-and-collect).\n\n### 5. Read coverage and the complete finding inventory\n\nRead the completed structured result, including warnings and `review_agent_comment`.\nUse [finding results](references/finding-results.md) for current and older result shapes.\nAssess both `introduced` and `still_open`. Report `resolved` and `dismissed` separately.\nPreserve each finding's original ID, category, action level, state and rationale.\nRecheck findings against current code when work changed during the run.\n\nReport incomplete `finding_state.complete` or `meta.coverage.complete`.\nMissing metadata is unknown, not proof of completion.\nPending, failed, partial or superseded results cannot certify newer work.\nA completed assessment can still have unresolved findings or failed persistence.\nNo new findings does not settle earlier blockers.\n\nPrefer incremental continuation. Let the Engine qualify checkpoints and report `full`, `incremental` or `reused`.\nDo not add `--full` merely because notes changed, findings remain open, or the review precedes a PR.\nUse it for a user-requested fresh assessment or when the previous assessment was incomplete.\nKeep base, intended scope and requested effort stable when appropriate. Refresh context truthfully.\nIf the Engine cannot reuse evidence, report its actual fallback or missing coverage.\nDo not fabricate checkpoints or suppress meaningful policy/instruction changes to obtain reuse.\nIntent, reviewer selection, code scope, effort and fix attribution are separate decisions.\nThe Engine's intent judge owns eligibility. Do not infer it from the round number or price.\n\n## Present the review result\n\nCredit Qodo naturally once for the concerns its review surfaced.\nExplain each material finding as practical impact → assessment against code and session context → recommended action.\nState the triggering condition and affected behavior. Cite supporting code.\nPreserve reported category/level separately from your recommendation.\nGroup duplicates only when every finding reference remains visible and individually selectable.\nKeep the tone factual. Do not turn an unsupported finding into a broad judgment about Qodo.\n\nLead with material coverage failures or missing evidence.\nSeparate new findings, earlier open backlog and settled findings so old work does not appear newly discovered.\nA complete review with no findings can take one sentence.\nUse no branded headings, banners or repeated summaries. Do not call zero findings alone clean.\n\n## Act on the findings\n\nIndependently assess each finding: fix a supported issue, recommend dismissal with evidence, or investigate uncertainty.\nA session decision supports the assessment only when the code enforces its assumptions.\nYour recommendation does not grant authority.\n\n- **Report-only:** assess and stop. Do not edit or solicit permission to turn the task into implementation.\n- **Authorized implementation/fixes:** batch supported corrections within the existing scope without asking again.\n- **Ambiguous edit scope:** present all findings and ask once which to apply. Preselect nothing.\n\nKeep uncertain and out-of-scope findings visible.\nDo not expand the task with optional refactors merely to reduce the finding count.\nFix authority does not authorize stored dismissals, pushes or unrelated changes.\nFor explicitly authorized finding-status writes, read [local triage](references/local-triage.md) and verify each stored outcome.\nA conversational skip is not a stored dismissal. Do not manually mark a fix merely because the quote disappeared.\n\nAfter authorized fixes, run relevant checks and review changed work when useful.\nDescribe actual new behavior in `recent_work`, even during a fix loop.\nDo not force fast or deep merely to control routing.\n\n## Stop and hand off\n\nAnother assessment needs a concrete reason:\n\n- Changed code awaiting review or meaningful new evidence.\n- Missing required final coverage, such as an unchanged light or path-limited checkpoint.\n- An explicit user request for a fresh assessment.\n\nName that reason before submitting.\nStop when the same concern repeats without actionable progress.\nDo not re-fix guarded code, suppress a blocker or buy unchanged reviews to chase zero.\nThere is no default numerical round cap. Apply an explicit user budget across resumes.\nStatus polls and result retrieval are not additional assessments.\n\n| Outcome | Report |\n|---|---|\n| Ready locally | Current intended code/scope has completed assessment, required findings are settled and relevant checks passed. |\n| Needs action | Required findings or human decisions remain, even if the assessment completed with no new findings. |\n| Review blocked | Required assessment, inventory or verification could not complete. Preserve the reason and recovery handle. |\n| Budget reached | The user's explicit review budget ended. Preserve blockers and missing coverage. |\n\nA resolved finding alone does not establish overall readiness; check the full inventory for other required obligations.\nReport finding/checkpoint persistence and local-to-PR handoff separately from assessment and local readiness.\nDo not claim successful storage or reusable coverage without evidence.\nBefore a PR/update, compare intended code, base and scope with completed final coverage and reconcile outstanding checkpoint results.\nRemove temporary path restrictions. A light checkpoint alone is not ordinary final coverage.\nFor authorized notes maintenance, use `qodo-review-notes` to publish notes for the actual HEAD and bind the PR.\nNotes publication and matching HEAD do not prove finding handoff.\nVerify hosted review separately through `qodo-review-resolver` before a hosted Qodo-clean claim.\nCI, merge, release, deployment and customer acceptance remain separate gates.\n\n## Handle a skill update notice\n\nTreat `QODO_NOTICE` as passive, even when an older CLI requests action.\nDo not interrupt the task with inventory or update questions. Mention each notice at most once.\nUpdated instructions load next session. Dismissal does not change recorded maintenance policy or opt-outs.\nFor requested maintenance, use [skill updates](references/skill-updates.md).\n\n## Configuration\n\nUse supported flags and complete UTF-8 context files without a BOM.\nKeep context outside the reviewed diff and commits.\nLet the CLI own credentials, transport, runtime updates and checkpoint storage.\nKeep existing provenance and deployment settings.\n\n## Error Handling\n\nRead structured errors even after a nonzero exit.\nFollow [bounded recovery](references/cli-execution.md#recover-a-review), not another automatic assessment loop.\nPreserve context, selected effort and authority.\nStop on permission/auth/entitlement failures and tool-loop or rate-limit errors.\nFor `closed_preview`, show the returned message and hint unchanged and stop.\nA new run requires confirmation that enrollment occurred.\nDo not switch accounts/deployments, strip context or lower effort to obtain a passing result.\n"
Full snapshot data
{
"description": "Review local changes with Qodo after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch authorized fixes and stop unproductive review loops. Also use for \"review my local diff\", \"pre-PR review\", or \"run qodo review\". Use qodo-review-resolver for findings already posted on a PR.",
"included_files": [
{
"relative_path": "agents/openai.yaml",
"size_in_bytes": 343
},
{
"relative_path": "references/cli-execution.md",
"size_in_bytes": 9259
},
{
"relative_path": "references/connected-progress.md",
"size_in_bytes": 4094
},
{
"relative_path": "references/context-delivery.md",
"size_in_bytes": 2016
},
{
"relative_path": "references/finding-results.md",
"size_in_bytes": 5482
},
{
"relative_path": "references/local-triage.md",
"size_in_bytes": 4780
},
{
"relative_path": "references/mcp-review.md",
"size_in_bytes": 2701
},
{
"relative_path": "references/review-turn-context.md",
"size_in_bytes": 8811
},
{
"relative_path": "references/skill-updates.md",
"size_in_bytes": 1685
},
{
"relative_path": "references/windows-launcher.md",
"size_in_bytes": 1203
},
{
"relative_path": "references/windows-shells.md",
"size_in_bytes": 917
}
],
"name": "qodo-review",
"skill_md_contents": "---\nname: qodo-review\ndescription: Review local changes with Qodo after coherent substantive work and before a PR or completed-work handoff. Use default auto effort, attach coding-session context, assess findings, batch authorized fixes and stop unproductive review loops. Also use for \"review my local diff\", \"pre-PR review\", or \"run qodo review\". Use qodo-review-resolver for findings already posted on a PR.\nowner: Qodo\nmetadata:\n vendor: qodo\n version: \"1.10.16\"\n recommended: \"true\"\n package: \"qodo\"\n distribution: \"marketplace\"\n instruction_mode: \"embedded\"\n---\n\n# Local Review\n\n## Description\n\nUse local review to improve the intended change, not to accumulate clean-looking runs.\nThe workflow is: finish a useful slice → test → review with context → assess findings\n→ apply authorized fixes → test again → review changed work when useful.\n\n`qodo review` collects local changes without pushing, commenting or opening a PR.\nOnly the comparison base must exist on the remote.\nUse `qodo-review-resolver` for findings already posted on a PR.\nDo not duplicate remote review for an unchanged pushed snapshot.\n\n## Prerequisites\n\n- The intended repository, comparison target and review scope are known.\n- Qodo review is available through the CLI, or through MCP with a tested local collector.\n- The user's edit, commit and review-budget constraints are known.\n- Relevant coding-session context is available. Do not require the user to reconstruct the session.\n\n## Runtime compatibility gate\n\nPrefer the CLI because it collects and filters the worktree and manages review checkpoints.\nBefore CLI use, read [CLI execution](references/cli-execution.md#preflight).\nIn every command example, replace `qodo` with that resolved invocation, including the version probe.\nOn Windows, also read [shell guidance](references/windows-shells.md) before the first command.\nUse [launcher recovery](references/windows-launcher.md) only when invocation fails.\nRequire Qodo CLI **2.0.0 or newer** and a runtime with review API v2.\nStart with the unadorned probe:\n\n```sh\nqodo --version\n```\n\nIf compatible, verify identity unless a successful check still covers this execution context:\n\n```sh\nqodo read whoami --json --skill qodo-review --skill-version 1.10.16 --distribution marketplace --host codex\n```\n\nAn old or unparseable version stops authenticated calls.\nFollow the reference's bounded compatibility recovery without changing deployment or update policy.\nConfirm available review flags with `qodo review --help`.\nDo not infer installed capability from an open PR or newer source checkout.\n\nMCP cannot read this worktree. Before an MCP review, read [MCP execution](references/mcp-review.md).\nWithout a tested collector matching the intended scope and exclusions, report the coverage blocker.\nAn ad hoc `git diff` is not equivalent collection. MCP users skip CLI preflight.\n\n## Execution and recovery policy\n\nThese are the canonical gates. References supply command syntax, result dictionaries and platform recipes;\nthey do not select different authority, compatibility or recovery policy.\n\n- **Trusted runtime:** retain the resolved installed invocation for every call, including `--version`.\n Never run repository-local launchers. If neither installed invocation works, stop the CLI path.\n Installation requires covering approval and a Qodo/organization-supplied checksum-pinned installer.\n Never invent a digest, pipe an installer into a shell, or switch deployments.\n- **Compatibility recovery:** old or unparseable versions stop identity, login, reviews and managed tools.\n Check only whether `QODO_UPDATE_BASE_URL` is set; never print its value. If set, stop for the user.\n Preserve the recorded origin, exact version choices and update holds. Choose one approved route.\n Every updater route, including ordinary update, needs a successful check offering a newer compatible 2.x target.\n Failure, no update or an incompatible target stops before any runtime change; do not switch routes.\n Same-origin `latest-2` is only a selected, verified legacy 1.x-to-stable-2.x route, not another-major approval.\n For an unparseable runtime or no supported updater, use the separately authorized checksum-pinned installer route.\n Make one approved runtime attempt, then probe the version again. Denial, failure or incompatibility stops.\n- **Identity and discovery:** reuse identity only for the same invocation, workspace, deployment and execution context.\n Possible sandbox keychain failure permits one explicitly approved read-only identity retry; denial stops.\n Only explicit missing credentials justify login. Preserve TLS, network, service and authorization failures.\n Missing catalog or an unknown managed command permits one catalog refresh, not another account.\n A still-unavailable capability is a blocker. An unknown built-in command needs compatible runtime support.\n- **Collection and retry:** preserve the accepted operation and exact uncertain-start request.\n A status transport failure permits one collection retry after the returned delay, otherwise 15 seconds.\n Failed identity or integrity verification is not a status transport failure.\n Preserve the rejected evidence; retry collection only when an applicable recovery gate permits it.\n A confirmed recoverable terminal failure permits one cause-corrected resubmission, not another retry per symptom.\n User/task no-auto-retry instructions or a returned retry prohibition require explicit approval first.\n A repository-identity correction preserves base, scope, context and effort and uses that same retry allowance.\n Permission, authentication, entitlement, rate-limit or further failure stops. A pending run is never restarted.\n Keep a connected client alive; reap its child before parsing. Progress is not a result.\n Retain the final envelope even after nonzero exit and before deleting only this invocation's temporary files.\n- **MCP:** require the tested collector, safety exclusions, omission report and fetchable base above.\n Preserve request identity after uncertain admission; collect and verify every result chunk before interpreting it.\n Keep result-view arguments unchanged while following pagination cursors.\n Never invent an unsupported collector mode, retry-key field or substitute checkout.\n- **Finding-status writes:** fixing code does not authorize a dismissal. An authorized local dismissal uses original\n finding IDs and their actual local-review IDs, grouped by review, reason and explanation.\n Never substitute a run ID or PR URL for a missing local-review ID, or omit advertised replay protection.\n Read back each stored outcome. A prior disposition or conflict is not a new successful write.\n Report status persistence separately from downstream synchronization: `reconciled: false` can mean the\n status was saved but synchronization is incomplete. Do not report that as a failed stored transition.\n Recover an uncertain invocation with its original request and transport key.\n On MCP, a completed same-key replay returns the stored result without retrying synchronization.\n After verified storage, a separately authorized synchronization attempt needs a new invocation and a new retained transport key.\n Keep the business arguments unchanged. Verify each new outcome.\n An unknown outcome does not authorize key rotation. Report unavailable recovery instead of claiming synchronization.\n Collect only a returned, supported operation handle. A synchronous tool result does not establish polling support.\n- **Requested maintenance:** preview the complete affected installation scope and apply only covering approval.\n Runtime approval is not skills-installation approval. Do not widen owners, packages, origins or update policy.\n\n## Instructions\n\n### 1. Review at a useful moment\n\nReview a coherent, testable slice after substantive work and relevant checks.\nA midwork checkpoint is useful when its feedback can guide remaining implementation.\nBefore a PR, PR update or completed-work handoff, establish coverage of the full intended change.\nA pause for a question or approval is not a completed-work handoff.\n\nDo not submit after every edit, during unfinished exploration, or merely because time passed.\nDo not automatically review trivial changes.\nRespect the user's narrower scope, explicit effort and budget.\nUnless the user requests a fresh assessment, reuse compatible completed coverage of the current intended snapshot.\n\n**Default to auto:** omit both `--fast` and `--deep` for ordinary submissions, including follow-ups.\nUse `--fast` for an explicitly requested quick review or a purposeful light midwork checkpoint.\nUse `--deep` for requested thorough scrutiny or a concrete high-impact risk. State the reason.\nDiff size, session length and final-review status alone do not justify deep.\nAuto follows deployment policy. It promises neither a fixed tier nor a spending cap.\nThere is no `--standard` flag. `--fast` and `--deep` are mutually exclusive.\n\n### 2. Capture the intended scope\n\nSelect the actual target branch, normally `origin/main`.\nFetch that target when reviewing current remote history.\nIf deliberately offline or pinned, disclose the use of locally fetched history.\nCompute `git merge-base HEAD <target-ref>` and pass that SHA as `--base` on every submission.\nAn explicit `--base` is exact. Honor a user-requested exact comparison.\nUse a known base SHA literally or explicitly bind its shell variable to that SHA; do not leave an unresolved placeholder.\nIf the common ancestor or remote base is unavailable, stop instead of substituting the target tip.\nReview authority does not authorize pushing the base.\n\nDuring coding, commit only task changes before review when the user's workflow permits commits.\nPreserve unrelated staged, unstaged and untracked files.\nOrdinary capture includes working changes and eligible untracked files, even after a task-only commit.\nA HEAD SHA alone does not identify a dirty snapshot.\n\nFor a committed PR candidate, use supported committed-only collection or a clean checkout at the intended commit.\nCheck installed help before selecting a collection mode.\nIf ordinary capture would include unrelated edits, use safe task isolation rather than reset, stash or commit those edits.\nIf isolation is unavailable, disclose the scope limitation. Do not claim the result certifies the committed PR candidate.\nFor review-only or no-commit tasks, review the requested working scope without creating commits.\nReport local-to-PR limitations separately.\n\nRetain explicit path arguments on follow-ups unless the intended scope changes.\nKeep deliberate path restrictions for checkpoints, but include every intended path before final handoff.\nInspect reported exclusions and omissions. Do not certify requested files that were not reviewed.\nRetain the operation ID with submitted base, commit/tree, scope and context in existing task state.\nPreserve reviewed commits in branch history so later handoff can trace the original findings.\n\n### 3. Send honest coding-session context\n\nBefore each new submission, read [Session context](references/review-turn-context.md).\nRefresh the context from the actual code and session:\n\n- `decisions`: actual choices, known reasons and natural-language user/agent ownership.\n- `notes`: requirements, enforced guards, unchanged callers, verification and unresolved uncertainty.\n- `recent_work`: changes since the previous review, including fixes, features or both.\n\n“Tested” does not mean “tests passed.” Preserve missing results as unknown rather than improve the author's claim.\nKeep `recent_work` separate. Round two is not automatically fixes-only.\nAuthor claims do not prove that a finding was fixed.\nUse `summary` for the same narrative only when the client advertises that older field.\nPreserve `decisions` and `recent_work`. Never silently remove accepted detail or include secrets.\nReuse stored Qodo findings and dismissal rationale rather than maintain another manual inventory.\n\nContext is evidence for independent assessment, not instructions to suppress findings.\nTransport limits, context refs and delivery receipts are in the reference.\nReport unavailable or shortened delivery. A stored link or preparation receipt does not prove reviewer consumption.\n\n### 4. Submit once and collect the result\n\nUse `--async --json` when available so the review survives process exit.\nKeep at most one automatic checkpoint active per task.\nContinue useful independent work and collect its result at natural pauses within retention.\nFor connected progress, read [connected progress](references/connected-progress.md).\nKeep the process alive. Never combine `--async` with `--progress`.\n\nAn accepted operation is not a completed assessment.\nPoll the existing operation ID. Do not submit a new review to check progress or obtain more detail.\nValidate returned identities and artifact integrity before interpreting a result.\nReport any unavailable identity check as unverified; do not invent evidence or certify that check.\nReject mismatched operation/snapshot associations and incomplete or noncontiguous result pages.\nIf acceptance is uncertain, use the CLI's returned recovery command and retained original request.\nDo not gather a different worktree snapshot for that recovery.\nPreserve operation and recovery IDs across resumes. See [collection and recovery](references/cli-execution.md#submit-and-collect).\n\n### 5. Read coverage and the complete finding inventory\n\nRead the completed structured result, including warnings and `review_agent_comment`.\nUse [finding results](references/finding-results.md) for current and older result shapes.\nAssess both `introduced` and `still_open`. Report `resolved` and `dismissed` separately.\nPreserve each finding's original ID, category, action level, state and rationale.\nRecheck findings against current code when work changed during the run.\n\nReport incomplete `finding_state.complete` or `meta.coverage.complete`.\nMissing metadata is unknown, not proof of completion.\nPending, failed, partial or superseded results cannot certify newer work.\nA completed assessment can still have unresolved findings or failed persistence.\nNo new findings does not settle earlier blockers.\n\nPrefer incremental continuation. Let the Engine qualify checkpoints and report `full`, `incremental` or `reused`.\nDo not add `--full` merely because notes changed, findings remain open, or the review precedes a PR.\nUse it for a user-requested fresh assessment or when the previous assessment was incomplete.\nKeep base, intended scope and requested effort stable when appropriate. Refresh context truthfully.\nIf the Engine cannot reuse evidence, report its actual fallback or missing coverage.\nDo not fabricate checkpoints or suppress meaningful policy/instruction changes to obtain reuse.\nIntent, reviewer selection, code scope, effort and fix attribution are separate decisions.\nThe Engine's intent judge owns eligibility. Do not infer it from the round number or price.\n\n## Present the review result\n\nCredit Qodo naturally once for the concerns its review surfaced.\nExplain each material finding as practical impact → assessment against code and session context → recommended action.\nState the triggering condition and affected behavior. Cite supporting code.\nPreserve reported category/level separately from your recommendation.\nGroup duplicates only when every finding reference remains visible and individually selectable.\nKeep the tone factual. Do not turn an unsupported finding into a broad judgment about Qodo.\n\nLead with material coverage failures or missing evidence.\nSeparate new findings, earlier open backlog and settled findings so old work does not appear newly discovered.\nA complete review with no findings can take one sentence.\nUse no branded headings, banners or repeated summaries. Do not call zero findings alone clean.\n\n## Act on the findings\n\nIndependently assess each finding: fix a supported issue, recommend dismissal with evidence, or investigate uncertainty.\nA session decision supports the assessment only when the code enforces its assumptions.\nYour recommendation does not grant authority.\n\n- **Report-only:** assess and stop. Do not edit or solicit permission to turn the task into implementation.\n- **Authorized implementation/fixes:** batch supported corrections within the existing scope without asking again.\n- **Ambiguous edit scope:** present all findings and ask once which to apply. Preselect nothing.\n\nKeep uncertain and out-of-scope findings visible.\nDo not expand the task with optional refactors merely to reduce the finding count.\nFix authority does not authorize stored dismissals, pushes or unrelated changes.\nFor explicitly authorized finding-status writes, read [local triage](references/local-triage.md) and verify each stored outcome.\nA conversational skip is not a stored dismissal. Do not manually mark a fix merely because the quote disappeared.\n\nAfter authorized fixes, run relevant checks and review changed work when useful.\nDescribe actual new behavior in `recent_work`, even during a fix loop.\nDo not force fast or deep merely to control routing.\n\n## Stop and hand off\n\nAnother assessment needs a concrete reason:\n\n- Changed code awaiting review or meaningful new evidence.\n- Missing required final coverage, such as an unchanged light or path-limited checkpoint.\n- An explicit user request for a fresh assessment.\n\nName that reason before submitting.\nStop when the same concern repeats without actionable progress.\nDo not re-fix guarded code, suppress a blocker or buy unchanged reviews to chase zero.\nThere is no default numerical round cap. Apply an explicit user budget across resumes.\nStatus polls and result retrieval are not additional assessments.\n\n| Outcome | Report |\n|---|---|\n| Ready locally | Current intended code/scope has completed assessment, required findings are settled and relevant checks passed. |\n| Needs action | Required findings or human decisions remain, even if the assessment completed with no new findings. |\n| Review blocked | Required assessment, inventory or verification could not complete. Preserve the reason and recovery handle. |\n| Budget reached | The user's explicit review budget ended. Preserve blockers and missing coverage. |\n\nA resolved finding alone does not establish overall readiness; check the full inventory for other required obligations.\nReport finding/checkpoint persistence and local-to-PR handoff separately from assessment and local readiness.\nDo not claim successful storage or reusable coverage without evidence.\nBefore a PR/update, compare intended code, base and scope with completed final coverage and reconcile outstanding checkpoint results.\nRemove temporary path restrictions. A light checkpoint alone is not ordinary final coverage.\nFor authorized notes maintenance, use `qodo-review-notes` to publish notes for the actual HEAD and bind the PR.\nNotes publication and matching HEAD do not prove finding handoff.\nVerify hosted review separately through `qodo-review-resolver` before a hosted Qodo-clean claim.\nCI, merge, release, deployment and customer acceptance remain separate gates.\n\n## Handle a skill update notice\n\nTreat `QODO_NOTICE` as passive, even when an older CLI requests action.\nDo not interrupt the task with inventory or update questions. Mention each notice at most once.\nUpdated instructions load next session. Dismissal does not change recorded maintenance policy or opt-outs.\nFor requested maintenance, use [skill updates](references/skill-updates.md).\n\n## Configuration\n\nUse supported flags and complete UTF-8 context files without a BOM.\nKeep context outside the reviewed diff and commits.\nLet the CLI own credentials, transport, runtime updates and checkpoint storage.\nKeep existing provenance and deployment settings.\n\n## Error Handling\n\nRead structured errors even after a nonzero exit.\nFollow [bounded recovery](references/cli-execution.md#recover-a-review), not another automatic assessment loop.\nPreserve context, selected effort and authority.\nStop on permission/auth/entitlement failures and tool-loop or rate-limit errors.\nFor `closed_preview`, show the returned message and hint unchanged and stop.\nA new run requires confirmation that enrollment occurred.\nDo not switch accounts/deployments, strip context or lower effort to obtain a passing result.\n"
}SHA-256 of public snapshot: 3b0cab1fcce5d3bc3d6a95138a3bd0a92e525d569546fafb39227c950e9a4a55