How does the skill identify stale architecture documents?

It extracts module and component references from your documentation and compares them against the actual codebase and CLAUDE.md declarations to find mismatches or missing components.

Can I audit specific parts of my project instead of the whole codebase?

Yes, you can use the --module argument to scope the audit to a single module or specific directory.

What is an ADR in the context of this skill?

An ADR (Architectural Decision Record) is a document that captures an important architectural decision, including its context, rationale, and consequences for the project.

Does arch-audit automatically update my documentation?

No, arch-audit is a diagnostic tool that generates a report of findings. You can use related skills like arch-sync to address the findings identified in the report.

What triggers a 'Critical' finding in the audit report?

A finding is classified as critical if a foundational 'core' module is found to have no architectural governance or documentation references.

Architecture Audit

Name: Architecture Audit
Author: alexnodeland

byalexnodeland

•

Learning & Documentation

Audits architectural decision record (ADR) coverage to identify governance gaps, orphaned documents, and stale architecture specifications.

Arch-audit provides an automated governance assessment for complex codebases by mapping modules to their respective Architectural Decision Records (ADRs). It helps maintain architectural integrity by flagging ungoverned core modules, identifying ADRs that reference deleted code, and highlighting stale documentation that no longer matches the system's actual structure. This skill is essential for maintaining long-term project health, ensuring that every design decision remains relevant and every critical module follows established architectural patterns.

Key Features

01Identifies ungoverned core modules with critical severity warnings

02Detects orphaned ADRs referencing deleted or moved modules

03Generates comprehensive audit reports with severity-based findings

04Maps code modules to governing Architecture Decision Records (ADRs)

053 GitHub stars

06Highlights stale documentation that diverges from codebase declarations

Use Cases

01Onboarding new developers by identifying areas lacking formal governance

02Performing a health check on architectural documentation before a major release

03Maintaining ADR relevance during significant refactoring or module deprecation

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add alexnodeland/principled arch-audit

For use in Claude.ai and ChatGPT

Download Skill