2026-05-03
The Gap Is
the Feature
Reliability comes from the system boundary — the artifact between steps — not from trying harder. Today's lessons all traced back to that one idea.
1---
2 name: "YIL 2026-05-03"
3 background: light
4 colors:
5 accent-1: "#cc785c"
6 accent-2: "#5db8a6"
7 accent-3: "#e8a55a"
8 tailwind:
9 bg-main: "bg-[#faf9f5]"
10 sections:
11 - id: hero
12 headline: "The Gap Is the Feature"
13 - id: specs-as-artifacts
14 layout: steps
15---
Without a file on disk between steps, 'following the spec' is just trying to stay consistent with what was written five minutes earlier.
Specs Only Work When They Exist
01
/yil-design writes a real artifact to disk — a DESIGN.md with colors, layout, and section structure fully resolved.
02
Review the artifact. The gap is not a delay — it's the mechanism. Without a file between steps, "following the spec" is just trying to stay consistent with context from five minutes ago.
03
/yil-build reads from the file on disk — not from memory, not from context. The artifact is
the spec.
Secondary lesson
Hex values in a design spec are a translation step. #d97706 requires knowing it maps to text-amber-600. Adding Tailwind class names directly to the tailwind: section of the spec removes that translation from the build step entirely.
Put It in a File, Not in Your Head
Pattern
Layout patterns need to be in durable memory — not just in the codebase. The
revealing footer (<Footer /> outside <main>, sticky at the bottom) exists on every page and was still missed twice in one
session.
Router
_-prefixed directories are invisible to Astro's router. _design/ and _prompts/ can live alongside pages without creating routes — artifacts collocated with the
pages they describe.
Discovery
import.meta.glob on .astro files can collect named exports. Exporting yilMeta from each YIL page is enough for the index to discover and list all entries without
a content collection.
Meta
The process for making YIL pages trustworthy is the same as the YIL content itself — design the system so reliability is structural, not volitional. You shouldn't have to try harder; the artifact does it.
Screenshots Show Shape; Words Define Behavior
Guiding Claude Code from a screenshot into a complex UI took several rounds to get connector behavior right. The insight: screenshots show shape, not constraints. When details matter — connector routing, line opacity, parallel lane offsets — they need to be named explicitly in the prompt, not implied by the reference image.
"Route the lines from the pick card to Hermes first, then straight through all harness nodes, then curve out to the right" is a constraint. A screenshot of a data pipeline diagram is a reference. Both are useful; only one is a spec.
Same principle, different domain
The WordPress / DreamHost migration: "easy" tooling still hides environment and browser-cache traps. Clearing cookies and local storage wasn't enough — it took using the browser's site-state reset to get past a cached DreamHost setup page. The tool was easy; the environment was not. Naming that gap explicitly is the work.