Change Review Agent
Use this skill after implementation work when the user explicitly asks for an
agent or subagent to review the current changes. The review agent is a second
pass, not the implementer, and must not edit files.
Trigger Phrases
Examples include:
- "start an agent review for these changes"
- "ask another agent to review the diff"
- "spawn a review agent"
- "run a subagent code review"
- "use an agent to review my changes"
Do not use this skill merely because the user asks for depth, confidence, or a
normal review. Only start a subagent when the user explicitly requests an agent
or subagent.
Workflow
- Finish any in-progress local edits before starting the review.
- Capture the local review scope, including staged and untracked files:
git status --short --untracked-files=all
git diff --stat HEAD
git diff --name-only HEAD
git diff --check HEAD
git ls-files --others --exclude-standard
If the worktree contains unrelated user changes, identify the files that belong
to the current task and tell the review agent to focus on those files. If
untracked files are in scope, include their paths and either their contents or a
concise content summary in the review prompt because git diff will not show
them.
- Check review readiness before spawning:
- If the diff is too broad, mixes unrelated goals, or has unclear scope, ask
the reviewer to report this as a finding or note.
- If verification is missing, pass that fact through explicitly instead of
implying the change was tested.
- If generated files, lockfiles, snapshots, or package outputs are present,
tell the reviewer whether they are in scope or incidental.
- Start one read-only review agent, normally an
explorer agent.
- In the review prompt, include:
- repository path
- original user request or current task goal
- files in scope
- verification already run and any failures
- explicit instruction not to edit files or run mutating commands
- Wait for the reviewer before giving the final answer, unless the user asks
for an asynchronous handoff.
- Triage the review result:
- Do not make follow-up code edits just because the reviewer found issues.
Report the findings first and wait for explicit user direction unless the
user already asked to "review and fix".
- If the user explicitly asked to review and fix, validate the finding
yourself before editing, then rerun relevant checks.
- If the user asked only for review, report the findings without making
further changes.
- If the review has no findings, say that clearly and mention any remaining
test gaps or risks.
Allowed and Forbidden Actions
The review agent may run read-only inspection commands such as git status,
git diff, git diff --check, git log, rg, sed, find, ls, package
metadata reads, and test-file inspection.
The review agent must not edit files, format code, stage changes, commit,
install or update dependencies, regenerate outputs, run package scripts that
can mutate the worktree, or apply automated fixes. If a command might mutate
the worktree, the reviewer should list it as suggested verification instead of
running it.
Review Readiness
Before line-level review, the reviewer should decide whether the diff is ready
for useful review:
- scope: one coherent task, no unrelated refactors or formatting churn
- context: task goal and changed files are understandable from the prompt and
diff
- size: large or multi-package diffs identify main files and likely review
order; overly broad diffs should be flagged for splitting
- verification: relevant checks are reported, missing, or intentionally skipped
- generated artifacts: lockfiles, snapshots, bundled outputs, and generated docs
are either explained or flagged as unclear
Readiness problems can be findings when they create merge risk, or notes when
they only limit review confidence.
Review Order
Ask the reviewer to inspect in this order:
- Understand the task goal, diff summary, changed file list, and impact area.
- Review the main implementation files and contracts first.
- Review tests next, including whether they fail for the changed behavior.
- Review package metadata, manifests, docs, install steps, generated files, and
release/changeset implications.
- Scan the rest of the in-scope files so every human-written change has been
considered.
Review Focus
The review agent should inspect the diff as a production code reviewer. Ask it
to cover:
- conflicts with existing behavior, public APIs, package/plugin manifests,
install flows, docs, marketplace entries, and established repository patterns
- impact area: affected packages, commands, docs, tests, generated artifacts,
user-visible behavior, and release or changeset implications
- correctness risks: regressions, broken contracts, missing edge cases,
incomplete error handling, async/concurrency issues, and platform assumptions
- test risk: changed behavior without targeted coverage, stale snapshots, or
verification that does not exercise the risky path
- maintainability risk: duplicated logic, unclear ownership boundaries, or
changes that make future package integration work harder
- security and supply-chain risk: secrets, unsafe shelling out, untrusted input,
dependency changes, permissions, tokens, and package publishing surfaces
- migration and rollback risk: config changes, persistent state, release tags,
marketplace pointers, install commands, or behavior that is hard to undo
Evidence Standard
Every finding must be actionable and evidence-backed:
- include priority, file/line, affected surface, risk, and smallest fix
- explain the concrete failure mode or merge risk, not just a preference
- distinguish confirmed defects from hypotheses and unverified concerns
- label style-only or taste-only feedback as
P3 or a note
- avoid comments that only restate the diff or ask broad questions without a
specific risk
If a reviewer cannot verify a concern from the available context, they should
state what evidence is missing and which command or file would resolve it.
Escalation
Ask for a domain expert or maintainer decision instead of overclaiming when the
change touches areas such as:
- security, auth, tokens, private data, or permissions
- release automation, package publishing, versioning, changesets, or
marketplace metadata
- installation flows, generated package contents, plugin manifests, or host-tool
compatibility
- concurrency, async ordering, persistent state, migrations, or destructive
commands
- broad architecture changes or ownership boundaries across packages
Severity Ratings
Require every finding to include one priority:
P0: blocks release or can cause data loss, security exposure, widespread
runtime failure, broken installs, or destructive behavior.
P1: likely user-facing regression, broken supported workflow, incompatible
package/API behavior, or high-confidence CI/release failure.
P2: localized bug, missing important test, confusing behavior, or
compatibility risk that should be fixed before merge.
P3: low-risk cleanup, naming clarity, minor docs issue, or maintainability
improvement that can reasonably follow later.
Findings without a concrete risk should be reported as notes, not blocking
findings.
Review Agent Prompt Template
Use a focused prompt like this:
Review the current uncommitted changes in <repo-path> as a code reviewer.
Do not edit files or run mutating commands. Inspect git status, git diff, and
the relevant source/tests. Focus only on these in-scope files unless another
file is needed to understand a contract:
<files>
Original task:
<task>
Verification already run:
<commands and results>
First assess review readiness: scope clarity, unrelated changes, diff size,
missing verification, and any unexplained generated artifacts.
Review in order: overall task and impact, main implementation and contracts,
tests, package/docs/manifests/generated files, then the rest of the in-scope
human-written changes.
Review for conflicts with existing behavior, public APIs, package/plugin
manifests, install flows, docs, marketplace entries, and established repository
patterns. Assess impact area, security/supply-chain risk, rollback risk, and
release/changeset implications.
Return findings first, ordered by severity. Each finding must include a P0-P3
priority, concrete file/line reference, affected surface, risk, and smallest
actionable fix. Prioritize bugs, regressions, broken contracts, missing tests
for changed behavior, release or packaging risks, and hidden compatibility
conflicts. If there are no findings, say that directly and list residual test
gaps or impact areas that were not verified. Escalate anything needing a domain
expert or maintainer decision instead of overclaiming certainty.
Reporting Shape
When the agent returns, answer in a code-review style:
- findings first, ordered by severity, each with
P0-P3
- affected surface and impact area for each finding
- review readiness issues, if any
- escalation or maintainer-decision items, if any
- open questions or assumptions
- whether the reviewer found no issues
- verification status and remaining test gaps
Do not bury real findings in a long summary. If you disagree with a reviewer
finding, state why and whether you verified the disagreement locally. Do not
make additional code changes after the review unless the user explicitly asks
you to fix the findings.
1---2name: change-review-agent3description: Use this project-local skill when the user asks Codex to start, spawn, launch, or use an agent/subagent to review current code changes, implementation, diff, or completed modifications in this repository with read-only review, readiness checks, conflict checks, impact analysis, evidence-backed findings, escalation notes, and P0-P3 severity ratings.4metadata:5 source: https://skillmd.com/skills/calle-ai/change-review-agent6---78# Change Review Agent910Use this skill after implementation work when the user explicitly asks for an11agent or subagent to review the current changes. The review agent is a second12pass, not the implementer, and must not edit files.1314## Trigger Phrases1516Examples include:1718- "start an agent review for these changes"19- "ask another agent to review the diff"20- "spawn a review agent"21- "run a subagent code review"22- "use an agent to review my changes"2324Do not use this skill merely because the user asks for depth, confidence, or a25normal review. Only start a subagent when the user explicitly requests an agent26or subagent.2728## Workflow29301. Finish any in-progress local edits before starting the review.312. Capture the local review scope, including staged and untracked files:3233```bash34git status --short --untracked-files=all35git diff --stat HEAD36git diff --name-only HEAD37git diff --check HEAD38git ls-files --others --exclude-standard39```4041If the worktree contains unrelated user changes, identify the files that belong42to the current task and tell the review agent to focus on those files. If43untracked files are in scope, include their paths and either their contents or a44concise content summary in the review prompt because `git diff` will not show45them.46473. Check review readiness before spawning:48 - If the diff is too broad, mixes unrelated goals, or has unclear scope, ask49 the reviewer to report this as a finding or note.50 - If verification is missing, pass that fact through explicitly instead of51 implying the change was tested.52 - If generated files, lockfiles, snapshots, or package outputs are present,53 tell the reviewer whether they are in scope or incidental.544. Start one read-only review agent, normally an `explorer` agent.555. In the review prompt, include:56 - repository path57 - original user request or current task goal58 - files in scope59 - verification already run and any failures60 - explicit instruction not to edit files or run mutating commands616. Wait for the reviewer before giving the final answer, unless the user asks62 for an asynchronous handoff.637. Triage the review result:64 - Do not make follow-up code edits just because the reviewer found issues.65 Report the findings first and wait for explicit user direction unless the66 user already asked to "review and fix".67 - If the user explicitly asked to review and fix, validate the finding68 yourself before editing, then rerun relevant checks.69 - If the user asked only for review, report the findings without making70 further changes.71 - If the review has no findings, say that clearly and mention any remaining72 test gaps or risks.7374## Allowed and Forbidden Actions7576The review agent may run read-only inspection commands such as `git status`,77`git diff`, `git diff --check`, `git log`, `rg`, `sed`, `find`, `ls`, package78metadata reads, and test-file inspection.7980The review agent must not edit files, format code, stage changes, commit,81install or update dependencies, regenerate outputs, run package scripts that82can mutate the worktree, or apply automated fixes. If a command might mutate83the worktree, the reviewer should list it as suggested verification instead of84running it.8586## Review Readiness8788Before line-level review, the reviewer should decide whether the diff is ready89for useful review:9091- scope: one coherent task, no unrelated refactors or formatting churn92- context: task goal and changed files are understandable from the prompt and93 diff94- size: large or multi-package diffs identify main files and likely review95 order; overly broad diffs should be flagged for splitting96- verification: relevant checks are reported, missing, or intentionally skipped97- generated artifacts: lockfiles, snapshots, bundled outputs, and generated docs98 are either explained or flagged as unclear99100Readiness problems can be findings when they create merge risk, or notes when101they only limit review confidence.102103## Review Order104105Ask the reviewer to inspect in this order:1061071. Understand the task goal, diff summary, changed file list, and impact area.1082. Review the main implementation files and contracts first.1093. Review tests next, including whether they fail for the changed behavior.1104. Review package metadata, manifests, docs, install steps, generated files, and111 release/changeset implications.1125. Scan the rest of the in-scope files so every human-written change has been113 considered.114115## Review Focus116117The review agent should inspect the diff as a production code reviewer. Ask it118to cover:119120- conflicts with existing behavior, public APIs, package/plugin manifests,121 install flows, docs, marketplace entries, and established repository patterns122- impact area: affected packages, commands, docs, tests, generated artifacts,123 user-visible behavior, and release or changeset implications124- correctness risks: regressions, broken contracts, missing edge cases,125 incomplete error handling, async/concurrency issues, and platform assumptions126- test risk: changed behavior without targeted coverage, stale snapshots, or127 verification that does not exercise the risky path128- maintainability risk: duplicated logic, unclear ownership boundaries, or129 changes that make future package integration work harder130- security and supply-chain risk: secrets, unsafe shelling out, untrusted input,131 dependency changes, permissions, tokens, and package publishing surfaces132- migration and rollback risk: config changes, persistent state, release tags,133 marketplace pointers, install commands, or behavior that is hard to undo134135## Evidence Standard136137Every finding must be actionable and evidence-backed:138139- include priority, file/line, affected surface, risk, and smallest fix140- explain the concrete failure mode or merge risk, not just a preference141- distinguish confirmed defects from hypotheses and unverified concerns142- label style-only or taste-only feedback as `P3` or a note143- avoid comments that only restate the diff or ask broad questions without a144 specific risk145146If a reviewer cannot verify a concern from the available context, they should147state what evidence is missing and which command or file would resolve it.148149## Escalation150151Ask for a domain expert or maintainer decision instead of overclaiming when the152change touches areas such as:153154- security, auth, tokens, private data, or permissions155- release automation, package publishing, versioning, changesets, or156 marketplace metadata157- installation flows, generated package contents, plugin manifests, or host-tool158 compatibility159- concurrency, async ordering, persistent state, migrations, or destructive160 commands161- broad architecture changes or ownership boundaries across packages162163## Severity Ratings164165Require every finding to include one priority:166167- `P0`: blocks release or can cause data loss, security exposure, widespread168 runtime failure, broken installs, or destructive behavior.169- `P1`: likely user-facing regression, broken supported workflow, incompatible170 package/API behavior, or high-confidence CI/release failure.171- `P2`: localized bug, missing important test, confusing behavior, or172 compatibility risk that should be fixed before merge.173- `P3`: low-risk cleanup, naming clarity, minor docs issue, or maintainability174 improvement that can reasonably follow later.175176Findings without a concrete risk should be reported as notes, not blocking177findings.178179## Review Agent Prompt Template180181Use a focused prompt like this:182183```text184Review the current uncommitted changes in <repo-path> as a code reviewer.185186Do not edit files or run mutating commands. Inspect git status, git diff, and187the relevant source/tests. Focus only on these in-scope files unless another188file is needed to understand a contract:189190<files>191192Original task:193<task>194195Verification already run:196<commands and results>197198First assess review readiness: scope clarity, unrelated changes, diff size,199missing verification, and any unexplained generated artifacts.200201Review in order: overall task and impact, main implementation and contracts,202tests, package/docs/manifests/generated files, then the rest of the in-scope203human-written changes.204205Review for conflicts with existing behavior, public APIs, package/plugin206manifests, install flows, docs, marketplace entries, and established repository207patterns. Assess impact area, security/supply-chain risk, rollback risk, and208release/changeset implications.209210Return findings first, ordered by severity. Each finding must include a P0-P3211priority, concrete file/line reference, affected surface, risk, and smallest212actionable fix. Prioritize bugs, regressions, broken contracts, missing tests213for changed behavior, release or packaging risks, and hidden compatibility214conflicts. If there are no findings, say that directly and list residual test215gaps or impact areas that were not verified. Escalate anything needing a domain216expert or maintainer decision instead of overclaiming certainty.217```218219## Reporting Shape220221When the agent returns, answer in a code-review style:222223- findings first, ordered by severity, each with `P0`-`P3`224- affected surface and impact area for each finding225- review readiness issues, if any226- escalation or maintainer-decision items, if any227- open questions or assumptions228- whether the reviewer found no issues229- verification status and remaining test gaps230231Do not bury real findings in a long summary. If you disagree with a reviewer232finding, state why and whether you verified the disagreement locally. Do not233make additional code changes after the review unless the user explicitly asks234you to fix the findings.