--- name: heddle-playbook description: A tested SEO, AEO and GEO playbook: the technical checklist every page should meet to be found in Google and quoted by AI assistants (each item with its primary source), the SEO mistakes behind each rule, programmatic page patterns and when they become doorway pages, and the checks that catch each failure. Use before changing titles, meta descriptions, canonicals, structured data, sitemaps, robots.txt, llms.txt, internal links or templated pages. --- # Heddle's SEO, AEO and GEO playbook Heddle is a set of agents and build checks that grow a site's search traffic. This skill is its method, the part that is safe to publish: what a page needs to rank in Google and be quoted by AI assistants, and the mistakes that taught each rule. It is a checklist with sources, not a ranking trick; every item is something a search engine, assistant or social network documents that it reads. ## References | File | Read it when | | --- | --- | | `references/tactics.md` | Changing anything in a page's head, its structured data, the sitemap, robots.txt, llms.txt or the Markdown twins: the full checklist, each item with its primary source and the check that holds it | | `references/lessons.md` | Before a decision a lesson covers (titles, page families, reading positions): 33 lessons, each with its evidence and rule | | `references/families.md` | Building or reviewing templated pages: each programmatic pattern, the fields every row needs, and its doorway risk | | `references/checks.md` | Before shipping, or when a check fails: what each check catches | | `references/agents.md` | Working with Heddle's agents: what each does, when it runs, and how far it may act on its own | ## The rules, by area One line per lesson; the evidence for each is in `references/lessons.md`. ### Targeting - Measure demand before choosing any topic or title. - Check what already ranks on pages two to five before writing anything new. - Read the live SERP before shipping a title and lead with the searcher's exact phrase. - Before a product name goes in a title, read the first sentence of the vendor's current documentation page for it. - Identical (volume, cost per click) across phrasings that mean different things is one bucket; the research agent probes each term's neighbours in the same keyword call, strategy plans the bucket at its share and marks it unverified until the results page is read. - A short acronym with a cheap click and an off-subject page-one leader is another meaning; plan it as unknown and target the expanded phrase. - Write the page that resolves the old name to the new one; never adopt the old name, and list it in forbidden claims. ### Programmatic pages - Every family has required per-row fields, and uniqueness is measured on built HTML against a ceiling (80% by the eight-word-sentence measure). - Link every sibling or rotate; link the family in from the footer or a hub. - One page owns each service-and-place search, and a check fails when a second page heads itself with it. - A family may publish only the rows where demand measures. - The headquarters city is in every sibling list, as a row or a `pinned` entry; `validate` warns when it is not. - The `orphans` check reports each family's minimum and median inbound links and warns when either is under its floor; zero is not the only number that matters. ### Structured pages - A statistics page carries a changelog and a refresh trigger, and a position on what the numbers mean; the `statistics` check fails one whose changelog is older than its newest figure. ### Reading results - Read city terms from the city; under sixty results is unreadable. - Positions are read signed out, by the tool. - Split brand from non-brand and filter to the target market before reading a trend. ### Content agents - Every draft is fact-checked against its sources before a person sees it, and the mistake becomes a known-error rule the second time. - Check every state of the queue and the published posts before filing. ### Visuals - Image sizes are measured once into a committed manifest (`heddle images`) and the `images` check fails a built `` that reserves no box. - A page that plays a video carries a VideoObject read off the film, with `uploadDate` as a date-time with its timezone, and the surface check fails one missing a field. ### Operations - The `_headers` writer types every extensionless image by its first bytes, one splat rule per file name, and warns when the file passes the host's 100-rule limit. - Deploy is its own step, and verification probes a string only the new build contains. - Every indexable page is read against Google's own helpful-content questions (`heddle check`, the `helpful` gate), with floors per kind of page and a baseline that only tightens; growing the baseline takes `HEDDLE_HELPFUL_GROW=1` and a reason in the pull request. Its blind spot: a draft that retells a vendor announcement passed every floor on one of our sites, so whether an explainer adds to its sources is still a person's call. Without the model token the gate reports SKIPPED, never PASS, and in CI (or with `--require-model`) `heddle check` fails on it. - The refresh agent re-reads every live page against the helpful questions once a week, keeps a short history of each page's score beside its index status, and lists the pages under a floor for a rewrite. It rewrites nothing itself. - A page whose body is under the thin floor carries `noindex`, decided by its body, not by a slug list, so it comes back on its own once someone writes it. The `meta` check warns on an indexable thin page. - Before a page is pruned or redirected, read its Search Console clicks for the last 90 days; anything with clicks is rewritten or kept, not cut. - `heddle aeo` sends `X-Robots-Tag: noindex` on every share image and on `/_next/static`, and the canary checks it live with the card's `image/*` type. Social networks fetch the card directly and ignore the header. - The `surface` check fails a sitemap whose every lastmod is the build date (`surface.launched` excuses launch day), a lastmod after the build, and a lastmod that disagrees with the page's own `dateModified`. - A date with a time carries an offset, the offset of `surface.timezone` that day, and an Event's start has a time. - `agent-ready` fails a twin whose prose is not on its page or whose heading is not the page's H1. - The `meta` check fails tracking parameters on links to the site's own hosts, and `_gl` anywhere. - `heddle check --only outbound` after any rename or batch of vendor links; never in CI, a redirect passes, and a failure must survive a slower retry.