WAYS OF WORKING · DEMO 09 NINO CHAVEZ
I installed a skill to make my READMEs prettier and pointed it at five repos. It barely touched the design. What it did instead was read the code — and start contradicting the docs.
photography/README.md said
"Deployment platform: Vercel · Adapter: @sveltejs/adapter-vercel by default."
→ or scroll to advance · ← to go back
02 THE SETUP
The skill is beautify-github-readme — a small agent skill that redesigns a repo's README: a hero image, cleaner hierarchy, a diagram or two. I expected a paint job. The instructions had one line I underweighted: read the real repository first.
So on the first repo it didn't reach for a color. It listed the actual commands, opened package.json, read the config — and the mismatch started immediately. By the fifth repo the pattern was undeniable: the design was the smallest thing the tool did. The valuable part was the part that looked at what was true.
03 THE DRIFT
Three contradictions, each one the README asserting a fact the repository disproves in a single grep. None of them are cosmetic. All of them would waste a real person's afternoon.
photography/README.md said
"Install with pnpm (recommended)" — and every command in the guide is a pnpm command.
browse-tool/README.md said
"Nine small CLI scripts."
photography/README.md said
Features and tech stack — a gallery, filtering, performance notes.
04 WHY IT WORKS
A tool named for decoration did its most valuable work as a diagnostic. Three things made the difference — and none of them are visual:
It read ground truth, not the doc
The drift only surfaces if you check the claim against the thing it describes — the config for a deploy line, the lockfile for a package manager, the deps for a feature list. The skill's first move is the audit-discipline rule I already keep: demo 07, applied to a README.
It stayed native to each project
Where it did add a visual, it pulled the palette and type from the repo itself — terminal green for a CLI, midnight-and-gold for the tournament app. The rule that kept five heroes from looking like one template: native to the project, not to the tool.
The audience set the effort
A maintainers-only README got left plain; the flagship product's got a full masthead. Same tool, opposite intensity — decided by who lands on the page and what they're judging, not by where the file sits.
Polish is the finish. The diagnosis is the substance.
05 THE DESIGNED CHOICES
The one place the tool did real design was a diagram: browse-tool's architecture, hand-drawn as an SVG that used the project's own colors. It looked good enough to want more of. But "make more diagrams" splits into two tools, and the honest answer is to keep both and choose at the moment you invoke them.
Hand-authored SVG
Bespoke layout, exact tokens, a real motif. Reserved for the one or two diagrams on a surface a non-engineer judges — a README's first screen. It doesn't scale: every coordinate is placed by hand.
Themed Mermaid
Written from reading the code, rendered by GitHub from a text fence, themed to the project's colors, edited as a diff. The right call for anything engineers read that changes with the code.
The choice is audience × change-rate — decided per diagram, never defaulted.
06 HONEST LIMITS
This is a demo about a tool that inspects — so the failure it produced is almost too on the nose. Demo 07's whole lesson happened again, this time to me, on this session.
The claim I didn't earn
I wrote that the hand-drawn SVG banners would "render fine" on GitHub's image proxy in dark mode. I had only ever looked at them locally, rendered by a Mac preview tool — never once on an actual GitHub page. I asserted the render and skipped the render.
The check that got blocked
When I tried to verify the published comparison artifact in a real browser, the browser profile wasn't logged in and hit a sign-in wall. I fell back to rendering the diagrams through the Mermaid engine directly — real evidence, but of the diagrams, not of the page I claimed to have checked.
The scope I can't wave away
Five repos, all mine, all one stack family. The "it's an auditor" conclusion is drawn from a small, homogeneous sample. A large repo with many contributors might drift in ways this pass would miss entirely.
Verify where it ships — not where it's easy to look.
07 YOUR VERSION OF THIS
If you never touch code
Before you accept a cleaned-up document, ask what it was checked against. A tidy README, deck, or spec can be confidently, beautifully wrong — the polish makes the stale facts look more trustworthy, not less.
If you're technical
Point your "polish" tools at ground truth first. The highest-value output of a formatting pass is the diff it can't reconcile — the deploy line the config contradicts, the command the CLI no longer has. Fix what's wrong before styling what's fine.
If you build systems
Treat any cosmetic tool as a diagnostic one, and give it the ground truth to check against. A README linter that greps the config for drift is worth more than a hero image — and the two can ship in the same pass.