Use Smart Review

Get an agent’s assessment of branch changes, choose how to handle each finding, and send those decisions back for action.

Before you begin

Select a session with branch changes you want reviewed. Confirm its project and branch. Review actions can request code changes or create a GitHub issue, so choose the session that should receive that work.

Starting state: use a task branch with committed changes and an available review base. Smart Review instructs the agent to start from the committed branch diff and then read full changed files. Uncommitted work alone is not that branch diff; inspect it in the Diff tab with Compare set to Working changes.

The default review base is origin/main, with origin/master used when it is found instead. Unlike Diff’s broader fallback behavior, a fresh practice repository with no remote references does not automatically get a usable Smart Review base. If neither exists, ask the project maintainer how reviews are configured. Do not add or publish a remote just to finish the greeting exercise.

For a configured project, follow its commit policy to record the changes before starting this branch review. A commit alone does not push them. The example below assumes a finding about spaces-only coverage; a real review can produce different findings or none.

1. Start a review

On the prompt bar above the message box, select tools, then Smart review, then run review. Smart review appears only on a branch other than main or master. In Areas of Focus, describe the concerns that matter, then select Start Review. Follow progress in the Smart Review tab at the top of the session, which says No active review until one exists. For the greeting example:

Check blank-name handling and whether the tests cover spaces-only input.
Look for unintended changes to greetings for nonblank names.

Expected result: the review begins analyzing changes; findings may appear as it works. An empty panel alone does not establish a successful review. See empty and unsuccessful reviews below.

2. Evaluate a finding

Select a finding and read What, In practice, Impact, and Fix. Check its file location against Diff. A proposed fix still needs your judgment.

Use Add comment, then Save note to preserve relevant context. For example: “The input contract is strings only. Please investigate blank strings within that contract.”

3. Choose what should happen

Selecting an action records your choice. Selecting the same action again clears it. The choice alone does not dispatch the work.

Action	What you ask for when you dispatch it
Fix	Implement a fix for the finding
Explain	Read the relevant code and expand the explanation
Refine	Investigate the finding and improve its assessment
Rewrite	Clarify the finding’s wording while preserving its meaning; this is not a code rewrite
Issue	Create a GitHub issue for follow-up; the agent needs the relevant GitHub access
Won’t fix	Close the finding during Act without sending it to an agent

Example: if the reviewer finds missing spaces-only coverage, choose Fix. If you don’t yet understand why the case matters, choose Explain first. An explanation or refinement may leave a decision for you to make afterward.

Choose between Explain, Refine, and Rewrite

Use the same hypothetical finding: “Spaces-only names may not use the fallback.”

• Choose Explain when you need to understand the finding: “Trace the spaces-only input through the function and explain the result.” Check the added explanation against the code.
• Choose Refine when you question its accuracy: “The function already trims before choosing the fallback. Recheck whether this defect exists.” The requested investigation may correct or invalidate the finding; it does not ask for a code fix.
• Choose Rewrite when you accept the finding but its wording is confusing: “Explain the same problem in plain language, preserving the conclusion.” This requests clearer finding text, not a different implementation.

After the response, decide whether a Fix is still needed. A clearer explanation is not itself a code change.

4. Dispatch your decisions

1. Confirm the selected session and your choices across the findings.
2. Use Act in the review header, which appears once a finding has an action chosen and shows a count such as Act (1 fix), to dispatch eligible items. Its menu offers Act on items and Clear context and act.
3. Choose Act on items to send the work without requesting a context clear. Clear context and act requests a context reset before delivery; include necessary task constraints in finding comments if you use it.
4. Follow the review’s progress and the session’s conversation.

Expected result: eligible findings are queued for work after delivery succeeds. Items already queued, working, or done are not dispatched again by the same action. Pending Won’t fix items close without agent work.

If dispatch fails, inspect the error and current finding states before retrying. Some Won’t fix decisions may already have closed even if other work could not be sent. Do not treat a selected action or a queued item as proof that a fix succeeded.

Choose whether to clear context

Context includes the conversation available to the agent for its next response. Act on items sends the review work without requesting a clear. Use it when earlier discussion still matters.

Clear context and act first requests a fresh conversation context. For managed agents, Firehose clears the conversation history after the provider clear succeeds; some providers require a replacement session. The Claude terminal path sends /clear before review work. This does not undo repository edits or delete the saved review findings.

The new review request is built from the actionable findings and their comments. Put necessary constraints there before clearing, such as “Strings only; keep existing nonblank greetings.” Do not assume unrelated earlier chat messages will accompany the new request. Nor should you treat this control as a guarantee that provider-side transcript records are erased.

If the clear fails, inspect the error before retrying: the normal path does not send the review work when clearing fails. Confirm the active session if a replacement was created.

5. Verify the result

After work completes, inspect the updated diff and run the relevant checks. For the greeting example, check both spaces-only and nonblank inputs.

Use Check status on a finding to request another assessment after a fix. Read its response alongside your own checks. Use All findings to return to the list; Show all findings removes a severity restriction when that control is available.

Follow one finding through to evidence

For a finding about a missing spaces-only test, choose Fix, add the strings-only constraint, and use Act on items. After the work returns, open greeting.test.mjs in Diff and confirm it tests " " against "Hello, guest!". Run node --test in that workspace and check all four greeting cases. Then request Check status and read the assessment. This is an illustrative sequence; inspect the actual result instead of expecting fixed agent wording.

If the review is empty or unsuccessful

• Analyzing branch changes… means analysis is still in progress. Check the selected session’s Chat for activity or a reported problem.
• No … findings can be a severity filter result. Select Show all findings before deciding the review is empty.
• A failed review can show its error in the empty panel. Keep that error and check the session before starting another review.
• A completed review with no findings means none were reported. It does not establish that tests passed or every defect was ruled out. Verify the diff and checks anyway.

Finish with the task handoff and cleanup checklist.