AI-diff review (the /changes/ workflow) · Documentation

Generate a /changes/ page from your latest changes and let reviewers approve, reject, or rewrite each one, on the review page or the page where it lives.

After a content rewrite, redesign, or major copy refresh, you want reviewers to decide on every change individually, not skim a giant diff. The PinAppAI AI-diff review workflow turns your work into a per-item review surface: a /changes/ page with Before/After cards, plus in-page review on the very pages the changes live on.

How it fits together

your AI agent applies changes (apply workflow)
   │
   ├── edits source
   ├── writes/refreshes the /changes/ page
   └── registers every item with PinAppAI
   │
   │  Reviewer visits /changes/ OR any source page
   ▼
   • /changes/ → per-item Approve/Reject/Request-change cards + summary
   • source page → review chip + decision panel + cross-page navigation

Registration happens automatically as part of the apply/generate run: there is nothing to warm up and the page itself never writes anything.

1. Generate /changes/

Most of the time you don’t generate it by hand: the apply workflow refreshes /changes/ automatically after every round. For a first-time page (or a standalone rewrite review), run the generate-changes-page workflow in your AI client (how), or copy the ready prompt from the dashboard’s InReview tab (Copy /changes/ prompt).

The generated page is a single self-contained file:

One card per atomic change: reviewers decide each one independently
Each card carries the CR’s #N number, the same identity the dashboard and the on-page pin show
BEFORE / AFTER text rows, byte-faithful to your source
All CSS inlined; no site chrome: one file to deploy, one file to delete

The AI generator never modifies your source files while generating. /changes/ is the only artifact it writes.

2. Deploy + decide

Commit and deploy /changes/ like any other page. Reviewers see a summary header, and per card:

✓ Approve: accept the applied wording
✗ Reject: the next Apply run reverts this change
↻ Request change: type the wording you actually want; the next Apply applies it

Two small icons next to each card heading open the change in context: one on the site itself, one through the no-install review link. The latter works even on pages without the widget embedded.

Decisions persist on PinAppAI’s servers, scoped to the reviewer’s verified email.

3. Review on the actual page (in-page mode)

When a reviewer visits a source page that has pending changes, a chip appears bottom-right:

16 changes to review on this page

Click → a draggable panel opens with the changed text highlighted in place, BEFORE/AFTER rows, the verdict buttons, and ◀ ▶ navigation that walks every pending item, even across pages. Applied-but-undecided changes glow green on the page; deciding removes the glow.

If the round you’re reviewing lives on a preview deploy (branch preview), review entries take you there automatically: you always verdict on the content that actually contains the change.

On pages without their own items, the chip shows the project-wide count and jumps you to the first pending item anywhere on the site.

4. Apply the verdicts

Run the apply workflow again. Rejected items are reverted to their original wording, change requests get the reviewer’s literal text, and /changes/ regenerates to match. Approved items close. The full state model is documented in the iteration loop.

5. The iteration boundary marker

Every apply run writes .pinappai/last-applied.json with the run’s timestamp. The next /changes/ generation reads it and scopes the diff to “what changed since the last apply”: reviewers only ever see the new round, not cumulative history.

If you decline the /changes/ page offer during an apply run, the marker records that the batch is still waiting for a review page. Running the generate-changes-page workflow later picks that batch up automatically, so nothing you applied goes unreviewed.

Commit .pinappai/last-applied.json together with the source changes of each run (your AI agent stages it for you and asks before committing). .pinappai/context.json (project binding) lives next to it. Both are tiny, commit them.

Preparing for production

When you ship and want all review markup gone from the customer-facing build, run the remove workflow in your AI client: it strips the widget tag, deletes /changes/, verifies with git grep, offers to disable the review link, and asks before committing. The .pinappai/ directory is preserved by design so a later re-install lands on the same baseline.