review-architecture
Skill4 starsChanged 4 months agoApache-2.0View on GitHub
Audit an aggregate implementation diff or proposed remediation obligation against resolved architecture and current architectural authorities. Report architecture drift, unresolved architectural changes, and boundary violations without modifying code, docs, ADRs, or the Living Entity Wiki.
15 other projects use a version of this.
Adopted by
Most recently taken up by
- unlockers-ai/unlockers-skills-librarytheir own version, first seen Nov 8, 2026
- 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
Used with
Projects with it also use review-testing, review-correctness and 1 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.
worldbankSkillreview-testing
Review test code for quality, design, and completeness after implementing a feature or fixing a bug. Use when the user asks to "review my tests", "check my test quality", "are these tests good enough", "review testing", or after completing a feature implementation that includes tests. Also use when tests feel brittle, flaky, or superficial. Cross-references production code to find coverage gaps.
Also in 4 projects that use this
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
SentrySkillwrite-tests
Write tests following project conventions. Use when adding new tests or modifying existing ones.
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 repository51 other files it gives its agents.
- AGENTS.mdAGENTS.md
- architecture-remediationSkill
- attentionSkill
- classify-docSkill
- codebase-designSkill
- codebase-memory-mcpSkill
- codegraphSkill
- coding-standardsSkill
- contract-ledgerSkill
- conventional-commitsSkill
- database-migrationsSkill
- deduplicate-codeSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- format-codeSkill
- github-issue-dependenciesSkill
- graphifySkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implement-ticketSkill
- improve-codebase-architectureSkill
- project-delivery-managementSkill
- project-trackingSkill
- prototypeSkill
- repowiseSkill
- researchSkill
- resolving-merge-conflictsSkill
- review-specSkill
- setup-matt-pocock-skillsSkill
- spec-contractSkill
- spec-merge-cleanupSkill
- tddSkill
- teachSkill
- to-adr-docSkill
- to-docSkill
- to-specsSkill
- to-ticketsSkill
- triageSkill
- verify-architectureSkill
- verify-codeSkill
- verify-spec-closureSkill
- verify-specSkill
- verify-ticket-closureSkill
- verify-ticket-decompositionSkill
- wayfinderSkill
- wiki-lintSkill
- wiki-syncSkill
- wiki-synthesizeSkill
- writing-great-skillsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
46 rules. 0 are common, 34 are distinctive, and 12 are very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
34
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 29
Read the spec's Architecture Impact and identify:
- Distinctive: line 36
If implementation materially changes architecture but the spec contains no resolved architectural basis for that change, report a Blocking …
- Distinctive: line 38
Do not invent the missing decision here.
- Distinctive: line 42
If the Living Entity Wiki exists:
- Distinctive: line 46
Follow relevant inline citations to authoritative sources.
- Very specific: line 47
Read wiki/_schema.md when authority or conflict semantics are needed.
- Very specific: line 58
Use read-only structural tools such as codegraph or codebase-memory-mcp only when targeted repository evidence is needed.
- Distinctive: line 60
Do not update indexes or regenerate graphs.
- Distinctive: line 64
When reviewing implementation, inspect the complete spec diff for architecture consequences that may not be visible in any individual …
- Very specific: line 70
When $review-spec supplies Architecture Review Universe cells, preserve every supplied cell and its ID.
- Distinctive: line 74
every affected entity in the Spec Architecture Impact.
- Distinctive: line 75
every governing ADR/current architectural document identified by the Spec or current entity context.
- Distinctive: line 76
every changed production surface materially participating in those entities or authorities.
- Distinctive: line 93
Do not restrict architecture review to changed hunks when the governing authority requires parity across sibling entry points or transports.
- Distinctive: line 95
Every coverage cell must end in exactly one state:
- Distinctive: line 105
If review discovers an additional materially relevant architecture surface or authority not present in the supplied universe, add a new …
- Very specific: line 109
When review pass strategy is supplied:
- Very specific: line 113
Start from each governing entity/ADR/current authority and trace forward to its canonical implementation, callers, …
- Distinctive: line 117
Start from changed and named production surfaces and trace backward to authority.
- Distinctive: line 128
Do not use another reviewer's findings or coverage conclusions.
- Distinctive: line 149
When the caller provides a proposed remediation or Root Blocker acceptance obligation, evaluate whether that obligation is implementable …
- Distinctive: line 151
Do not decide whether the obligation is desirable and do not design its solution.
- Very specific: line 160
Use Architecture decision required: No when current authority already permits and determines the required behavior.
- Distinctive: line 162
If the obligation conforms to current architecture, report no architecture finding for it.
- Distinctive: line 164
When this skill is reviewing only a proposed remediation obligation rather than an aggregate implementation, full Spec-wide coverage …
- Distinctive: line 168
Follow the repository's claim-specific authority rules.
- Very specific: line 170
If applicable architectural authorities materially disagree, report [source-conflict] as Blocking.
- Very specific: line 172
Do not classify implementation absence or nonconformance as [source-conflict] merely because an accepted decision has not yet been realized.
- Distinctive: line 178
Do not turn uncertainty into an architectural fact.
- Distinctive: line 182
When an apparent architecture mismatch may reflect active implementation or remediation work, check relevant open GitHub issues using …
- Distinctive: line 186
Use them to determine whether:
- Distinctive: line 192
If a relevant issue declares a work branch, inspect that ref read-only when useful.
- Distinctive: line 200
Use the caller's Finding Taxonomy when provided.
- Distinctive: line 208
Do not promote general design preferences or smells into Blocking architecture findings.
- Distinctive: line 216
Use No when existing architectural authority already establishes the required result and the remaining work is conformance or remediation.
- Distinctive: line 218
Use Yes only when remediation requires a new or changed architectural decision, applicable architectural authorities materially disagree, …
- Distinctive: line 220
Do not equate Blocking with Architecture decision required: Yes.
- Distinctive: line 246
If reviewing a proposed remediation obligation, identify the exact blocked obligation when applicable.
- Very specific: line 258
If no findings exist, report No findings.
- Very specific: line 260
Keep findings concise and evidence-based.
- Distinctive: line 266
run tests, Ruff, Mypy, coverage, and duplication scans.
- Distinctive: line 272
create or edit ADRs or non-ADR documents.
- Distinctive: line 277
treat GitHub issues as architectural authority.
- Distinctive: line 278
treat unmerged branch work as current implementation.
- Very specific: line 286
Before dispositioning ARCH-* cells, build a working Architecture Candidate Inventory from the supplied Architecture Impact plus current …
- Very specific: line 298
Every candidate must be dispositioned.
“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
Review Architecture
Audit whether an implemented change or proposed remediation obligation preserves or correctly realizes resolved architecture.
This is a read-only review. It reports architecture findings; it does not redesign or repair the system.
Inputs
Use the caller-provided:
- aggregate diff and commit list, when reviewing implementation;
- originating spec;
- spec Architecture Impact, when present;
- affected entities and governing ADR/doc references, when known;
- owner overrides, when applicable;
- proposed remediation or Root Blocker acceptance obligation, when evaluating its architecture conformance;
- affected production paths/contracts for that obligation, when known;
- architecture Review Universe cells, when provided by
$review-spec; - review pass strategy:
authority-first | adversarial-surface-first, when provided.
1. Establish the Intended Architecture
Read the spec's Architecture Impact and identify:
- affected entities;
- impact:
none | conforming | extending | changing | retiring; - governing architectural decisions or constraints;
- ADRs/docs that resolved intentional architecture changes.
If implementation materially changes architecture but the spec contains no resolved architectural basis for that change, report a Blocking finding.
Do not invent the missing decision here.
2. Load Current Architectural Context
If the Living Entity Wiki exists:
- Read
wiki/index.md. - Load the affected entity pages.
- Follow relevant inline citations to authoritative sources.
- Read
wiki/_schema.mdwhen authority or conflict semantics are needed.
Consult applicable:
- accepted ADRs;
docs/current/;- relevant
docs/proposed/for planned architecture; - implementation evidence from the codebase.
The wiki is derived context, not architectural authority.
Use read-only structural tools such as codegraph or codebase-memory-mcp only when targeted repository evidence is needed.
Do not update indexes or regenerate graphs.
3. Review the Aggregate Implementation
When reviewing implementation, inspect the complete spec diff for architecture consequences that may not be visible in any individual ticket.
Architecture Coverage Contract
Architecture review is coverage-driven, not discovery-until-interest-runs-out.
When $review-spec supplies Architecture Review Universe cells, preserve every supplied cell and its ID. Do not merge or drop materially distinct cells.
The architecture universe must account for:
- every affected entity in the Spec Architecture Impact;
- every governing ADR/current architectural document identified by the Spec or current entity context;
- every changed production surface materially participating in those entities or authorities;
- named canonical owners, paths, boundaries, persistence/release/evaluation seams, and transports;
- relevant sibling or alternate paths required to obey the same authority, even when they are unchanged by the latest remediation;
- the applicable architecture dimensions below.
For each relevant surface or boundary, evaluate applicable dimensions:
- canonical owner and source of truth;
- boundary crossing and dependency direction;
- authority/evidence/lifecycle ownership;
- fail-closed, unavailable, optional-dependency, default, and fallback behavior;
- alternate, compatibility, direct-construction, bypass, and parallel canonical paths;
- duplicate ownership of durable concepts, services, repositories, or sources of truth;
- caller/model/payload/metadata/mapping control over authoritative semantics;
- accepted realization-required decisions versus actual realization;
- retirement or topology changes not deliberately resolved.
Do not restrict architecture review to changed hunks when the governing authority requires parity across sibling entry points or transports.
Every coverage cell must end in exactly one state:
checked-no-finding | blocking | advisory | not-applicablenot-applicable requires a concrete reason. unknown, unchecked, deferred, or silent omission is not complete review.
For every coverage cell, return concise evidence identifying the authority and inspected implementation surface(s). A finding does not discharge unrelated cells; continue until all cells are dispositioned.
If review discovers an additional materially relevant architecture surface or authority not present in the supplied universe, add a new coverage cell rather than silently expanding another one.
Independent Pass Strategies
When review pass strategy is supplied:
authority-first
Start from each governing entity/ADR/current authority and trace forward to its canonical implementation, callers, persistence/release/evaluation seams, and required sibling surfaces.
adversarial-surface-first
Start from changed and named production surfaces and trace backward to authority. Deliberately search for paths most likely to evade the canonical lifecycle, including:
None/optional dependency behavior;- defaults, fallbacks, compatibility branches, and early returns;
- direct construction or alternate service/facade entry points;
- caller-supplied authority/evidence/version/provenance;
- metadata/mapping/type-recovery authority paths;
- alternate persistence, release, promotion, audit, or evaluation paths;
- sibling CLI/backtest/MCP/runtime/facade behavior;
- paths that succeed when the canonical owner/service is unavailable.
Do not use another reviewer's findings or coverage conclusions. Each pass must independently disposition the complete architecture universe.
Architectural Checks
Look for:
- ownership moving away from the canonical owner;
- layers bypassing established boundaries;
- reversed or invalid dependency direction;
- duplicate ownership of a durable concept;
- parallel canonical paths, runtimes, repositories, services, or sources of truth;
- new architectural abstractions or boundaries not resolved by the spec;
- existing architectural boundaries or responsibilities silently retired;
- implementation that contradicts an applicable invariant or accepted decision;
- accepted realization-required decisions implemented differently from what was resolved;
- entity topology changes not deliberately resolved through the architecture lifecycle.
Evaluate the implementation as a system, not as isolated hunks.
4. Review Proposed Remediation Obligations
When the caller provides a proposed remediation or Root Blocker acceptance obligation, evaluate whether that obligation is implementable under current architectural authority.
Do not decide whether the obligation is desirable and do not design its solution.
Report Blocking with Architecture decision required: Yes when satisfying the obligation would require:
- violating or changing an accepted architectural decision;
- introducing a new canonical contract, owner, path, or boundary;
- choosing a new dependency direction or lifecycle responsibility; or
- reconciling materially conflicting architectural authorities.
Use Architecture decision required: No when current authority already permits and determines the required behavior.
If the obligation conforms to current architecture, report no architecture finding for it.
When this skill is reviewing only a proposed remediation obligation rather than an aggregate implementation, full Spec-wide coverage accounting is not required; cover the supplied obligation and its affected production paths/contracts.
5. Handle Evidence Correctly
Follow the repository's claim-specific authority rules.
If applicable architectural authorities materially disagree, report [source-conflict] as Blocking. Do not choose a winner.
Do not classify implementation absence or nonconformance as [source-conflict] merely because an accepted decision has not yet been realized. Distinguish implementation or documentation drift from disagreement between architectural authorities.
For mechanically observable constraints, positive implementation evidence may verify compliance.
For intent-level architectural constraints, absence of contradictory code is not proof. State only that no contrary implementation evidence was found.
Do not turn uncertainty into an architectural fact.
Active Work Context
When an apparent architecture mismatch may reflect active implementation or remediation work, check relevant open GitHub issues using strong identifiers such as the affected entity, ADR, canonical owner, root blocker, or spec.
GitHub issues are workflow-status evidence only. They are not architectural authority or implementation proof.
Use them to determine whether:
- an existing architecture decision is already being realized or remediated;
- the mismatch is known and actively tracked;
- remediation requires a new architecture decision or only conformance with an existing one.
If a relevant issue declares a work branch, inspect that ref read-only when useful. Do not switch branches.
Implementation present only on another branch is in progress, not implemented on the branch under review.
Active work does not make the audited branch pass, and a closed issue does not prove implementation.
6. Classify Findings
Use the caller's Finding Taxonomy when provided.
Otherwise:
- Blocking — implementation or a proposed remediation obligation violates applicable architectural authority, introduces/requires an unresolved material architecture change, or cannot be judged because of a material
[source-conflict]. - Advisory — architecture concern worth review but not supported strongly enough to establish a violation.
- Owner-overridden — explicitly accepted by the owner; report only when useful for context.
Do not promote general design preferences or smells into Blocking architecture findings.
For every Blocking finding, determine:
Architecture decision required: Yes | NoUse No when existing architectural authority already establishes the required result and the remaining work is conformance or remediation.
Use Yes only when remediation requires a new or changed architectural decision, applicable architectural authorities materially disagree, or the governing architecture cannot be determined.
Do not equate Blocking with Architecture decision required: Yes.
Output
For each finding report:
### <Blocking | Advisory | Owner-overridden> — <short title>
**Issue:** <what the implementation or proposed obligation does/requires>
**Evidence:** <diff/source/obligation evidence>
**Architecture:** <affected entity, ADR, document, contract, or invariant>
**Why it matters:** <specific architectural consequence>
**Architecture decision required:** <Yes | No>
**Routing:** <existing-authority remediation | upstream architecture resolution>For Architecture decision required: No, identify the governing authority when known.
For Architecture decision required: Yes, identify the specific unresolved architectural question.
If reviewing a proposed remediation obligation, identify the exact blocked obligation when applicable.
For aggregate implementation review, always append:
## Coverage
- ARCH-<id> — <checked-no-finding | blocking | advisory | not-applicable> — <authority>; <surfaces inspected>; <evidence/reason>Include every supplied and reviewer-added Architecture Review Universe cell exactly once.
If no findings exist, report No findings. and still return the complete Coverage section.
Keep findings concise and evidence-based. Coverage may be longer because it is an internal completeness artifact consumed by $review-spec.
Out of Scope
$review-architecture does not:
- run tests, Ruff, Mypy, coverage, and duplication scans;
- invoke the
$wiki-lintskill; - update repository graphs;
- perform the Standards or Spec review axes;
- invent or modify Root Blocker acceptance obligations;
- modify source code;
- create or edit ADRs or non-ADR documents;
- mutate the Living Entity Wiki;
- resolve
[source-conflict]; - design new architecture to fix a finding;
- create remediation tickets;
- treat GitHub issues as architectural authority;
- treat unmerged branch work as current implementation.
The caller owns remediation and lifecycle routing.
Transition-Bound Architecture Review Coverage
Architecture review completeness has two separate gates: complete construction of the applicable architecture universe, then sound disposition of every cell. Neither may be inferred from checked = all cells the reviewer happened to create.
Before dispositioning ARCH-* cells, build a working Architecture Candidate Inventory from the supplied Architecture Impact plus current accepted authorities and directly implicated canonical owners, paths, boundaries, lifecycles, sources of truth, and authority-required sibling/alternate surfaces.
Each candidate records:
Candidate: AC-<n>
Source/authority: <exact source>
Architectural dimension/surface: <exact concern>
Disposition: <ARCH-<n> | excluded>
Reason: <None | exact authority/scope reason for exclusion>Every candidate must be dispositioned. Exclusion is explicit evidence-bearing state, not omission. Before review can complete require Unclassified architecture candidates: 0 and Excluded candidates without reason: 0.
For every ARCH-* cell maintain:
Claim: <authoritative architecture obligation>
Predicate: <subject + quantifier + domain + required predicate + material conditions/exceptions>
Falsifier: <concrete current state that would make the claim false>
Evidence: <direct current evidence>
Survivability: <excluded | survives>
Assumptions: <None | material assumption + authority/direct proof>
Disposition: <checked-no-finding | Blocking | Advisory | not-applicable | unresolved>checked-no-finding requires Survivability: excluded and no unproven material assumption. If all inspected evidence could succeed while the architecture claim remains false, the cell is unresolved or finding-bearing, never clean by default.
Return architecture coverage counts with the existing review result and require:
Missing ARCH cells: 0
Unknown ARCH cells: 0
Unchecked/unresolved ARCH cells: 0
Incomplete checked-no-finding proof records: 0
Unclassified architecture candidates: 0These are working review records; concise human reporting remains acceptable.
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.

