agentleFS
okeefecookeefeco/pyeye-mcp/skills/architecture-review/SKILL.md

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

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.
  • lilangMaxSkill

    create-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

  • lilangMaxSkill

    story-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

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
  1. Distinctive:

    Every finding the auditor emits carries exactly one of these four grades, and the human loop handles exactly these four states (there is no …

    line 57
  2. Very specific:

    Run these in order. The deterministic substrate lives in src/pyeye/architecture_review/ and is the authority for every mechanical step.

    line 88
  3. Very specific:

    Validate before merging (#498): run state.finding_problems(f) on every returned finding and reject (re-dispatch, or drop and report) any …

    line 115
  4. Very specific:

    Call state.build_non_issue(finding) → append the returned NonIssue dict to state["confirmed_non_issues"].

    line 215
  5. Very specific:

    When drafting the entry, pull evidence and handles from the finding verbatim.

    line 239
  6. Distinctive:

    prevalence ≠ correctness: Never assert which cluster is correct, *even the strict majority*.

    line 256

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 keyWhat it covers
layeringLayering / dependency direction: which layers/packages may import which.
module_boundariesModule & placement boundaries: where a kind of thing lives.
dependency_acquisitionDependency acquisition: constructor-injection vs import vs global/singleton.
error_handlingError handling: raise vs return-sentinel vs result-type; exception types; where caught.
validation_placementValidation placement: at the boundary vs in core vs scattered.
naming_api_shapeNaming & API shape: naming patterns, return-type conventions, sync/async split.
cross_cuttingCross-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 as deterministic_single only 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 with python scripts/decisions.py index --active where 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.

  1. Reproduction gate — gate.apply_reproduction_gate(findings, redispatch_fn, runs=DEFAULT_GATE_RUNS, equivalent=findings_equivalent). Each deterministic_single candidate is re-dispatched runs times (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.
  2. Cross-derivation guard (#494) — guard.apply_cross_derivation_guard(findings, corroborate_fn). For each surviving deterministic_single, the injected corroborate_fn independently 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 in guard.corroborate_imports, which compares the edge's resolved imports and its unresolved_imports against guard.imports_via_ast, a from-scratch stdlib ast reader). The verdict has three states (#499):
    • corroborated: the finding keeps deterministic_single.
    • divergent: the guard rewrites the grade to ambiguous and sets possible_extractor_bug = True (surface, do not confirm). This is what catches a reproducibly-wrong Tier-1 fact (e.g. pyeye's imports edge 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 becomes ambiguous with corroboration: "cannot_confirm" and no possible_extractor_bug: present it to the human as "needs review, could not verify", never as confirmed and never as an extractor bug.

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 to Read, 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_single finding.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.