Editorial titles

People orient through concrete common knowledge and deliberate through abstract frames. Titles that open with in-group abstractions (dependents, wires, labels, navigating by content) fail before the idea starts.

The machine-readable house rule is agents/editorial/titles.md. This page is the same doctrine for humans on the docs hub. Philosophy depth: Titles as orientation.

Cold-reader gate

Title and first paragraph must orient a stranger out of thin air — no prior chat, no product lore, no case-study context.

  • Prefer: Broken links after a URL rename

  • Fail: When the agent names a fork before it looks (private scene)

  • Fail: Path renames that break dependents (dependents is abstract before the hook)

Enthymemic / implication-dense titles

Some titles pack a second title the reader invents without writing it.

One surface phrase + a charged relation to a known object → the reader supplies why? / for what? and arrives ready to accept or reject.

Surface title Second title the stranger invents (approx.)

An alternative to URLs

Why would URLs need an alternative? / Alternative for what job?

Attention is not inventory

Why isn’t attention inventory?

When 'non-technical' products lie

How do they lie?

New ideas meet rejected assumptions

For a novel claim, assume the cold reader has already rejected it (by ignorance or habit). The title reopens the case against that implicit assumption. It is not there to summarize the architecture diagram.

Calculated width

An alternative to URLs is not an overclaim when the body scopes the use-case (URL-as-identity / URL-as-wire). Do not "fix" implication-dense titles into fully scoped thesis titles (URLs as labels, not wires) unless disambiguation was requested over charge.

Agents default to over-explicit titles. Prefer implication density when the common concrete object is already in the reader’s head (URL, not wire).

Title doctrine is not body doctrine

A good H1 does not excuse a briefing-memo opening. Re-run the cold-reader gate on the first paragraph and SEO description after you draft. Symptom faces especially must stay in concrete register (broken link, URL, rename) in the lede — leave wires / labels / identity for later sections.

Slug equals public title

Default: filename and published path match the H1 (kebab-case). Keep a Cool-URI absorb / redirect only when you can name who still hits the old URL. Record absorb decisions in AGENTS.md or the changelog — never in the reader’s opening.

Channel split

Channel What belongs there

Published docs / blog / news

Concrete hooks, implication-dense titles when earned, casual explanation

AGENTS.md, skills, changelogs

Slug history, nicknames, “do not confuse with…”, Cool-URI decisions, session maps

Run Audience / POV pass checks in general/documentation.md after drafting, not only before. Session context outcompetes the stranger unless you re-check.

Agent self-test

Before shipping a title:

  1. Concrete hook? — shared words a stranger already has

  2. Second title? — what question do they invent? Nothing → too flat; wrong job → too vague

  3. Accept/reject fork? — stance forming before paragraph one

  4. Abstraction demoted? — wires / labels / dependents / identity in the body, not stealing the public title

  5. New-idea check? — reopen a rejected assumption, do not only name the in-group concept

  6. Lede check? — paragraph one stays in the same concrete register as the title

Worked cluster (reference durability)

Symptom ↔ diagnosis for URL-as-wire pain (HCI Nerdz / Internet Reliability):

Face Public title

Symptom

Broken links after a URL rename

Diagnosis (and docs H1)

An alternative to URLs

Internal nickname (after the hook)

Labels versus wires

Demo catalog and docs slug should match the public titles. Match the page slug to the public title (an-alternative-to-urls); do not keep opaque Cool-URI absorb names when nobody depends on the old path.

See also