Guardrails And Success Criteria

This reference defines what the architecture audit must avoid and how to decide whether the report is complete.

Guardrails

• Audit code and repo docs only.
• Do not confuse framework conventions with proven architecture quality.
• Do not recommend a rewrite unless the evidence strongly shows incremental repair is not viable.
• Do not reward speculative abstractions or pattern cargo culting.
• Do not flag every large file as a problem without showing why its responsibilities are incoherent.
• Do not prescribe microservices, event sourcing, or other heavyweight patterns unless the evidence clearly supports them.
• Prefer concrete structural improvements over abstract architectural commentary.
• Keep recommendations incremental and aligned with the codebase's likely rate of change and current seams.
• Do not include a score or scorecards.
• Do not include a strengths section unless the user explicitly asks for one.
• Move ambiguous evidence to ## Open Evidence Gaps.

Decision Logic

Before writing findings, answer these checks:

1. Is the target narrow enough for one pass, or broad enough for specialist-panel mode?
2. Which issues are root causes versus symptoms?
3. Is a dependency or abstraction improving changeability, or merely adding indirection?
4. Is duplication cheaper than the current abstraction, or has the code crossed the threshold where extraction is justified?
5. Are tests supporting safe change, or are they coupled to implementation details in ways that block refactoring?
6. Which first structural move unlocks the cleanest next move?

Success Criteria

The audit is complete when:

• the repo brief is factual and grounded in direct evidence
• the chosen mode matches the scope of the target
• findings cover the main structural issues without turning into a generic best-practices list
• every finding includes severity, evidence, why it matters, recommended improvement, and likely refactor surface
• the improvement sequence is ordered and incremental
• ambiguous or missing information is isolated in ## Open Evidence Gaps
• the report avoids scorecards, broad praise sections, and heavyweight rewrite recommendations

Exit Criteria

This phase is done when the final report satisfies every success criterion and no guardrail violation remains.