Why Architecture Decisions Should Render in the Browser

·https://github.com/nicobailon/visual-explainer
repotoolpatternaiclitypescriptpiarchitectureadragent-loopvaultvisualization

Useful for [ADR review checkpoints](https://joelclaw.com/adrs/0015-loop-architecture-tdd-roles) in the [agent loop](https://joelclaw.com/adrs/0015-loop-architecture-tdd-roles), because `diff-review` and `plan-review` artifacts could become the loop’s handoff format instead of terminal-only noise.

visual-explainer by Nico Bailon is a Pi / Claude style skill that replaces terminal-heavy explanation output with a full HTML artifact. It watches for requests like /generate-web-diagram, /diff-review, and /plan-review, then emits a file under ~/.agent/diagrams/ for quick browser review, with no build step and minimal tooling beyond the model and a browser.

The clever part is the decision boundary: once output size crosses 4x3 table complexity or turns into a tangle of ASCII boxes, it auto-routes to templates tuned for Mermaid diagrams, CSS Grid architecture cards, and structured tables with Chart.js-style sections. It is, in other words, an attempt to make architecture explanation consumable for people who are already drowning in code. The prompt set is explicit about use cases: plan verification, diff review, fact-checking claims, and context-recapture after a day away.

For this system, that matters because the loop architecture already depends on explicit checkpoints—planning, review, and memory. A browser-rendered review artifact gives each stage a concrete, shareable artifact the next model (or human) can skim quickly. It also aligns with how ADRs already function in this repo: decision intent plus rationale, not just terminal output.

This feels like a practical upgrade path for Joel’s Vault and architecture hygiene if we treat visualization as infrastructure. A lot of friction in this stack starts when a good design exists only as text output; visual-explainer’s model is that structure should be generated once and reused by handoff tooling later.

Key Ideas

  • The repository structure makes the rendering model explicit: SKILL.md defines workflow, references/ define design systems, and templates/ define output types.
  • The diff-review flow is tailored for implementation checkpoints and already includes architecture comparison, risk notes, and decision logging, which maps cleanly to the loop stages where this repo already tracks observability.
  • A single-file output directory (~/.agent/diagrams/) creates a simple retention point, which is unusual compared with ephemeral terminal artifacts and is attractive for replayability.
  • The skill is spec-compliant with the Agent Skills standard, which makes installation and extension predictable for existing skill ecosystems.
  • It can be installed side-by-side with existing Pi and Claude skill trees via git clone and prompt template copy, so adoption can be incremental.

Links

← All discoveries