Software Architecture Audit

Run an evidence-grounded software architecture audit workflow that turns the highest-leverage findings into an ordered, incremental improvement sequence.

What this skill does

This skill reviews a repository, subsystem, or specific path for architecture problems grounded in direct code evidence. It builds a factual repo brief, selects single-auditor or specialist-panel mode, inspects boundary integrity, dependency direction, cohesion, composition roots, testability, architecture smells, report structure, and refactor sequencing.

The workflow starts with a factual repo brief, chooses single-auditor or specialist-panel mode based on scope, gathers direct evidence, and produces a structured report with category-specific findings and a concrete improvement sequence.

When to use

Use this skill for prompts such as:

• "Audit this repo's architecture"
• "Write an architecture audit report"
• "Produce audit_report.md"
• "Architecture review for this package"
• "Review the structure of this subsystem"
• "Find boundary and layering problems"
• "Inspect dependency direction and composition roots"
• "Identify architecture smells and testability gaps"
• "Plan an incremental architecture refactor"
• "Use specialist-panel synthesis for a multi-module system"

Install

tessl install sharaf/software-architecture-audit

How it's organized

Output format

The final audit report must use these headings, in order:

## Repo Brief
## Highest-Leverage Structural Issues
## Boundary and Layering Problems
## Dependency and Composition Problems
## Testability and Change Friction
## Improvement Sequence
## Open Evidence Gaps

Each full finding includes severity, evidence, why it matters, recommended improvement, and likely refactor surface. The improvement sequence is ordered by leverage and dependency, not abstract architectural purity.

Eval results

Tested across three generated scenarios:

Per-scenario with-context scores:

Activation after the routing fix: 3/3 generated scenarios fired tessl__software-architecture-audit.

Built from

Migrated from the legacy flat skill skills/software-architecture-audit.md in this repository.

Research lineage:

• Domain: software-architecture
• Sub-domains: anti-patterns-code-smells, clean-layered-architecture, dependency-management-inversion, structural-patterns, testing-architecture, system-evolution-migration
• Research date: 2026-04-01