ln-24-architecture-auditor
Audits implemented architecture, boundaries, dependencies, and configuration ownership. Not for documenting current state or reviewing plans.
levnikolaevich · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add levnikolaevich/claude-code-skills --skill ln-24-architecture-auditorAbout this skill
name: ln-24-architecture-auditor description: "Audits implemented architecture, boundaries, dependencies, and configuration ownership. Not for documenting current state or reviewing plans."
Architecture Auditor
Goal: Perform a read-only audit of the architecture the system actually executes. Evaluate whether structure, dependencies, contracts, and cross-component ownership fit current product needs without rewarding pattern names or speculative modernization. Judge where atomicity and resource ownership belong; leave local query, transaction, and data-resource correctness to a persistence-focused review.
Execution contract: The ordered checkboxes are the Definition of Done. Track every item internally as PENDING, PROVEN with concrete evidence, CLEARED with evidence that its condition is absent, or UNPROVEN with a gap; reading, delegation, or tool failure is not proof. Reconcile items after each section. Before returning, resolve all PENDING and count only PROVEN and CLEARED; apply the skill's verdict and approval rules to every gap.
Preserve user intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without silently skipping checks. Preserve dependency and safety ordering; otherwise choose the verification method appropriate to each obligation.
Tool Routing
| Need | Preferred tool | Use it when | Fallback |
|---|---|---|---|
| Physical and declared architecture | Native file listing, manifests, build files, configuration, and architecture documents | Establishing modules, packages, domains, layers, entrypoints, and deployment units | Targeted repository map from known entrypoints |
| Symbols and dependency topology | Language server, compiler metadata, or host-native code intelligence | Tracing imports, calls, implementations, routes, events, and cycles | Narrow search plus direct inspection of definitions and consumers |
| Runtime wiring | Registration code, dependency injection, routing, startup configuration, and safe runtime diagnostics | A component may exist but not be discoverable or connected | Static trace with explicit uncertainty |
| Historical intent | Git history, blame, and decision records | A current exception or parallel mechanism may have a still-valid reason | Current behavior and documented constraints remain authoritative |
| Architectural fitness | Current official framework and platform documentation | A finding depends on supported extension, lifecycle, configuration, or boundary behavior | Primary-source web research; otherwise mark UNVERIFIED |
| Quantitative structure | Existing dependency, cycle, complexity, or package-analysis commands | The repository already defines reliable structural analysis | Reproducible static inventory and call-path evidence |
Use diagrams only when they clarify a relationship that prose cannot. Do not generate a diagram as a substitute for evidence, and do not modify code or architecture documents during the audit.
Evidence Rules
- Executable dependencies, runtime wiring, and public contracts outweigh intended diagrams or folder names.
- A cycle or cross-layer call is a finding only when it creates a concrete change, ownership, testing, deployment, or failure cost.
- Pattern compliance is not a goal by itself; evaluate fitness against product complexity, team workflow, and operational constraints.
- Framework convention and generated wiring require framework-aware verification before being labeled leakage or dead code.
- Modernization is justified only by a present defect or measurable simplification, not novelty.
- Explicit repository boundary rules define intended constraints; documentation explains them; inference from folder names is low-confidence evidence and must not create a violation by itself.
- A prior audit baseline separates new, resolved, and accepted debt. It does not make an active correctness or security risk disappear.
- Shared system-design baseline, current-state, target-design, decision, diagram, and migration artifacts are optional intent evidence. Their absence is not a defect by itself, and their presence never outranks executable behavior for the implemented state.
Checklist
1. Discover the Actual Architecture
- Read repository instructions, architecture documents, manifests, entrypoints, deployment definitions, and configuration ownership rules.
- Discover shared architecture artifacts by repository convention, distinguish a system-design baseline from a prior audit baseline, and classify each as current, proposed, accepted, superseded, stale, contradictory, or
UNKNOWN; do not require any particular artifact path. - Map packages, modules, domains, layers, processes, data stores, queues, external systems, and public interfaces in scope.
- Record ownership and independent build, deploy, scale, and failure boundaries; do not infer a service boundary from a directory or process name alone.
- Identify the dominant organizing model and any competing models: layer-first, domain-first, service boundaries, plugin boundaries, or framework conventions.
- Trace representative critical flows from entrypoint through orchestration, domain behavior, persistence or integration, and observable outcome.
- Compare documented current state, target state, accepted decisions, and active migration phase with executable structure; record drift and authority conflicts without assuming documentation describes what actually runs.
- Inspect Git state so current work and unrelated user changes are not misclassified as established architecture.
- Keep the audit read-only and disclose any permitted diagnostic caches or generated analysis artifacts.
2. Audit Pattern Fitness and Ownership
- Identify major patterns from behavior and assess problem fit, completeness, consistency, and evidenced maintenance cost; avoid in