Audit Workflow

This reference covers the architecture audit sequence: build a factual repo brief, choose audit mode, gather direct evidence, and synthesize findings.

Phase 1: Build A Factual Repo Brief

Read the strongest available sources of truth first:

• README*
• package manifests and workspace config
• architecture docs, ADRs, and module docs
• source directories that define app boundaries, services, domain modules, dependency injection, adapters, shared utilities, and tests
• import paths, wiring layers, and test helpers

Assemble a repo brief that states:

• product or package name
• implementation language and framework
• audit scope
• audit mode selected, written exactly as Audit mode: single-auditor or Audit mode: specialist-panel
• primary docs checked
• primary code surfaces checked
• top-level module map
• likely composition roots and boundary layers
• test layout and major testing style

Phase 2: Choose Audit Mode

Use single-auditor mode when the target is narrow enough to reason about in one pass.

Use specialist-panel mode when the repo is full-project scope or spans multiple independently meaningful modules or layers.

State the selected mode explicitly in the final report's ## Repo Brief. Do not leave mode selection implicit in the analysis prose.

Specialist roles:

1. Boundaries and layering
2. Dependencies and composition
3. Smells and change friction
4. Testability and refactor seams

In specialist-panel mode, give every specialist the same factual repo brief. Run the specialist passes in parallel when the available tools support parallel execution; otherwise run them sequentially. Synthesize the specialist outputs into one final report by deduplicating overlapping symptoms, keeping the root causes, resolving conflicts in favor of direct evidence, and collapsing the results into the required section order.

Phase 3: Gather Direct Evidence

Inspect the codebase for direct evidence of:

• inward or outward dependency flow
• boundary leaks between modules or layers
• shared utilities that centralize unrelated concerns
• god classes, oversized modules, shotgun surgery surfaces, feature envy, and speculative abstractions
• dependency injection seams, composition roots, and infrastructure leakage
• test shapes that either support or block safe refactoring
• duplicated logic that should remain duplicated versus duplication that now justifies extraction

Prefer direct evidence over architectural intent. Read the most likely source files before making a claim.

Phase 4: Synthesize Findings

Prioritize issues by leverage, not by abstract purity. Distinguish root boundary failures from dependency direction and composition problems, change-friction smells, and missing test seams that block safe restructuring.

Every full finding must be grounded in specific evidence and assigned to exactly one primary category section in the final report. Deduplicate symptoms that share a root cause. Move ambiguous evidence to ## Open Evidence Gaps.

Exit Criteria

This phase is done when:

• the repo brief is factual and cites the docs and code surfaces checked
• the audit mode matches the target scope
• direct evidence supports every finding candidate
• symptoms are collapsed into root causes before writing the report