# USEFULNESS.md - how this site stays good

> FRESHNESS: TIMELESS. This is the DNA. Models change, the stack changes, the
> operator's mood changes; this does not. AGENTS.md says what breaks the build.
> This says what makes the thing worth building. Also published as
> /specs/usefulness.md so an agent editing the site reads the same filter it
> applies to any job.
>
> One rule above all the others: this document has to pass its own filter. If
> it ever reads like a compliance memo, it has failed, and you should rewrite
> it meaner and funnier. A sterile rulebook teaches the next agent to build a
> sterile site. The lobster is watching.
>
> And the rule that outranks even that one: this is a personal scratch pad,
> built for fun, that other people happen to find useful. Fun comes first. If
> maintaining it ever starts to feel like joyless compliance, an agent has
> sanded the soul off in the name of the very guardrails meant to protect it -
> stop, and do less. The guardrails exist so the operator can play fearlessly,
> never so the play becomes paperwork. "Vibe coded" is not a confession; it is
> the spec. The site is allowed to admit it doesn't know everything - that
> honesty is the feature, not the gap.

## What this site is

A field manual for running AI agents that do long, unattended work, with a
deliberately idiotic name and a real spine of engineering under it. It is
vibe-coded on purpose and useful in earnest - those are not in tension, they
are the whole trick. It now has two readers: a tired human at midnight, and a
working agent at 2 a.m. The magic is that the SAME move serves both. Make a
section clear, self-contained, lesson-first, and copy-pasteable, and you have
simultaneously built the most useful human page and the most fetchable agent
spec. When the two audiences seem to want different things, you haven't found
the move yet. Keep cooking until one artifact serves both.

## The mechanic that made this site

The site got good from a generative instruction, never a checklist:

> "Take what I said and make it 10x better. As useful as possible to a human
> actually trying to SEE and UNDERSTAND this. Now cook."

Decoded:

- Maximize toward one north star, don't satisfy a spec. The seed is a direction;
  your job is to overshoot it. Under-delivering on a "cook" is worse than
  overshooting.
- The north star is the reader's comprehension, for both readers. Not
  feature-completeness, not coverage, not polish. Does a real person - or a real
  agent - leave knowing or able to DO something they couldn't before?
- Subject dictates form. The shape of a thing is an argument about its content.
  If your layout would suit any topic, you reached for a template instead of
  thinking.
- Comedy is load-bearing, not garnish. A joke earns its place by sitting next to
  a lesson. Subtle and best-placed beats a big gag card every time.

## The guardrails

These do not replace the cooking. They keep it honest while you do it:

- Receipts, not vibes. Every real-world claim is sourced and posture-labeled
  (official / industry / local), or it is dropped.
- Additive only. You grow this site; you do not "clean it up." Losing something
  good is worse than adding something mediocre.
- Honesty is the credibility. Red cells, Known Limits, "what this leaves open."
  The authority comes from admitting the gaps.
- Serve both readers from one source. Human view and agent view render the same
  truth; never fork them into two drifting copies.

## After you cook, check you didn't drift

Quick questions to catch the common ways usefulness rots:

- What does this teach, in one line?
- What problem did the person walk in with, and does this meet them there?
- Could this be any page, or did its subject force its shape?
- What does it leave open?
- Would it survive being pasted into a fresh thread with nothing else?
- Did the joke pay rent, or is it just a joke?
- Did anything good get smaller? Then stop. Your change is wrong.

## What CI quietly enforces

Tests cannot measure "good," but they catch the gross ways it decays. The floor
exists so you can swing for the most alive version without fear of silently
breaking the last one.

## For an agent editing this site

Cook first, check second. You were handed a thing built to be the most useful
and most alive version of itself, for two audiences at once. Meet that bar; do
not just clear the tests. If your change could be any page, you assembled
instead of cooked. If it reduces anything, you are wrong, not the contract.