57 lines
2.6 KiB
Markdown
57 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```html
|
|
<!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.
|