architecture-survey

# Architecture survey

Architecture survey is the start for a question about the code's structure as a whole: "refactor what next", "tech debt", "this repo is a mess, where do I start", or a scoped architecture review. Outside an orientation the survey is a report and edits no file of the repository, so it needs no mode and no record: its report lives in the working files, the id a date and a slug as a change's is, deleted when the survey ends without a finding taken up, and a change that takes one up holds the report under its own id. When `architecture-map` (extra, installs on request) has written the map's snapshot, read it before walking the codebase; once a deepening lands, the map's refresh folds it back in. The owner decides what is taken up, and a finding taken up becomes a change under the mode the owner approves. At an orientation, a repository with documents and no change record on any branch, local or remote-tracking, the survey runs before the first change, as AGENTS.md says, and opens a quick record before it writes its result into the knowledge homes the workspace's work guide names; the report itself stays in the working files. Where a change record exists on any branch, the survey is no orientation: it runs only when the request asks for a survey or the owner names it.

Greenline's paths and commands for this skill stand on its references page, [references/greenline.md](references/greenline.md): read it when the work lands in the workspace.

- Load deep-modules through the harness's native skill mechanism, or read its installed SKILL.md and required support when the harness has none, for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion and in every delegated brief, and don't drift into "component," "service," "API," or "boundary."

Then walk the codebase: through one agent the harness's delegation starts, whose report you wait for, or by your own reading where the harness has no delegation; the delegated walk is the survey's one extra agent, so say so before starting it. That agent is the survey's own reader, not a fresh agent of a change's line, and no record cites what it hands back. Don't follow rigid heuristics; explore organically and note where you experience friction:

Write a self-contained HTML file to the working files as `architecture-review-<timestamp>.html` so each run gets a fresh file and nothing lands in the repo: a survey need not create implementation work, and git never sees the working files. Never open it: no `open`, `xdg-open` or `start`, no browser, nothing that reaches the owner's desktop. Tell the owner its absolute path; opening it is the owner's. When the owner takes a finding up, copy the report into that change's folder once its record cites it.

The report is offline-complete: **embedded CSS** for layout and styling, and **static inline SVG** for diagrams where a graph/flow/sequence reliably communicates the structure, with no network-loaded script, style, font, or image needed to view it. Mix graph-shaped SVG with hand-crafted CSS/HTML visuals: draw relationships directly in SVG when they are graph-shaped (call graphs, dependencies, sequences), and use hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.

The survey, its evidence and the grilled candidate return to the owner; a recommendation alone does not authorize implementation. A finding the owner takes up is a change like any other: propose its mode and wait, as AGENTS.md says, open its record with a `## start` section naming architecture-survey and the finding, and run the line from `frame`; its plan step splits the work into tickets only where it needs them. Do not manufacture a planning program for each observation.

## Handoff

Consumes: the repository; .greenline/map/snapshot.json when architecture-map (extra) has written it (optional); GLOSSARY.md and the decision records Produces: the offline HTML report under .greenline/tmp/<id>/, never opened, its path told to the owner, copied into the change's folder under .greenline/ledger/<id>/ only when a finding taken up cites it; at an orientation, its result in the knowledge homes; the survey returns to the owner, and a recommendation is not authorization Next: frame, under the mode the owner approves, for a finding the owner takes up; otherwise none, the survey staying in the reply

The architectural review is rendered as a single self-contained HTML file in the working files. It is offline-complete: the CSS is embedded and every diagram is static inline SVG or HTML, so no script, style, font, or image loads from a network. Inline SVG draws the graph-shaped diagrams; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on one pattern for everything, it'll start to look generic.

```html

<!doctype html>

<html lang="en">

<head>

<meta charset="utf-8" />

<title>Architecture review for {{repo name}}</title>

<style>

/* the whole stylesheet is embedded: nothing loads from a network */

body { margin: 0; background: #fafaf9; color: #0f172a; font-family: system-ui, sans-serif; }

main { max-width: 64rem; margin: 0 auto; padding: 3rem 1.5rem; }

main > * + * { margin-top: 3rem; }

article { border: 1px solid #e2e8f0; border-radius: 0.5rem; background: #fff; padding: 1.5rem; }

article + article { margin-top: 2.5rem; }

.badge { display: inline-block; border-radius: 9999px; padding: 0.125rem 0.625rem; font-size: 0.75rem; font-weight: 600; }

.strong { background: #d1fae5; color: #065f46; }

.explore { background: #fef3c7; color: #92400e; }

.speculative { background: #e2e8f0; color: #334155; }

.files { font-family: ui-monospace, monospace; font-size: 0.875rem; }

.label { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; }

.pair { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }

.diagram { border: 1px solid #e2e8f0; border-radius: 0.5rem; background: #fff; padding: 1rem; }

.callout { border: 1px solid #fcd34d; background: #fffbeb; border-radius: 0.375rem; padding: 0.5rem 0.75rem; }

/* small custom layer for the diagrams:

dashed seam lines, hand-drawn-feeling arrow heads, etc. */

.seam { stroke-dasharray: 4 4; }

.leak { stroke: #dc2626; }

.deep { background: linear-gradient(135deg, #0f172a, #1e293b); }

</style>

</head>

<body>

<main>

<header>...</header>

<section id="candidates">...</section>

<section id="top-recommendation">...</section>

</main>

</body>

</html>

```

Draw the graph directly in SVG when the point is "X calls Y calls Z, and look at the mess": modules as `<rect>` elements with a `<text>` label, calls as `<path>` elements ending in an arrowhead `<marker>`, laid out by hand left to right. Wrap it in a `.diagram` card so it doesn't feel parachuted in. Put the `leak` class on leakage edges to colour them red and the `deep` treatment on the deep module. Prefix marker ids per diagram so two SVGs on the page never share one. A hand-drawn sequence (lifelines as vertical lines, messages as horizontal arrows) works well for "before: 6 round-trips; after: 1."

```html

<div class="diagram">

<svg viewBox="0 0 560 120" role="img" aria-label="OrderHandler calls OrderValidator, which calls OrderRepo, which leaks into PricingClient">

<defs>

<marker id="c1-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">

<polygon points="0 0, 8 3, 0 6" fill="#475569" />

</marker>

</defs>

<rect x="8" y="40" width="112" height="40" rx="4" fill="#fff" stroke="#0f172a" />

<text x="64" y="64" text-anchor="middle" font-size="12">OrderHandler</text>

<rect x="168" y="40" width="112" height="40" rx="4" fill="#fff" stroke="#0f172a" />

<text x="224" y="64" text-anchor="middle" font-size="12">OrderValidator</text>

<rect x="328" y="40" width="88" height="40" rx="4" fill="#fff" stroke="#dc2626" />

<text x="372" y="64" text-anchor="middle" font-size="12">OrderRepo</text>

<rect x="456" y="40" width="96" height="40" rx="4" fill="#fff" stroke="#dc2626" />

<text x="504" y="64" text-anchor="middle" font-size="12">PricingClient</text>

<path d="M120 60 H168" stroke="#475569" fill="none" marker-end="url(#c1-arrow)" />

<path d="M280 60 H328" stroke="#475569" fill="none" marker-end="url(#c1-arrow)" />

<path class="leak seam" d="M416 60 H456" stroke-width="2" fill="none" marker-end="url(#c1-arrow)" />

</svg>

</div>

```

- No scripts at all. The report is static: no app code, no interactivity, and nothing fetched from a network, so it reads the same with the network off.

# Architecture survey: the practice's mechanics

This page holds where architecture-survey's work lands in the workspace and the commands it runs, which `SKILL.md` names by their nouns. Read it with `SKILL.md` when the work lands in the workspace.

## Where its work lands

The survey's report is `.greenline/tmp/<id>/architecture-review-<timestamp>.html`, in the working files, the id a date and a slug as a change's is; a change that takes a finding up copies it into its folder, `.greenline/ledger/<id>/`. The map's snapshot, which architecture-map writes, is `.greenline/map/snapshot.json`, and the work guide that names the knowledge homes is `.greenline/WORK.md`.