Report Templates

This reference defines the required architecture audit report structure and block formats.

Required Section Order

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 Gaps

Treat ## Highest-Leverage Structural Issues as a short prioritized summary of the top root issues. The three later category sections contain the full finding blocks. Each full finding must appear in exactly one primary category section and must not be duplicated across sections.

In ## Repo Brief, include the chosen audit mode exactly as Audit mode: single-auditor or Audit mode: specialist-panel so mode selection is explicit and machine-checkable.

Finding Block

Every full finding must use this shape:

### [Short issue title]
- Severity: [critical | high | medium]
- Evidence: [files, modules, dependency edges, symbols, tests, docs]
- Why it matters: [change cost, coupling, fragility, cognitive load, regression risk]
- Recommended improvement: [specific structural change]
- Likely refactor surface: [where the change would start]

Use critical only for structural issues that create immediate correctness, safety, or delivery risk. Use high for architecture problems that clearly raise change cost or regression risk. Use medium for material issues that should be sequenced after higher-leverage repairs.

Improvement Sequence

The improvement sequence must be ordered and explain the goal and why each first move comes first.

Use this exact shape for every numbered item:

1. [First move]
   Goal: [what this unlocks]
   Why first: [dependency, leverage, or risk reason]

Each numbered improvement must include both labels exactly: Goal: and Why first:. Do not use prose-only explanations, parenthetical reasons, or alternate labels such as Rationale: in place of Why first:.

Order moves by dependency and leverage. Start with changes that expose or protect a seam, reduce risk for follow-on refactors, or isolate a boundary before reshaping internals.

Exit Criteria

This phase is done when:

• all required headings are present and in order
• every full finding uses the required block shape
• each finding appears in one primary category only
• the improvement sequence has Goal: and Why first: lines under every numbered item