sharaf/software-architecture-audit
Run an evidence-grounded software architecture audit workflow that builds a repo brief, selects single-auditor or specialist-panel mode, inspects boundary, layering, dependency, composition, cohesion, and testability risks, writes required finding blocks, and sequences incremental refactors. Use when asked for an architecture audit, architecture review, repo-structure review, software architecture report, audit_report.md, structural issue findings, or specialist-panel synthesis across multi-module systems.
100
100%
Does it follow best practices?
Impact
100%
1.85xAverage score across 3 eval scenarios
Passed
No known issues
SKILL.md
- name:
- software-architecture-audit
- description:
- Run an evidence-grounded software architecture audit workflow that builds a repo brief, selects single-auditor or specialist-panel mode, inspects boundary, layering, dependency, composition, cohesion, and testability risks, writes required finding blocks, and sequences incremental refactors. Use when asked for an architecture audit, architecture review, repo-structure review, software architecture report, audit_report.md, structural issue findings, or specialist-panel synthesis across multi-module systems.
- metadata:
- {"version":"0.2.13","source_domain":"software-architecture","source_sub_domains":"anti-patterns-code-smells, clean-layered-architecture, dependency-management-inversion, structural-patterns, testing-architecture, system-evolution-migration","research_date":"2026-04-01"}
Software Architecture Audit
Purpose
Audit a codebase for structural architecture improvement opportunities, with emphasis on boundary integrity, dependency direction, cohesion, composition, and testability. Use this skill when the user wants a repo-level or subsystem-level review that turns architecture concerns into a concrete, incremental improvement sequence.
The audit accepts the current repo, one or more paths, or a named subsystem. It should start by building a factual repo brief and then choose the right mode:
single-auditormode for a narrow path, package, or subsystemspecialist-panelmode for a full-repo or clearly multi-module target
The output is a structured report that starts with a factual repo brief, then surfaces the highest-leverage structural issues and orders the first moves that unlock safer follow-on refactors.
Instructions
Use the audit workflow in audit-workflow.md, then produce the final report with the exact templates in report-templates.md. Apply the constraints and completion checks in guardrails-and-success.md.
| Need | Read |
|---|---|
| Build the factual repo brief, choose audit mode, gather evidence, synthesize findings | audit-workflow.md |
| Exact report headings, finding blocks, and improvement sequence format | report-templates.md |
| Anti-patterns to avoid, decision checks, and completion criteria | guardrails-and-success.md |
Workflow Summary
- Build
## Repo Briefwith product context, language/framework, audit scope, docs checked, code surfaces checked, module map, and test layout. - Select mode and state it exactly:
Audit mode: single-auditorfor a narrow path or subsystem;Audit mode: specialist-panelfor full-repo or multi-module scope. - Inspect boundary direction, dependency flow, composition roots, cohesion, test seams, and repeated symptoms using direct file evidence.
- Collapse repeated symptoms into root-cause findings, then assign each finding to exactly one category section.
- Sequence incremental repairs by dependency and leverage; use
## Open Evidence Gapsfor ambiguity instead of guessing.
Format Anchors
Finding block:
### Shared persistence logic bypasses service boundaries
- Severity: high
- Evidence: `src/orders/repository.py`, `src/billing/repository.py`
- Why it matters: duplicated data access rules raise change cost and regression risk.
- Recommended improvement: introduce one persistence boundary owned by the domain layer.
- Likely refactor surface: repository interfaces, service constructors, persistence tests.Improvement sequence item:
1. Extract an order persistence interface at the service boundary.
Goal: make domain services depend on an interface before moving storage details.
Why first: it creates a narrow seam for follow-on refactors without changing behavior.Output Contract
The final report must contain exactly these sections, in this order:
## Repo Brief
## Highest-Leverage Structural Issues
## Boundary and Layering Problems
## Dependency and Composition Problems
## Testability and Change Friction
## Improvement Sequence
## Open Evidence GapsFull block shapes are defined in report-templates.md. Do not include scorecards or a strengths section unless the user explicitly asks for one.