Review an agent’s change before accepting it

# Apply the “Review an agent’s change before accepting it” guide in your agent

## Objective
Compare the requested outcome with the actual patch and its observable behavior. Inspect sensitive boundaries such as permissions, persistence and outgoing data. Use an independent review for consequential changes, while keeping feedback tied to reproducible defects and distinguishing accepted code from a published, verified result.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Review behavior, scope, data effects and evidence rather than trusting a summary or green checks alone.
- Preserve the correct decisions already in place.

## Guide steps
- 1. Start with the requested contract — Write the expected change in one sentence and list preserved behavior. Compare this with the diff and file list. A polished summary can omit an unrelated dependency or a changed default. Ask why each new dependency, endpoint or persistent field is necessary. Do not reject them by size alone; evaluate the new behavior and maintenance surface against the task.
- 2. Review risk boundaries — Check whether a formerly local action now sends data, a permission became broader or a retry can repeat a side effect. Read the changed failure path, not only the happy path screenshot. For storage, inspect compatibility with existing saved values. For UI, inspect focus and recovery. For generated content, confirm the source changed and the artifact was regenerated rather than editing derived bytes alone.
- 3. Example: a retry button — A patch adds retry after a failed save. Review whether failure means rejected, disconnected or unknown outcome. Replaying every request can duplicate an operation already accepted by the server. Request one focused demonstration: lost response after server acceptance. The expected outcome is reconciliation or explicit uncertainty, not merely a second green notification.
- 4. Make feedback actionable — State the trigger, observed consequence and expected behavior, with a file or journey reference. Distinguish a release-blocking defect from an optional style preference. Keep the reviewer read-only when another agent owns the patch. A reviewer’s approval is evidence of that review, not a security certificate. Missing coverage should be named precisely rather than demanding unrelated test campaigns to eliminate all uncertainty.
- 5. Accept the right delivery state — Verify that checks apply to the current commit. After fixes, rerun affected checks; do not reuse an earlier green result for changed behavior. Record remaining limitations and the publication boundary. A merged PR, successful deployment and working public journey are distinct. For a local-only task, stop at the authorized boundary instead of publishing just to complete a checklist.

## Acceptance criteria — Verify in your product
- The diff matches the request.
- Unrelated changes are identified.
- Sensitive boundaries are reviewed.
- Failures have observable checks.
- Checks apply to current bytes.
- Approval does not overclaim deployment.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Anchor the guide in the project

## Objective
Turn the applied steps into durable repository conventions.

## Checks
- Link each decision made to the guide step that justifies it.
- Add the checklist to the relevant reviews.
- Record out-of-scope cases for the neighboring guides.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:aa9865ef3002709baa747ccfdfaa5d115290846a0e0986608237b6651c759e7b

# Diagnose a failed application of the “Review an agent’s change before accepting it” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. Start with the requested contract — Write the expected change in one sentence and list preserved behavior. Compare this with the diff and file list. A polished summary can omit an unrelated dependency or a changed default. Ask why each new dependency, endpoint or persistent field is necessary. Do not reject them by size alone; evaluate the new behavior and maintenance surface against the task.
- 2. Review risk boundaries — Check whether a formerly local action now sends data, a permission became broader or a retry can repeat a side effect. Read the changed failure path, not only the happy path screenshot. For storage, inspect compatibility with existing saved values. For UI, inspect focus and recovery. For generated content, confirm the source changed and the artifact was regenerated rather than editing derived bytes alone.
- 3. Example: a retry button — A patch adds retry after a failed save. Review whether failure means rejected, disconnected or unknown outcome. Replaying every request can duplicate an operation already accepted by the server. Request one focused demonstration: lost response after server acceptance. The expected outcome is reconciliation or explicit uncertainty, not merely a second green notification.
- 4. Make feedback actionable — State the trigger, observed consequence and expected behavior, with a file or journey reference. Distinguish a release-blocking defect from an optional style preference. Keep the reviewer read-only when another agent owns the patch. A reviewer’s approval is evidence of that review, not a security certificate. Missing coverage should be named precisely rather than demanding unrelated test campaigns to eliminate all uncertainty.
- 5. Accept the right delivery state — Verify that checks apply to the current commit. After fixes, rerun affected checks; do not reuse an earlier green result for changed behavior. Record remaining limitations and the publication boundary. A merged PR, successful deployment and working public journey are distinct. For a local-only task, stop at the authorized boundary instead of publishing just to complete a checklist.

## Possible causes
- A step was skipped or executed out of order.
- The actual need falls outside the guide scope.
- A checklist criterion was never verified.

## Bounded fixes
- Redo only the diverging step and what depends on it.
- Document the gap if the guide scope does not cover the need.

## Final verification — Verify in your product
- The diff matches the request.
- Unrelated changes are identified.
- Sensitive boundaries are reviewed.
- Failures have observable checks.
- Checks apply to current bytes.
- Approval does not overclaim deployment.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Prevent the next drift

## Objective
Turn the first diverging step into an explicit project check.

## Checks
- Add a focused check on the step that diverged.
- Verify the checklist on a second real case.
- Document the scope limit you hit.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:d7d28688f191f48a11ea19f2526d37b135852b3a18792c360576f6cf23a0b488