review-architecture
Skill4 starsChanged 3 months agoMITView on GitHub
Review branch or pull-request changes for architectural fit — layering, ports and adapters, dependency direction, package boundaries. Use when a change adds a collaborator, crosses a package boundary, or introduces a new seam.
15 other projects use a version of this.
Adopted by
Most recently taken up by
- pascalorg/editortheir own version, first seen Nov 6, 2026
- dotnet/orleanstheir own version, first seen Nov 1, 2026
- rpraharaj/ai-sdlctheir own version, first seen Nov 1, 2026
- ROCm/rocprofiler-systems-skillstheir own version, first seen Oct 27, 2026
- nesnilnehc/ai-cortextheir own version, first seen Oct 25, 2026
- omarismailb/product-wikitheir own version, first seen Oct 25, 2026
Used with
Projects with it also use review-correctness.
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.
navjyotnishantSkillreview-correctness
Use this skill when the user asks to "review my changes for bugs", "check this diff for correctness", "did I introduce a regression", or wants a correctness-focused review of the current commit or uncommitted work before pushing. Reviews the changed lines and their blast radius for logic errors, regressions, unhandled edge cases, and missing validation. Works in any git repo; nothing here is project-specific.
Also in 3 projects that use this
Other versions15 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 15
- pascalorg/editor★ 26ksame name
- dotnet/orleans★ 11ksame name
- daveallie/crosspoint-reader★ 8.8ksame name
- crosspoint-reader/crosspoint-reader★ 8.8ksame name
- apache/pinot★ 6.2ksame name
- mrinalwadhwa/fluent★ 125same name
- dannys-code-corner/incan★ 74same name
- igmarin/rails-agent-skills★ 26same name
- nesnilnehc/ai-cortex★ 8same name
- omarismailb/product-wiki★ 8same name
5 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 repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adapter-contract-testingSkill
- azure-devops-prSkill
- bugszero-root-causeSkill
- legacy-3pSkill
- port-refactoringSkill
- quality-gateSkill
- review-ai-writingSkill
- review-allSkill
- review-complexitySkill
- review-driftSkill
- review-impactSkill
- review-prSkill
- review-securitySkill
- review-slopSkill
- review-testingSkill
- scope-challengeSkill
- teams-local-messagesSkill
- write-testsSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 81
Test reaching across the boundary it is meant to respect
- Distinctive: line 83
Check the seams: Every new external collaborator — HTTP, DB, queue, filesystem, clock, randomness, subprocess — should enter through a port …
- Distinctive: line 106
If the project has ADRs or active design specs, close with an Alignment section stating whether the change satisfies them.
“Common” is measured: kept by at least 6 in 10 of the 14 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
Architecture Review Skill
Reviews changes for architectural fit: are boundaries respected, are the seams in the right place, and can this be extended without infrastructure leaking into the domain?
Protocol: docs/review-protocol.md — arguments, ref resolution, exhaustiveness, severity levels, report shape. Read it first.
Its § 4 Be exhaustive is mandatory; the lens steps it refers to are steps 3–5 (Map the dependency direction, Apply the architecture lens, Check the seams) below.
Also read: the project's conventions doc (AGENTS.md, CLAUDE.md, CONTRIBUTING.md
— whichever exists), docs/design-patterns.md and
docs/hexagonal-architecture-rules.md — the
latter only where the codebase is actually hexagonal (see step 2), and often only for part
of it: one-shot scripts and static-site builds reviewed against the hexagon produce
findings nobody will act on. If the project keeps ADRs or design specs, check whether an
active one constrains the touched area.
Process
- Resolve refs and gather the diff — per
review-protocol.md. - Learn the existing architecture before judging it. For each touched package, read its README, its entry point, and one or two existing modules. Determine what style the codebase is actually in — hexagonal, layered, event-driven, transaction-script — and review against that, not against a preferred style. A change that is idiomatic for a layered codebase is not a finding because you would have written it hexagonally.
- Map the dependency direction. For each new import crossing a package or layer boundary, note which way it points. Most architectural findings are an arrow pointing the wrong way.
Apply the architecture lens
Critical (boundary violations):
- One deployable importing another deployable's internals
- Shared library importing from an application
- Domain layer importing an adapter or infrastructure module — the inverted dependency
- A new SDK / HTTP / DB / broker call placed directly in domain or service code instead of behind a port
- A concrete adapter constructed inside domain code instead of injected
- Direct clock, filesystem, randomness or environment access where a port already exists
- Bypassing an established abstraction with a raw client
- State written to a module global or singleton instead of an explicit owner
Major (design cost, paid later):
- New external collaborator with no port — no seam means untestable
- Optional constructor dependency added "to simplify tests" (use a Fake instead)
- New shared mutable state across components
- One bounded context reaching into another's models or storage
- A "manager"/"service" class accumulating unrelated responsibilities
- Behaviour that obviously belongs on an entity pushed into a service (anaemic model)
- Config object threaded through many layers instead of injecting the resolved value
- New public API duplicating an abstraction that already exists nearby
- Multiple side effects with no transaction and no stated decision to go without one — ask what state is left behind when the second write fails after the first succeeded
- Controller doing more than a few lines of work instead of delegating to a use case
- A use case interleaving reads, decisions and writes past the signals in
hexagonal-architecture-rules.mdrule 2 — three functional cases, a second catch, a second read-port or write-port call - An adapter reading an inbound payload field by field (
.get("status")) where the provider publishes a schema — rule 5
Minor (alignment):
- Module in the wrong folder for what it actually is (adapter living under services)
- Public symbol not exported where its peers are
- Naming that fights the established vocabulary
- Test reaching across the boundary it is meant to respect
- Check the seams. Every new external collaborator — HTTP, DB, queue, filesystem, clock, randomness, subprocess — should enter through a port with at least one Fake or Null implementation. Constructors should require all collaborators in production.
- Confirm § 4 of the protocol is satisfied, then generate report →
reviews/architecture-review-issues.md
Severity Model
| Severity | Indicators |
| Critical | Hard boundary violation; direct infrastructure call in domain; abstraction bypassed |
| Major | Missing seam or port; optional collaborator; god class; cross-context leakage; config tunnelling; untransacted multiple side effects; deciding and applying interleaved |
| Minor | Misplaced module; naming drift; missing export |
Output Format
Per review-protocol.md, with two extra fields on each finding:
**Principle violated:** e.g. dependency inversion / package boundary / seam-at-boundary
**Suggestion:** the concrete refactor — introduce port `X`, move the call into adapter `Y`If the project has ADRs or active design specs, close with an Alignment section stating whether the change satisfies them. Drift from a merged, authoritative spec is Critical; drift from a draft is Major.
Example Usage
review-architecture # Current branch vs main
review-architecture feat/foo # Specific branch
review-architecture feat/foo dev # Different base
review-architecture 3574 # PR/MR by numberDoes 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.

