architecture-review
Skill0 starsChanged yesterdayMITView on GitHub
Use when auditing how a Python codebase's architectural conventions diverge — "review the architecture", "audit conventions", "where does this code disagree with itself", "find inconsistent error-handling/layering/validation patterns", "is this package internally consistent". Surfaces a ranked queue of "here are N ways your code does X — you decide", many entries with no recommendation by design. Audits convention DIVERGENCE, not semantic duplication (that is #495). Scope is caller-supplied. Requires the pyeye MCP server.
85 other projects use a version of this.
Adopted by
Most recently taken up by
- lx-wnk/skillstheir own version, first seen Nov 16, 2026
- seancabalse/agentic-playbooktheir own version, first seen Nov 16, 2026
- erikperttu/steering-coding-agentstheir own version, first seen Nov 16, 2026
- Sequela02/canastatheir own version, first seen Nov 15, 2026
- OmarAlex24/audit-skillstheir own version, first seen Nov 15, 2026
- chuanglibs/Claude-Code-Game-Studios-Codextheir own version, first seen Nov 15, 2026
Used with
Projects with it also use create-stories, story-done 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.
lilangMaxSkillcreate-stories
Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.
Also in 11 projects that use this
lilangMaxSkillstory-done
End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint.
Also in 11 projects that use this
- +10 more from lilangMax
Other versions85 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 85
- Donchitos/Claude-Code-Game-Studios★ 39ksame name
- langwatch/langwatch★ 5ksame name
- ghuntley/loom★ 1.7ksame name
- microsoft/hve-core★ 1.6ksame name
- DataDog/dd-trace-js★ 840same name
- decebals/claude-code-java★ 763same name
- borgbase/vykar★ 722same name
- appdevforall/CodeOnTheGo★ 586same name
- owainlewis/blueprint★ 432same name
- getsentry/warden★ 424same name
75 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 repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- pyeye-scenariosSkill
- pyeye-verifySkill
- decision-logSkill
- python-exploreSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 2 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 77 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 57
Every finding the auditor emits carries exactly one of these four grades, and the human loop handles exactly these four states (there is no …
- Very specific: line 88
Run these in order. The deterministic substrate lives in src/pyeye/architecture_review/ and is the authority for every mechanical step.
- Very specific: line 115
Validate before merging (#498): run state.finding_problems(f) on every returned finding and reject (re-dispatch, or drop and report) any …
- Very specific: line 215
Call state.build_non_issue(finding) → append the returned NonIssue dict to state["confirmed_non_issues"].
- Very specific: line 239
When drafting the entry, pull evidence and handles from the finding verbatim.
- Distinctive: line 256
prevalence ≠ correctness: Never assert which cluster is correct, *even the strict majority*.
“Common” is measured: kept by at least 6 in 10 of the 77 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
Surface and prioritise how a Python codebase's architectural conventions diverge from each other, with cited evidence and honest grades — so a human can decide which convention to keep. This skill is the single source of truth for how to run the audit; it orchestrates a fresh-context auditor over a supplied scope and drives the human review loop.
<!-- architecture-review-axes: layering module_boundaries dependency_acquisition error_handling validation_placement naming_api_shape cross_cutting -->What This Is (and Is NOT) — Read First
Honest expectation. This tool produces a ranked queue of "here are N ways your code does X — you decide." Many entries will carry no recommendation by design (see the honesty invariants). It makes unknown divergences visible and ordered by impact — it does not remove the work, and it is emphatically not "the AI cleans up its own mess." You still make the architectural calls; this just stops you from making them blind.
Hard scope caveat — divergence, NOT duplication. This audits convention divergence ("your code does X seven different ways"). It does NOT detect semantic duplication ("the same code copy-pasted in many places"). Duplication is a content-similarity problem this skill structurally cannot do; it is carved out to issue #495. Do not run this expecting duplication detection — you will not get it.
Scope is caller-supplied and REQUIRED. You must hand this a scope — a package, module, or directory. Bounded-scope auto-iteration over a whole large repo is deferred; this skill audits exactly the scope it is given.
The Seven Seed Axes
The auditor sweeps (at minimum) these seven convention axes. The keys are the
single source of truth in pyeye.architecture_review.taxonomy.SEED_AXES; the
auditor may also surface other axes it finds.
| Axis key | What it covers |
layering | Layering / dependency direction: which layers/packages may import which. |
module_boundaries | Module & placement boundaries: where a kind of thing lives. |
dependency_acquisition | Dependency acquisition: constructor-injection vs import vs global/singleton. |
error_handling | Error handling: raise vs return-sentinel vs result-type; exception types; where caught. |
validation_placement | Validation placement: at the boundary vs in core vs scattered. |
naming_api_shape | Naming & API shape: naming patterns, return-type conventions, sync/async split. |
cross_cutting | Cross-cutting access: logging, config, path handling. |
Not an axis: code duplication. Carved out to #495 (see the scope caveat above). It never appears as an axis here.
The Output Contract — Four Grades
Every finding the auditor emits carries exactly one of these four grades, and the human loop handles exactly these four states (there is no fifth branch — contest signals are deferred):
mechanical_fact— extracted and deterministic; stated as context, no action.deterministic_single— a single convention the codebase consistently follows ("N/N do X"); presented for confirmation with evidence. Survives asdeterministic_singleonly if it passes the promotion chain (step 4).ambiguous— multiple clusters with no deciding anchor; all clusters surfaced with neutral evidence; usually carries no recommendation.no_signal— nothing found on this axis; stated honestly.
Grade by extraction where mechanical. For a mechanically-determinable
convention the grade is a counting fact, not an LLM label: N == total →
deterministic_single; a split → ambiguous. Judgment is reserved for the
within-axis question "does this divergence matter?", not for grades that fall out
of the count.
Tool Mechanics Live in python-explore
Both this orchestrator and the auditor build their structural model with pyeye
primitives (resolve / inspect / outline / expand / trace over canonical
handles). Do not restate the primitives here — follow the
python-explore skill for all tool mechanics,
including its honest-limits rule: pyeye has no reverse-reference / caller data
(deferred to #333), so never fake "who calls this" with grep — delegate caller
questions to an LSP, or state the limit. imported_by (static importers) is fine and is a primary
signal for the layering axis.
Orchestration — The Seven Steps
Run these in order. The deterministic substrate lives in
src/pyeye/architecture_review/ and is the authority for every mechanical step;
the orchestrator's job is to wire the steps together and drive the human loop.
1. Resolve scope + load baseline and cross-run state
- Resolve the caller-supplied scope to a canonical handle (a package, module, or directory). Scope is required — if the caller gave none, ask for one; do not default to the whole repo (auto-iteration is deferred).
- Load the Tier-3 baseline: the decision log, one file per decision in
docs/decisions/entries/(list them withpython scripts/decisions.py index --activewhere that script exists, then open the relevant ones), plus any existing conformance tests / fitness functions. These are the only first-strength external anchors a recommendation may cite. - Load prior cross-run state with
state.load_state(path): prior coverage, prior findings, and confirmed non-issues. This is what lets the audit suppress things the human already dismissed and carry a per-project axis prior.
2. Dispatch the auditor over the scope
Dispatch the fresh-context auditor (auditor.md) over the resolved scope, seeding
it with the Tier-3 baseline and the prior cross-run state (so it suppresses
confirmed non-issues and does not re-surface settled forks). The auditor builds a
structural model with pyeye, does targeted reads only, and returns a JSON array
of graded findings — nothing else. (Run it as a fresh subagent so its judgment
is uncontaminated by this conversation.)
Validate before merging (#498): run state.finding_problems(f) on every
returned finding and reject (re-dispatch, or drop and report) any with problems:
a seed-axis finding must carry a facet from taxonomy.AXIS_FACETS[axis], or
"other". This keeps unkeyed findings rare.
3. Merge into cross-run state
Merge the new findings into prior state with
state.merge_findings(prior, new), which dedups by state.findings_equivalent.
A finding's identity is state.observation_key = axis + facet + handle set
(order-independent), and two findings are equivalent when the key and the grade
match (#498). The claim wording is ignored, so a reworded claim is the same
finding, and two observations at one location stay apart by facet. Duplicates
across axes stay separate entries by design. An unkeyed finding (facet
missing or other, or an open axis) falls back to the exact normalised claim,
which can under-merge but never over-merges. The same predicate drives the
reproduction gate below, which never promotes an unkeyed finding. This
accumulates coverage across runs rather than starting cold each time.
4. Promotion chain — two stages, in order
A finding keeps deterministic_single only if it passes BOTH stages. Each
stage can only downgrade a grade (to ambiguous); neither invents or promotes.
- Reproduction gate —
gate.apply_reproduction_gate(findings, redispatch_fn, runs=DEFAULT_GATE_RUNS, equivalent=findings_equivalent). Eachdeterministic_singlecandidate is re-dispatchedrunstimes (DEFAULT_GATE_RUNS= 3, configurable) over its scope; it keeps the grade only if an equivalent finding appears in every re-run, else →ambiguous. This checks reproducibility, not truth. - Cross-derivation guard (#494) —
guard.apply_cross_derivation_guard(findings, corroborate_fn). For each survivingdeterministic_single, the injectedcorroborate_fnindependently re-derives its Tier-1 fact from source / AST (or an LSP) — NOT from another pyeye edge and NOT from the auditor's own evidence (for import / layering facts, wire inguard.corroborate_imports, which compares the edge's resolved imports and itsunresolved_importsagainstguard.imports_via_ast, a from-scratch stdlibastreader). The verdict has three states (#499):- corroborated: the finding keeps
deterministic_single. - divergent: the guard rewrites the grade to
ambiguousand setspossible_extractor_bug = True(surface, do not confirm). This is what catches a reproducibly-wrong Tier-1 fact (e.g. pyeye'simportsedge silently dropping a real import, #494) — the gate cannot, because a reproducible error reproduces. - cannot_confirm: the fact couldn't be decided (an import listed in
unresolved_imports, or source that doesn't parse). The grade becomesambiguouswithcorroboration: "cannot_confirm"and nopossible_extractor_bug: present it to the human as "needs review, could not verify", never as confirmed and never as an extractor bug.
- corroborated: the finding keeps
Net: deterministic_single survives only when reproduction-stable AND
cross-derivation-corroborated.
5. Rank (ordering only)
Rank the post-gate findings with
ranking.rank(findings, blast_fn, buckets=AXIS_STAKES_BUCKET, priors=AXIS_STAKES_PRIOR):
tiered by post-gate grade, and within a tier bucketed-lexicographically — by
explicit stakes bucket (high → med → low, from AXIS_STAKES_BUCKET) first,
then blast-radius descending within the bucket, then the stakes prior as a
within-bucket tiebreaker only. The bucket map is the source of truth for tier (a
high-stakes finding outranks a low-stakes one regardless of blast — dominance by
construction); the prior can no longer re-tier an axis (#492). Both are carried in
cross-run state and are per-project overridable (re-tier by editing the bucket
map).
Show the human the ranking basis verbatim, and offer to reorder:
Ranked by stakes bucket (validation/error-handling > … > naming), then blast-radius within the bucket — reorder?
Ranking is ordering only: it never drops, suppresses, or recommends. It is a queue order, not a verdict.
6. Human loop — exactly the four output-contract states
Surface the auditor's structured findings and cited evidence VERBATIM (evidence-transparency, spec §5/§9) — do not re-narrate, so the human judges the facts, not your framing. Then, per grade:
mechanical_fact→ state it as context. No action.deterministic_single→ "X is universal (N/N), evidence shown — recommend codifying. Confirm?" → on confirm, codify (step 7).ambiguous→ surface ALL clusters with neutral cited evidence; offer a recommendation only if an external anchor exists (often there is none → "no recommendation — you decide"). The human picks/writes the norm, or marks it a confirmed non-issue.no_signal→ note it honestly.
There is no fifth branch. Contest signals are deferred — do not add one.
7. Codify (human-gated) and save state
Both paths below are human-gated — nothing is codified without explicit
confirmation. Then call state.save_state(path, state) so the next run starts
from this point.
Dismissal path
Call state.build_non_issue(finding) → append the returned NonIssue dict to
state["confirmed_non_issues"]. Key design (#498): for a keyed finding,
build_non_issue sets structural_fact = "facet:<axis>/<facet>" and key =
non_issue_key(handles, structural_fact), so:
- Cosmetic source edits, a reworded claim or a grade change keep the same key: the finding stays suppressed on the next run.
- A genuine structural re-divergence changes the handles or the facet the auditor reports → new key → the finding re-surfaces for human review.
- An unkeyed finding falls back to
structural_fact = finding["claim"], which re-surfaces whenever the claim is reworded.
The auditor is seeded with state["confirmed_non_issues"] at step 2 so it skips
findings whose non_issue_key matches an entry in this list.
Positive-norm path (confirmed deterministic_single)
Invoke the decision-log skill's
human-gated propose → draft → confirm → append flow. That skill's rigid gate
applies in full — propose in ONE line; never draft before the user confirms; never
fabricate the date. The entry's Anchor must use stable refs (canonical symbol
handles / #issue) — never bare file:line; Verify must be honestly tiered
(gold / partial / unverifiable).
When drafting the entry, pull evidence and handles from the finding verbatim.
The entry is a new file in docs/decisions/entries/, in the format the
decision-log skill's File Convention defines (one file per decision; #679).
Prefer an executable fitness-function or conformance-test stub so the norm
becomes a running check (anti-drift, spec §14): the stub lives in tests/ and
the decision-log entry's Verify cites it as a gold assertion. Only if the norm
is non-executable (e.g. a naming convention that resists automated checking) fall
back to an explicitly-flagged checklist note in the entry, with Verify:
unverifiable — <reason> or Verify: partial — <checkable part>; <residue> needs
human review.
Honesty Invariants — Non-Negotiable
These bind the whole flow (spec §9). They are why most forks correctly produce no recommendation.
- prevalence ≠ correctness. Never assert which cluster is correct, even the strict majority. In an AI-written brownfield the majority pattern may be the mess. Prevalence is a descriptive fact, never a justification.
- A recommendation is non-null ONLY with an external anchor — a documented decision / Tier-3 baseline, or a language / stdlib idiom. Import-graph and structural facts of this codebase are corroborating only, never sole grounds (deciding on them just re-entrenches the mess). For genuine architecture forks the ladder usually yields no anchor → an absent recommendation is the correct output, not a defect.
- ranking ≠ correctness. The stakes bucket (then blast, then the prior tiebreaker) orders the queue; it is never a recommendation, is always shown and overridable (never a silent constant), and never suppresses a finding.
- the gate checks reproducibility, not truth. A reproducibly-wrong Tier-1 fact passes the reproduction gate — which is exactly why the cross-derivation guard (#494) re-derives the fact independently.
- grade by extraction where mechanical. For mechanically-determinable conventions the grade falls out of counting, not an LLM label.
Failure Modes
- No scope supplied → ask for one; do not audit the whole repo.
- pyeye unavailable → the auditor degrades per
python-explore's failure mode (note it, fall back toRead, warn that structural analysis is reduced). - Auditor returns non-JSON → its output contract is JSON-only; treat any surrounding prose as a contract violation and re-dispatch.
- No LSP for the cross-derivation guard → derive the Tier-1 fact from a
targeted source / AST read instead; never skip the guard for a
deterministic_singlefinding.
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.

