vac-optimizer/.agents/skills/improve-codebase-architecture/HTML-REPORT.md

HTML Architecture Report

Use only when HTML output is requested or a visual artifact materially helps. Honor the selected location; otherwise write to a fresh temporary file. Keep it usable offline with semantic HTML, a small stylesheet, and static SVG when useful.

Minimal scaffold

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Architecture review</title>
    <style>
      body { max-width: 70rem; margin: 2rem auto; padding: 0 1rem; font-family: system-ui; line-height: 1.5; }
      article { margin-block: 2rem; }
      svg { max-width: 100%; height: auto; }
    </style>
  </head>
  <body>
    <main>
      <h1>Architecture review</h1>
      <!-- Add the scoped findings and recommendation. -->
    </main>
  </body>
</html>

Findings

For each candidate, include its location, observed problem, proposed change, concrete benefit, and recommendation strength. Identify ADR conflicts and uncertainty. Omit unsupported or merely speculative candidates rather than filling a quota.

Use before/after visuals for relationships that prose does not explain clearly. A small dependency graph, sequence, or nested module view may help; a plain paragraph often suffices. Give SVGs accessible titles and descriptions, and do not communicate meaning through color alone.

Use an existing renderer only when it adds value; embed static output rather than requiring external scripts at viewing time. Escape repository text inserted into HTML. Do not execute code from issues or findings to build the report.

End with the recommended next step and its reason. The report does not authorize implementation.

Tone

Use concise, evidence-backed explanations. Preserve project vocabulary and describe the relevant design concept where useful.

Terms such as module, interface, depth, seam, leverage, and locality can clarify the design.

Names such as component, service, API, boundary, layer, or wrapper are appropriate when they accurately name the project element. Do not replace established terms just to satisfy a glossary.

Phrasings that fit the style:

• "Order intake module is shallow — interface nearly matches the implementation."
• "Pricing leaks across the seam."
• "Deepen: one interface, one place to test."
• "The payment boundary isolates network failures in tests."

Describe concrete gains such as fewer caller obligations or preserved coverage through one contract. Avoid unsupported claims of cleaner code, regardless of vocabulary.

State uncertainty and trade-offs honestly. Use only the formatting needed to make the finding understandable.