review
Skill4 starsChanged 2 months agoMITView on GitHub
Review the changes since a fixed point along three independent axes — Standards (does the code follow this repo's documented conventions and avoid known smells?), Spec (does it do what the issue/PRD asked?), and Architecture (does the change belong in the system and raise its evolvability — working with the grain of the existing seams, domain model, and layers to leave the architecture cheaper to change next — rather than lowering it?). Runs three parallel sub-agents that never share context and reports them side by side. The strongest architectural opportunity gets a concrete follow-up the operator can run. Use when the user wants to review a branch, a PR, or work-in-progress changes, or asks to "review since X".
192 other projects use a version of this, 3 of them edited.
Adopted by
Most recently taken up by
- dzhng/skillstheir own version, first seen Nov 15, 2026
- muxy-app/muxytheir own version, first seen Nov 15, 2026
- macro-inc/macrotheir own version, first seen Nov 15, 2026
- yagizdo/quivertheir own version, first seen Nov 15, 2026
- markmhendrickson/neotomatheir own version, first seen Nov 15, 2026
- felipeam86/pipe-skillstheir own version, first seen Nov 15, 2026
Used with
Projects with it also use close-spec, design-with-images 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.
dzhngSkillclose-spec
When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).
Also in 5 projects that use this
dzhngSkilldesign-with-images
Explore UI and visual design with image generation, then iterate the real implementation against the user-selected concept. Use when brainstorming visual directions, offering mockup variants, or implementing an approved generated design; do not stop at the mockups or the first code approximation.
Also in 5 projects that use this
LambenthanSkilldaily-arxiv
每日从 arXiv 拉取新论文,过滤相关性,auto-ingest 高优先级论文,检测 SOTA 更新
Also in 5 projects that use this
LambenthanSkillexp-eval
实验判决门:Review LLM 独立评判实验结果 → 4 种判决路径 → 自动更新 claims confidence、ideas status、graph edges
Also in 5 projects that use this
- +3 more from dzhng
- +5 more from Lambenthan
Other versions192 projects use a version of this.
Word for word · 0
None found.
Edited · 3
- InditexTech/weavejs★ 26624% same
- gaia-research/gaia-skill-tree★ 2232% same
- metrogg/AgentHub★ 1924% same
Wrote their own version · 189
- garrytan/gstack★ 142ksame name
- ansible/ansible★ 71ksame name
- docling-project/docling★ 71ksame name
- traefik/traefik★ 66ksame name
- ClickHouse/ClickHouse★ 51ksame name
- temporalio/temporal★ 24ksame name
- ccch1mneyyy/dsh-Go★ 24ksame name
- tisfeng/Easydict★ 15ksame name
- juicedata/juicefs★ 15ksame name
- elie222/inbox-zero★ 13ksame name
179 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 repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-voiceSkill
- babysitSkill
- changelogSkill
- commitSkill
- desert-modeSkill
- dispatchSkill
- handbackSkill
- handoffSkill
- mailboxSkill
- open-prSkill
- quickchartSkill
- session-usageSkill
- spawnSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 157 edited versions we read keep these.
2
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
- Very specific: line 50
Use the general-purpose sub-agent for all three.
- Distinctive: line 75
If the spec is missing, skip this sub-agent and note it in the final report.
- Very specific: line 117
If the Architecture axis returned an Opportunity: naming a real deepening or code-judo move — one bigger than this change should swallow …
- Distinctive: line 143
Don't flood the review with low-value nits when there are structural issues.
“Common” is measured: kept by at least 6 in 10 of the 157 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
Three-axis review of the diff between a fixed point the user supplies and HEAD:
- Standards — does the code conform to this repo's documented conventions, and does it steer clear of the smell baseline below?
- Spec — does the code faithfully implement the originating issue / PRD / spec?
- Architecture — does the change go with the grain, keeping the system coherent and cheaper to change — or cut across it?
Each axis runs as a parallel sub-agent so they don't pollute each other's context, then this skill aggregates their findings. The separation is the point: a change can pass one axis and fail another, and a single reviewer collapses them.
Process
1. Pin the fixed point
Whatever the user said is the fixed point — a commit SHA, branch name, tag, main, HEAD~5, etc. If they didn't specify one, ask for it.
Capture the diff command once: git diff <fixed-point>...HEAD (three-dot, so the comparison is against the merge-base). Note the commit list via git log <fixed-point>..HEAD --oneline.
Confirm the fixed point resolves (git rev-parse <fixed-point>) and the diff is non-empty before going further. A bad ref or empty diff fails here — not inside three parallel sub-agents.
2. Locate the inputs (do this once, hand to the sub-agents)
- Spec source, in order: issue refs in commit messages (
#123,Closes #45) → a path the user passed → a PRD/spec underdocs/,specs/,.scratch/matching the branch → else ask; if there is none, the Spec axis skips and reports "no spec available". - Standards sources:
CLAUDE.md,AGENTS.md,CONTRIBUTING.md,CONTEXT.md,docs/adr/(ADRs are standards), anySTYLE.md/STANDARDS.md. Note machine-enforced config (.editorconfig,eslint,tsconfig,biome,prettier) but tell the agent NOT to re-check what tooling already enforces. - Architecture inputs:
CONTEXT.md— the domain model that names the system's real concepts and good seams — anddocs/adr/, the decisions that fix where the architecture is heading. The Architecture axis needs both:CONTEXT.mdto tell a canonical concept from a reinvented one, ADRs to tell a course-correction from a violation.
3. Spawn three sub-agents in parallel (one message, three Agent calls)
Use the general-purpose sub-agent for all three. Each brief carries everything the agent needs — the agents share no context with each other or with you.
Standards brief — include the diff command, the commit list, the standards-source files from step 2, plus the smell baseline below pasted in full (the agent has no other access to it):
Report — per file/hunk — (a) every place the diff violates a documented standard: cite the standard (file + rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words, structural findings first, nits last.
Smell baseline (Fowler, Refactoring ch.3 — each reads what it is → how to fix):
- Mysterious Name — a name that doesn't reveal what it does/holds. → rename; if no honest name comes, the design's murky.
- Duplicated Code — the same logic shape in more than one hunk/file. → extract the shape, call it from both.
- Feature Envy — a method reaching into another object's data more than its own. → move it onto the data it envies.
- Data Clumps — the same few fields/params travelling together. → bundle them into one type, pass that.
- Primitive Obsession — a primitive standing in for a domain concept. → give the concept its own small type.
- Repeated Switches — the same
switch/if-cascade on the same type recurs. → polymorphism, or one shared map. - Shotgun Surgery — one logical change forces scattered edits. → gather what changes together into one module.
- Divergent Change — one module edited for several unrelated reasons. → split so each changes for one reason.
- Speculative Generality — abstraction/params/hooks for needs the spec doesn't have. → delete it; inline until a real need shows.
- Message Chains — long
a.b().c().d()the caller shouldn't depend on. → hide the walk behind one method. - Middle Man — a class/function that mostly just delegates onward. → cut it, call the real target direct.
- Refused Bequest — a subclass ignoring most of what it inherits. → drop the inheritance, use composition.
Spec brief — include the diff command, commit list, and the spec path/contents:
Report: (a) requirements missing or partial; (b) behaviour not asked for (scope creep); (c) requirements that look implemented but wrong. Quote the spec line for each finding. Under 400 words.
If the spec is missing, skip this sub-agent and note it in the final report.
Architecture brief — include the diff command, commit list, the CONTEXT.md domain model, the ADR list, plus the depth vocabulary below pasted in full:
The diff is your starting point, not your bounds — judge how the change sits in the whole system: does it keep it coherent and cheaper to change, or cut across the grain? Adding capability is fine — deepening a module or opening a clean seam raises evolvability; flag those that lower it, ranked by impact:
Fit — one coherent source of truth, or a second that drifts? A domain concept reinvented under a name
CONTEXT.mdowns; a bypass around the canonical flow; logic in the wrong layer; a change contradicting an ADR (surface only if it warrants reopening).Shape — deep module, load-bearing seam? A shallow module — pass-through or forwarding wrapper; confirm with the deletion test. New behaviour behind no seam — untestable in isolation.
Direction — cheaper next time, or dearer? A code-judo move that folds the change into an existing deep module and deletes a branch / helper / layer. A change that scatters — a file past ~1,000 lines, conditionals wanting a typed dispatch, or magical code where boring reads better.
Tier each Blocker / Concern / Nit, in
CONTEXT.mdvocabulary — false positives are cheap. Under 200 words. Then one line — the strongestOpportunity:, a module and the move that raises evolvability most, orOpportunity: none.
Depth vocabulary (use these terms exactly — don't drift into "component", "service", "API", "boundary"):
- Module — anything with an interface and an implementation: a function, class, package, or tier-spanning slice.
- Interface — everything a caller must know to use it correctly: signature, invariants, ordering, error modes, config, performance.
- Depth — behaviour a caller/test exercises per unit of interface they must learn. Deep = large behaviour behind a small interface; shallow = interface nearly as complex as implementation.
- Seam (Feathers) — a place you can alter behaviour without editing there; where a module's interface lives, and the surface tests cross.
- Leverage / Locality — depth buys callers more capability per unit of interface (leverage) and buys maintainers change/bugs/knowledge concentrated in one place (locality). Both are evolvability: leverage lowers the cost of the next caller, locality lowers the cost of the next change.
4. Aggregate
Present the three reports under ## Standards, ## Spec, and ## Architecture, verbatim or lightly cleaned. Keep the Architecture findings in the sub-agent's evolvability ranking, and carry its Opportunity: line through to step 6. Do not merge or rerank across axes — the independence is what keeps one axis from masking another (see Why three axes).
End with a one-line summary: total findings per axis, and the worst issue within each axis. Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
5. Verdict (approval bar)
Close with approve / request changes, judged against this bar. Any one of these presumptive blockers justifies request-changes:
- a change that lowers evolvability at a load-bearing point: a reinvented domain concept, a bypass around the canonical flow, or logic landed in the wrong layer;
- a shallow module added at a seam that should have been deep;
- new behaviour with no seam to test it through its interface;
- a documented-standard hard violation;
- a spec requirement implemented wrong (not merely a missing nice-to-have).
Judgement-call smells and architecture nits inform the review but don't block on their own. A raise-evolvability opportunity never blocks — it takes the escape route below.
6. Escape route (Architecture axis only)
If the Architecture axis returned an Opportunity: naming a real deepening or code-judo move — one bigger than this change should swallow inline — end the review with a single concrete next step the operator can run:
"Strongest architectural opportunity: <module> — <the move>. Run
/improve-codebase-architectureon it for a before/after report and a grilling pass, or fold it in now if it's small."
One opportunity, the strongest, ranked by evolvability impact — not a backlog. If the axis returned Opportunity: none, omit this section. The escape route is a forward path the operator chooses to take; it is never a condition of approval.
Why three axes
A change can pass one axis and fail another:
- Follows every standard, implements the wrong thing → Standards pass, Spec fail.
- Does exactly what the issue asked but breaks conventions → Spec pass, Standards fail.
- Clean and correct, but it forks the domain model — a second Order definition the next change has to keep in sync → Standards + Spec pass, Architecture fail.
Reporting them separately stops one axis from masking another.
Tone (primes the agent's vocabulary)
Direct, serious, specific. Not rude. Reach for:
- "this forks the Order concept
CONTEXT.mdalready owns — two definitions to keep in sync; fold it into the intake module." - "this bypasses the repository and writes straight to the table — a second source of truth the next change has to find."
- "there's a code-judo move here: fold this behind the existing seam and the new layer disappears — cheaper to change next time."
- "correct, but there's no seam to test it through — can we inject X?"
- "this is clean, but it doesn't do what #123 asked for."
Don't flood the review with low-value nits when there are structural issues.
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.

