review-loop
Skill42 starsChanged 22 days agoMITView on GitHub
Runs a multi-round human review loop over a long AI-written document (spec, plan, report, proposal) without drift between versions. Use whenever the user is reviewing a draft you produced and wants changes, says things like next version/v2/v3, I recorded my feedback/here's the transcript, revise this section, review section by section, review my draft, next revision — and whenever a document will go through more than one round of feedback. Also use before publishing a final version, to prove nothing agreed-on silently disappeared.
59 other projects use a version of this.
Adopted by
Most recently taken up by
- DaraBoth/skilljmskilltheir own version, first seen Nov 15, 2026
- sp-hk2ldn/SKILLStheir own version, first seen Nov 15, 2026
- HerbertGao/herbertgao-skillstheir own version, first seen Nov 15, 2026
- fullstackhouse/skillstheir own version, first seen Nov 15, 2026
- revisit-studies/studytheir own version, first seen Nov 9, 2026
- Mmbugraaslan/motion-plustheir own version, first seen Nov 8, 2026
Used with
Projects with it also use motion-design, polish and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
soilmassSkillmotion-design
Create animations and motion graphics using industry standards. Use when asked to animate UI elements, create video content, implement transitions, or build motion systems. Implements W3C Design Tokens, Material Design 3 baseline, and Lottie specification compliance.
Also in 5 projects that use this
HK-hubSkillpolish
Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.
Also in 3 projects that use this
GoogleSkillto-spec
Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
Also in 4 projects that use this
GoogleSkillimprove-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
Also in 5 projects that use this
AWSSkillship
Finalize dev work on an issue branch — update docs, push, and open a PR.
Also in 4 projects that use this
MicrosoftSkillcouncil
Convene the persona panel — six orthogonal review lenses — on a target. Cold independent fan-out, debate-to-consensus, synthesized verdict with recorded dissent and a roster manifest.
Also in 3 projects that use this
- +4 more from google
Other versions59 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 59
- didi/mpx★ 4ksame name
- blockscout/frontend★ 310same name
- microsoft/bocpy★ 184same name
- 9thLevelSoftware/legion★ 76same name
- microsoft/Trieste★ 53same name
- revisit-studies/study★ 46same name
- timharris707/skills★ 44same name
- spxrogers/agentsync★ 41same name
- Latand/delegatus★ 39same name
- mathruffian-dot/claude-motion-explainer★ 30same name
49 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- checkpointSkill
- explainSkill
- first-principlesSkill
- humanizerSkill
- phantom-pushbackSkill
- politeSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 9 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 52 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Not because it wasn't careful enough.
- Very specific: line 68
When the user says a section is approved, that content's hash is recorded at that instant.
- Distinctive: line 85
If a piece of feedback can't attach to any block id, it's usually not asking for one section to change -- it's saying the whole shape of …
- Distinctive: line 100
Every block has to be understandable on its own.
- Distinctive: line 140
Typing: every block on the review page has an input box.
- Distinctive: line 150
Don't just hand over a new document when you're done.
- Distinctive: line 160
Prefer analogies over definitions.
- Distinctive: line 164
When archiving old versions, the final version can't point at any of them.
- Very specific: line 166
Run check once before archiving.
- Distinctive: line 168
Put a short note in the archive folder covering three things: why each version got superseded, where the original basis for each decision …
- Distinctive: line 175
It doesn't dictate the shape of a feedback summary: Every comment just needs to trace to an id, say what was done about it, and show what's …
“Common” is measured: kept by at least 6 in 10 of the 52 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review Loop
A person has to put their name on a long document they didn't write, and their attention is limited. This skill does exactly one thing:
Make the number of changes that actually happened equal the number of changes the reviewer actually saw.
Drift is defined as those two numbers not matching. Something changed, or an entire section vanished, and the reviewer never knew -- that section wasn't rejected, it never entered anyone's field of view.
When to use this
The user is reviewing a long document you wrote, and there will be a second round. The moment a second round shows up, drift starts.
Skip it for a one-off short reply. Skip it for a single-pass final draft.
Why discipline alone doesn't work
This skill exists because of a real failure. A long spec went through four rounds, and:
- A whole section disappeared between revisions and nobody noticed
- Section numbers shifted across the board -- "Section 4" in v1 and "Section 4" in v2 were different things
- A section that had already been verbally approved got its heading changed, a new subsection inserted, and was renumbered afterward, without the approver knowing
An independent AI was later dispatched to diff the versions. It found 9 smaller omissions, and completely missed the vanished section.
Not because it wasn't careful enough. It's that "used to be there, isn't now" doesn't exist in prose -- there's nothing left to read. Catching that requires the document to have structural identity, and it has to be computed, not read.
So: don't ask an AI to "go find anything missing." Give the machine a ratio with a denominator.
Seven rules
1. Every block gets a permanent id
Mark a line in the markdown:
<!-- @block timeline -->
## Timeline
body...The id is assigned once, at birth, and can never change after that. The heading can change, the order can change, the body can be rewritten entirely -- the id follows that block of content.
Displayed numbering is generated by the tool. Never hand-write section numbers. Hand-written numbers always drift.
2. Removal is a declaration, not a deletion
To take a section out, don't just delete it:
<!-- @block old-section removed: folded into timeline, this call no longer applies -->It renders greyed out with a strikethrough, still in place. Leaving it there is how you can see it was taken out.
3. Change is computed by the machine, not remembered by a person
Running check computes coverage -- how many of the previous version's blocks can be found in this version. Lose one block and the ratio drops; no one has to "notice" it. The default threshold is 100%.
Status (new/edited/unchanged/approved/removed) is computed too, by comparing content hashes -- never hand-filled. Hand-filled fields get forgotten.
4. Approval freezes
When the user says a section is approved, that content's hash is recorded at that instant. If it's edited afterward while its status still says "approved," check blocks it outright.
Approval isn't a sentence. It's a lock.
5. Feedback attaches to an id; the user picks the intent
Each block gets one comment box, plus an intent: Approve / Revise / Question / Discuss.
- Pick Revise: do it, don't argue back, don't try to talk them out of it
- Pick Question: answer it, don't touch the document
- Pick Discuss: this is the only mode where you push back if you disagree
- Pick Approve: freeze it
Don't default to labeling things "I agree / I disagree." Whether to argue is the user's call in the moment, not yours. If they say revise, revise.
6. Feedback that can't attach to any id is a structural problem
If a piece of feedback can't attach to any block id, it's usually not asking for one section to change -- it's saying the whole shape of the thing is wrong.
- "The materials table has the wrong session number" → attaches cleanly to
materials, just fix it - "This won't sell" / "every section feels like it's missing the payoff" → doesn't attach to any single block, because it's talking about the whole thing
If it attaches to an id, just do it, don't argue. If it doesn't, stop.
Stopping means: state what you think they're actually pointing at, ask if that's right, get confirmation before touching the structure. Don't patch it section by section on your own -- patching produces patches, they'll still feel it's wrong afterward, and you'll have burned a whole round.
Real example: a spec broken into multiple phases got the feedback "every phase drags on, this won't sell." Patching section by section would have meant tweaking the content of each phase. The right move was to go back and ask "should this be phased at all?" -- the answer was to collapse the whole thing into a single phase. That one change improved things more than every other round combined.
This is also the test for "should I push back": feedback that attaches to an id doesn't need debate. Feedback that doesn't is the only kind worth debating.
7. No implicit inheritance, ever
Every block has to be understandable on its own. Never write "same as the previous version," "see the previous section," "same as v2, can be skipped."
That kind of reference rots after a revision or an archiving pass -- once the historical version gets filed away, the "final" copy is crippled. check catches this kind of wording.
What one round looks like
you write/revise the document (with @block ids)
↓
render → review page (one comment box + intent picker per block, only changed ones need attention)
↓
user reviews (recording or typing, see below) → one-click copy the feedback
↓
apply → updates state, freezes approvals, prints the to-do list
↓
you revise → check passes → hand over the next version
↓
ship it with a plain-language summary of what changed (see below)Commands
The first time, confirm the path is right -- wherever the skill is installed, the script lives under that install's scripts/.
python3 ~/.claude/skills/review-loop/scripts/review_loop.py render spec.md # produce the review page
python3 ~/.claude/skills/review-loop/scripts/review_loop.py check spec.md # pre-publish gate, exits non-zero on problems
python3 ~/.claude/skills/review-loop/scripts/review_loop.py apply spec.md feedback.txtFeedback format (the review page's "Copy" button produces exactly this):
[timeline] Approve
[materials] Revise — the materials table says "second and third session" but the second session has no tool log
[format] Discuss — I think this framing needs more thoughtTwo ways to give input, one path from there
Typing: every block on the review page has an input box; fill it in, click copy, paste it back.
Recording: works well for long documents and for thinking out loud -- an hour of recording can cover feedback on dozens of blocks, much faster than typing, and it's easier to stay in flow. Transcribe it and paste the transcript back in.
This skill doesn't care what tool you use to transcribe -- a local model, a cloud API, or a transcript you already made yourself, any of those work. But there are two rules that have nothing to do with which tool you pick and everything to do with not losing content; see references/transcription.md.
Once you have the transcript, your job is to map the scattered spoken feedback onto block ids, then act on it. If a comment doesn't map to any id, ask which section it means -- don't guess.
Delivery: every round needs a plain-language summary
Don't just hand over a new document when you're done. A change nobody can understand is a change nobody saw -- in the "changes the reviewer actually saw" numerator, it's a zero.
So every round, attach a short plain-language summary covering three things:
- What you said, and what I did about each point
- What I didn't do, and why
- What's still unresolved
When writing it: no jargon, no unexplained abbreviations, no mixing in technical shorthand that only makes sense to you. If a term genuinely has no plain equivalent, add a short parenthetical explaining it. Lead with the conclusion and what it means for them, details after. Better to say less and be clear than to cram in every detail -- when something's hard to follow, the usual cause is saying too much, not too little.
Prefer analogies over definitions. One idea per sentence.
Wrap-up: the final version has to stand alone
When archiving old versions, the final version can't point at any of them.
Run check once before archiving. It catches "same as v2"-style wording -- that's exactly where a document goes stale.
Put a short note in the archive folder covering three things: why each version got superseded, where the original basis for each decision lives (transcript, source document), and what this diff pass found.
What this skill deliberately doesn't do
These are excluded on purpose. Adding them back is over-engineering:
- It doesn't build a transcription system. That's an input, not the core of this.
- It doesn't dictate the shape of a feedback summary. Every comment just needs to trace to an id, say what was done about it, and show what's still open.
- It doesn't force an agree/disagree label. Depends on what the user wants in the moment (rule 5).
- It doesn't dictate a round count, or stage a "final version" ceremony. When it converges, it converges.
- It doesn't build a diff viewer. Greyed-out + "changed this round" is enough; don't turn this into a code-diff tool.
- It doesn't dispatch an AI to hunt for omissions. Already proven not to work. Use coverage instead.
Optional flags
--strict-numbers: promotes "the same number appears in more than one block" from a warning to a failure. The same fact written in two places will eventually drift into two different stories (real example: one document said an event was free in one section and paid in another). Worth turning on when the document has prices, dates, headcounts, or other numbers that get quoted elsewhere.--min-coverage: loosens the coverage threshold. Default is 1.0, not recommended to lower -- lowering it is the same as allowing things to vanish silently.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

