audit-structure
This skill contains shell command directives (!`command`) that may execute system commands. Review carefully before installing.
!cat ~/.claude/skills/audit-workflow.md
Run as the structure dimension. Lens:
Find code that lives in the wrong place — wrong module, wrong layer, wrong grouping — against the repo's own conventions, never an imported ideal.
Structure has no universal shape, so establish the convention before judging, in priority order. First, materialized policy: a written structure doc (*structure*.md, ARCHITECTURE.md, CONTRIBUTING.md) or an enforcement config (import-linter, eslint boundaries, dependency-cruiser, ArchUnit) — when one exists it is the authority; audit against its rules and flag violations of it, don't reinvent a scheme. Otherwise infer from what dominates: grouping axis (by-feature folders holding their own routes+models+logic, vs by-type models/+routes/+services/), the recurring file-role vocabulary, and layer direction from the import graph. Directory listings give shape; git log co-change is ground truth for what belongs together. Apply audit-patterns' >60% rule — converge outliers toward the dominant pattern; never impose one the repo doesn't use.
Flag: a feature scattered across by-type dirs when the repo groups by feature (or the reverse), so one change touches five folders; god-modules failing the proportionality test (one-sentence job, yet 5+ files or 3+ classes); misplaced files and co-changing files split across the tree; leaky boundaries — internals imported from outside instead of through the module's curated surface, re-export barrels duplicating that surface, a public surface growing faster than real external consumers; layer-direction violations (infra importing domain, pure helpers importing I/O, cross-domain coupling bypassing public surfaces) and import cycles; cross-cutting code consuming 2+ domains buried inside one; novel one-off file roles, empty stubs, depth past ~4 levels.
Filter hard. Framework-mandated layouts (Next.js, Rails, Django) are conventions to respect, not findings. A by-type repo that is by-type throughout is consistent — only flag the outlier breaking the dominant grouping. Size alone is not yours: a thin or oversized file is audit-complexity (merges, collapse) or audit-necessity (should it exist); you own placement and boundaries — a correctly-sized file in the wrong module. Dynamically-resolved layouts (plugin dirs, registry walks, convention-scanned folders) look misplaced but are wired by mechanism — confirm no loader depends on the path before moving. git log dates divergence: recent drift is accidental and worth fixing; long-standing structure is load-bearing.
Apply in the direction the repo prefers: move the file to where co-change points, route through the existing public-surface convention, collapse a stray by-type split back into the feature folder, break a cycle by promoting the shared concept to a layer both may depend on. Moves are high-blast-radius — grep every reference, fix all import sites in one pass. Where a structural linter or policy doc exists, extend its rules so the convention stays pinned. Auto-fix: a behavior-preserving move/route/collapse with all references updated in the same commit. Sign-off: tree-reshaping — re-grouping a directory, splitting or merging modules, changing the layer scheme — sketch the before/after tree as the evidence.