From c4e013fbcec57a6123b3fddd44f8c34fa2dea6db Mon Sep 17 00:00:00 2001 From: Ken Date: Wed, 27 May 2026 00:59:12 +0000 Subject: [PATCH] docs: add visualization pass as mandatory content pipeline step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every post must be considered for diagrams before publishing. The question is not 'does this need a diagram?' but 'what would illustrate this better than prose?' Visualization approach: - Claude hand-codes SVGs using primitives following design spec - Warm palette (paper bg, brown-black ink, terracotta accent) - Diagrams break wider than prose (840px breakout) - DOT + d3-graphviz for interactive architecture graphs - Image generation for concept art / visual targets Rule: 1000+ words with zero visuals is a warning. The consideration is mandatory. The diagrams are not. 🤖 Generated with Amplifier Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- .amplifier/AGENTS.md | 52 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/.amplifier/AGENTS.md b/.amplifier/AGENTS.md index e674748..13104d1 100644 --- a/.amplifier/AGENTS.md +++ b/.amplifier/AGENTS.md @@ -79,6 +79,53 @@ It almost always does. - **Voice profile:** .amplifier/VOICE.md - **Design specs:** .design/AESTHETIC-GUIDE.md, .design/specs/ +### Visualization Pass Is Mandatory Before Publishing + +Every post gets a visualization pass. The question is not "does this post need +a diagram?" The question is "what would illustrate this better than prose?" + +**For every section of a post, ask:** + +1. Am I reaching for a bullet list? A diagram might replace it entirely. + Bullet lists are a Claude default. Ken's real writing uses prose or visuals, + not lists. If you have 3+ items that relate spatially or sequentially, draw + them instead of listing them. + +2. Am I describing a system, flow, or architecture? Draw it. Code an inline + SVG following the diagram design spec, or use a `` component. + +3. Am I comparing two things? A two-column visual or a before/after diagram + beats a paragraph explaining the contrast. + +4. Am I showing a progression or timeline? A flow diagram with labeled steps + beats a numbered list every time. + +5. Would a concept illustration anchor the section? Even a simple symbolic + SVG (like the masterclass philosophy cards: hub-and-spoke, concentric + circles, crossed-out icons) gives the reader a visual anchor. + +**What the visualization pass produces:** +- A list of sections that would benefit from diagrams +- For each: what type (architecture, flow, comparison, concept) and a brief + description of what the SVG should show +- Generate the SVGs inline using the diagram design spec (when it exists) + or flag them for the author to describe + +**The rule:** If a post has 1000+ words and zero visuals, that's a warning. +Not every post needs diagrams, but every post should have been *considered* +for them. The consideration is mandatory. The diagrams are not. + +**How visuals are made:** +- Claude hand-codes SVGs using primitives (``, ``, ``, + ``) following the diagram design spec constraints +- Use the warm palette from DESIGN.md (paper background, brown-black ink, + terracotta accent) +- Diagrams break wider than prose (840px vs 720px) using the code-block + breakout pattern +- For interactive architecture graphs: DOT source + d3-graphviz runtime +- For concept art / visual targets: use image generation, then code SVG + approximations toward the target + ## Content Pipeline ``` @@ -94,7 +141,10 @@ Mechanical lint: ./scripts/lint-voice.sh LLM judge: voice-check (8 dimensions) | v -Fix failures, re-check +Visualization pass: what would illustrate this better than prose? + | + v +Fix failures, add diagrams, re-check | v Rebuild preview: rebuild /tmp/blog-dist, serve on :4321