Human Review

Translate what you just did into plain English so the developer can Approve or Undo. Be brief. Every extra sentence costs tokens.

When to run

Exactly two situations:

1. Review trigger. The Stop hook injected a prompt telling you to invoke human-review. The prompt includes a path to edit_log.jsonl and a session_id. You must produce a review before stopping.
2. Reply handling. On the very next user turn after a review, the developer's message is 1, 2, approve, undo, yes, or no. Run the matching script and nothing else.

Otherwise, don't invoke this skill.

Step 1: Document what you changed

Before writing the review, add brief doc comments to new or materially-changed classes, functions, methods, exported symbols, and non-obvious config blocks in the files listed in edit_log.jsonl. The goal is a glanceable note, not prose.

Comment style by language

Rules

• Keep it to 1 line (max 2 if a non-obvious param/return matters). One short sentence on what this is for, not how it works.
• Only touch symbols you added or meaningfully changed this turn. Don't document the whole file.
• Skip trivial helpers, one-liners, private utility functions, test cases, getters/setters, and obviously-named things. A 3-line formatDate doesn't need a JSDoc.
• Don't duplicate the signature. "Adds two numbers" on add(a, b) is noise.
• Don't overwrite existing comments unless they're now wrong. If a symbol already has a docstring/JSDoc, leave it alone.
• Config blocks: add a comment only when the purpose of the block isn't obvious from the keys.
• No emojis, no TODOs, no author tags, no dates.

If a file has nothing worth documenting under these rules, skip it. Don't force comments.

Step 2: Writing the review

Read edit_log.jsonl for the file list. Produce exactly this structure:

## Review: what I just did

**What changed**
- `path/to/file1.py`: <≤12 words on the edit>
- `path/to/file2.ts`: <≤12 words on the edit>

**Why**
<1 sentence. Only add a second if a non-obvious assumption needs flagging.>

**Worth a second look**
- <one line per real risk: new dep, secret/config, deletion, auth/crypto, SQL, shell exec, network, migration, unsnapshotted file>

---
**1. Approve**: accept these changes.
**2. Undo**: revert all files this turn.

Hard rules

• Target 60–120 words total. Hard cap 200. If you're over, cut.
• One short line per file. Summarize the goal, not each chunk.
• Skip "Worth a second look" entirely if nothing is risky. Don't pad. No "N/A", no "nothing to flag".
• Skip "Why" if the prompt was literal (e.g. "add a print statement", "rename X to Y"). Omit the whole section.
• No preamble, no recap of the prompt, no closing commentary. The template above is the whole message.
• Never drop the 1/2 closing block. It must appear verbatim.
• Flag invisible risks only. Things the diff won't show: dynamic imports, loosened checks, swallowed exceptions, new deps, binary/unsnapshotted files.

Example (terse)

## Review: what I just did

**What changed**
- `src/auth/session.py`: session cookie SameSite=Lax → Strict, added Secure flag.
- `tests/test_auth.py`: two cases for the new flags; fixture expects `secure=True`.

**Why**
Read "tighten cookie handling" as CSRF hardening. Strict will break cross-site embeds; I assumed you have none.

**Worth a second look**
- Strict breaks OAuth redirects landing on your domain.
- Secure drops cookies on plain-HTTP localhost dev.

---
**1. Approve**: accept these changes.
**2. Undo**: revert all files this turn.

Handling the developer's reply

On the turn after a review, match the message (case-insensitive, trimmed):

Use the exact <session_id> from the Stop hook prompt. ${CLAUDE_PLUGIN_ROOT} is set by Claude Code.

After approve or undo

• No second review this turn. State is cleared.
• No proactive edits. Wait for the next prompt.
• If undo.sh warns about unsnapshotted files, surface the warning plainly.