# Human Review > Produce a plain-English review of the files you just edited and gate the changes behind an explicit Approve/Undo choice. Use when the Stop hook from the human-review-skill plugin asks for a review (you'll see a prompt referencing an edit log), OR when the developer's most recent message is "1", "2", "approve", or "undo" in reply to a previous review. - Skill: `irtezaasadrizvi/human-review` (Agent Skill) - Install (CLI): `npx skillmds@latest add irtezaasadrizvi/human-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/irtezaasadrizvi/human-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: IrtezaAsadRizvi (https://skillmd.com/u/irtezaasadrizvi) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/irtezaasadrizvi/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: ```markdown ## 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** - --- **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) ```markdown ## 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 `. Reply once: "Approved." | | `2`, `undo`, `no` | Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/undo.sh `. 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 `` 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.