human-review

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

| Language | Style | | -------------------------------- | ------------------------------------- | | TypeScript / JavaScript | JSDoc /** ... */ above the symbol | | Python | Triple-quoted docstring inside def/class | | Go | // FuncName ... line above | | Rust | /// ... lines above | | Java / Kotlin / PHP / C# | JavaDoc-style /** ... */ | | Ruby | # lines above | | Shell / YAML / TOML / Dockerfile | # line above the block |

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):

| Reply | Do | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | 1, approve, yes | Run bash ${CLAUDE_PLUGIN_ROOT}/scripts/approve.sh <session_id>. Reply once: "Approved." | | 2, undo, no | Run bash ${CLAUDE_PLUGIN_ROOT}/scripts/undo.sh <session_id>. Paste the script output. Surface any warnings. | | Anything else | Treat as a new prompt. Don't run either script. The next edit auto-clears prior review state (implicit approve). |

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.