guided-review

Guided review as an inline artifact

A big diff in file order makes a reader jump between files for half an hour to learn what the change even does. A guided review does that work for them in a minute: what the change is, how control now flows through it, what changed in its contracts — types, signatures, endpoints — and then its ideas in chapters, most important first, each beside the code that shows it. A reader learns a change from its calls and its contracts, not from its list of files; the diff viewer already has that list.

Build it as one html artifact shown inline: the chat draws it right in your reply at its full height, laid on the chat's own surface. You write its files with the artifact tools, patching them with edit_artifact_file as you would any other file, and every tool call that changes it makes a new version the chat follows in place. Everything it quotes comes from the real change, through Happy's standard components; you never copy code into it by hand.

The pieces

Make the artifact first, then give it two files.

1. create_artifact with type: "html", a short title ("Review: crop before upload"), and display: "inline_expanded". It returns the artifact's id.

2. changes.diff — the change itself, written by git, never by hand. Write it to a scratch file inside your working directory with the shell, then publish it with update_artifact and files: [{ "fromPath": ".context/changes.diff", "path": "changes.diff" }]:

   mkdir -p .context && git diff <base> > .context/changes.diff
   # New files are part of the change too.
   git ls-files --others --exclude-standard -z \
     | xargs -0 -I{} git diff --no-index /dev/null {} >> .context/changes.diff
   

   For a committed range use git diff <base> <head> and nothing else. For an explanation of code that did not change, skip the diff and publish the real source files with update_artifact and files: [{ "fromPath": "src/app.ts", "path": "src/app.ts" }]. Quote their lines with <happy-code>.

3. index.html — the review, written with write_artifact_file, in this order: the standard styles, your few lines of CSS, the HTML, and the components script last.