Foresee this solution before they approve it. Show what would change, and what they should expect, as a file tree of git-like red and green lines, as if the PR is ready and they are reviewing the changes tab.
The page is for them or a product reader. They are not looking to deep-dive the code.
Mark each part of a file with a blue @@ section @@ line. Indent the way a
diff would. Write a sentence when the behavior is the point. Write a short
code line when that is easier to read than the sentence. Do not paste the
surrounding implementation.
Open it for review
Copy template.html to <plan-name>-plan-review.html next to
the plan file, or in the repo root when the plan lives only in the chat. Fill
every {{TOKEN}}.
Serve it in the background with scripts/review_server.py beside this file:
python3 <skill-dir>/scripts/review_server.py <plan-name>-plan-review.html
It opens the page and prints the URL and the review file path. Comments save
to <plan-name>-plan-review.json next to the page as the reader writes them.
Wait for the verdict
Ask one question with three options: Approve, Commented, Rejected. Use your question tool if you have one. Otherwise ask in chat and end the turn.
When they answer, read the review file. It has an overall summary and
comments. Each comment has a body and the places it points at: file,
lines, and the quote they selected. One comment can point at several
lines, or at places in several files. A file of null is the page header.
- Approve: the plan stands. Fold in any comments, then stop the server. Do not start implementing unless they ask.
- Commented: answer each comment in chat, change the plan where a comment
asks, and rewrite the page. Rename the review file to
<plan-name>-plan-review-<round>.json, ask them to refresh the tab, and ask again. - Rejected: read the comments for why. If there are none, ask what is wrong. Do not rewrite the page until the direction is clear. Stop the server.