pippinmole/ghost

public

Source code of Ghost - On Ghost

chore: add the code-review and cleanup skills used for the unslop pass6b064615 days ago123 lines · 6.5 KB

1	# HTML Report Format
2
3	The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
4
5	## Scaffold
6
7	```html
8	<!doctype html>
9	<html lang="en
10	<head>
11	<meta charset="
12	<title>Architecture review for {{repo name}}</title
13	<script src="
14	<script type="
15	import mermaid from "
16	mermaid.initialize({
17	</script>
18	<style>
19	/* small custom layer for things Tailwind doesn't cover cleanly:
20	dashed seam lines, hand-drawn-feeling arrow heads, etc. */
21	.seam { stroke-dasharray
22	.leak { stroke
23	.deep { background
24	</style>
25	</head>
26	<body class="
27	<main class="
28	<header>...</header
29	<section id="
30	<section id="
31	</main>
32	</body>
33	</html>
34	```
35
36	## Header
37
38	Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
39
40	## Candidate card
41
42	The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
43
44	Each candidate is one `<article>`:
45
46	- Title: short, names the deepening (e.g. "Collapse the Order intake pipeline").
47	- Badge row: recommendation strength (
48	- Files: monospaced list,
49	- Before / After diagram: the centrepiece. Two columns, side by side. See patterns below.
50	- Problem: one sentence. What hurts.
51	- Solution: one sentence. What changes.
52	- Wins: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
53	- ADR callout (if applicable): one line in an amber-tinted box.
54
55	No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
56
57	## Diagram patterns
58
59	Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
60
61	### Mermaid graph (the workhorse for dependencies / call flow)
62
63	Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
64
65	```html
66	<div class="rounded-lg border border-slate-200 bg-white p-4
67	<pre class="
68	flowchart LR
69	A[OrderHandler] --> B[OrderValidator]
70	B --> C[OrderRepo]
71	C -.leak.-> D[PricingClient]
72	classDef leak stroke:#dc2626,stroke-width:2px;
73	class C,D leak
74	</pre>
75	</div>
76	```
77
78	### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
79
80	Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `
81
82	### Cross-section (good for layered shallowness)
83
84	Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
85
86	### Mass diagram (good for "interface as wide as implementation")
87
88	Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
89
90	### Call-graph collapse
91
92	Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
93
94	## Style guidance
95
96	- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
97	- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
98	- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
99	- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
100	- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
101
102	## Top recommendation section
103
104	One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
105
106	## Tone
107
108	Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
109
110	Use exactly: module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
111
112	Never substitute: component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
113
114	Phrasings that fit the style:
115
116	- "Order intake module is shallow: interface nearly matches the implementation."
117	- "Pricing leaks across the seam."
118	- "Deepen: one interface, one place to test."
119	- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
120
121	Wins bullets name the gain in glossary terms: *
122
123	No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.