architecture-review

Files (5)

• HTML-REPORT.md
• LEDGER-FORMAT.md
• SKILL.md
• YES-QUEUE.md
• openai.yaml · agents/

SKILL.md (first lines)

# Architecture review

Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is verifiability and AI-navigability: fewer, deeper modules mean fewer files an agent must read before it can act safely. Any codebase with interfaces qualifies, imperative or declarative; the friction signals differ, the vocabulary doesn't.

The run ends at triage. Grilling the candidates the user accepted is a separate session, started from a `/handoff` so the argument gets a clean context; see [YES-QUEUE.md](./YES-QUEUE.md).

This command is informed by the project's domain model and built on a shared design vocabulary:

- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the verification surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion; don't drift into "component", "service", "API" or "boundary".
- The domain doc conventions live in `docs/agents/domain.md`: the glossary gives names to good seams, and ADRs record decisions this command doesn't re-litigate.
- The review ledger at `docs/agents/architecture-review-ledger.md` records what past runs proposed and the user turned down. Reading it first is what stops this command re-suggesting the same deepenings run after run; see [LEDGER-FORMAT.md](./LEDGER-FORMAT.md).

## Process

### 1. Explore

Read the project's domain docs first, per `docs/agents/domain.md`, then the review ledger at `docs/agents/architecture-review-ledger.md` if it exists. The ledger holds candidates the user has already dismissed or parked, each with a fingerprint; keep them to hand, they decide what survives exploration.

When the user names a scope, confine the scan to it; otherwise walk the whole project. A scope can be spatial (a path, a feature) or by substance (only the `.scss`, only the token layer). Reading outside the scope to understand callers is fine; proposing candidates outside it isn't. On a large codebase an unscoped scan dilutes the report, so suggest a scope before starting rather than pressing on with a noisy one.

Then use the Agent tool with `subagent_type=Explore` to walk the scoped codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:

- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow**, the interface nearly as complex as the implementation?
- Where have small pieces been extracted just for testability, while the real bugs hide in how they're combined (no **locality**)?
- Where do tightly coupled modules leak across their seams?
- Where do variables or tokens rename what they configure one-to-one instead of abstracting it?
- Where must a caller know a module's internals (markup structure, cascade position, call order) to use it correctly?
- Which parts of the codebase are unverified, or hard to verify through their current interface?

Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

If sub-agents aren't available in the environment, explore directly.

Then drop every candidate the ledger has already settled, per the matching rules in [LEDGER-FORMAT.md](./LEDGER-FORMAT.md). Suppression is never silent: carry a count of what you dropped into the report.

### 2. Present candidates as an HTML report

Write a self-contained HTML file to the OS temp directory so nothing lands in the project. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.

The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph, flow or sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), hand-built divs and SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.

For each candidate, render a card with:

- **Files**: which files or modules are involved
- **Problem**: why the current architecture is causing friction
- **Solution**: plain English description of what would change
- **Benefits**: explained in terms of locality and leverage, and how verification would improve
- **Before/after diagram**: side by side, custom-drawn, illustrating the shallowness and the deepening
- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge

End the report with a **top recommendation** section: which candidate to tackle first and why.

**Use the domain glossary's vocabulary for the domain and the `/codebase-design` vocabulary for the architecture.** If the glossary defines "Order", talk about "the Order intake module", not "the FooBarHandler" and not "the Order service".

**ADR conflicts**: when a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (a warning callout: *"contradicts ADR-0007, but worth reopening because…"*). Don't list every theoretical refactor an ADR forbids.

See [HTML-REPORT.md](./HTML-REPORT.md) for the full HTML scaffold, diagram patterns and styling guidance.

Do NOT propose interfaces yet, and keep triage out of the report: it presents, the next step decides.

### 3. Triage every candidate

Take a disposition on all of them, not just the one that gets built; anything left untriaged is what comes back next run. Write one numbered question per candidate, top recommendation first, offering `Yes`, `Maybe-later` and `No` in the body with your recommended disposition against each. Ask every candidate in a single round and wait for the dispositions.

Then write the ledger before acting on any of it, per [LEDGER-FORMAT.md](./LEDGER-FORMAT.md). Every `no` and `maybe-later` gets an entry, with the reason in the user's own words; a `yes` gets nothing, as building it changes the code out from under any fingerprint. Write the entries while the decisions are fresh, not at the end of a session that may not get there. This is where the ephemeral `no` lands: "not worth it right now" is too thin for an ADR and too real to lose.

### 4. Close out the dismissals

**Maybe-later**: offer to capture each as a task per the tracker conventions in `docs/agents/task-tracker.md`, and link the task from its ledger entry. Don't publish them unasked, a parked candidate is the user's call rather than backlog filler.

**No**: discard. When the reason is load-bearing rather than ephemeral, call the Skill tool with "domain-modelling" for its ADR criteria, offer an ADR and link it from the ledger entry.

Both are cheap and they finish the run, so do them now rather than carrying them into a session that may not reach them. That leaves only the yes-queue outstanding.

### 5. Stop, and send the yes-queue to a fresh session

The review is over. Grilling the yes-queue is the next session's work, and it starts from a handoff so it begins with a clean context: by this point the exploration sweep and the report's markup are still in the window, and none of it is what a grill needs. The artefacts carry what does.

Tell the user the run is complete and ask them to run `/handoff` to start the grill phase. Recommend an argument naming the work, e.g. `/handoff grill the architecture-review yes-queue`. Say nothing about what the grill will conclude, and don't start one.

Give them the material the handoff document should carry, so it can point rather than duplicate:

- The absolute path of the HTML report.
- The yes-queue, in recommendation order, each candidate named as the report titled it.
- The absolute path of the ledger.
- The absolute path of `YES-QUEUE.md` in this skill's own directory, resolved from wherever this skill was loaded. That file is the next session's instructions, and this command is `disable-model-invocation`, so a fresh session can't reach it any other way.

Suggested skills for the handoff: `/grill`, `/codebase-design`, `/domain-modelling`.

The user may decline and grill in this session instead. That's their call; follow [YES-QUEUE.md](./YES-QUEUE.md) if so.

From nathanstaines/skills, MIT.

More from nathanstaines/skills