SEO & style

Rendered from playbook/docs/style-guide.md.

Thinking Bugs SEO & Style Conventions

This file owns SEO, article length, uniqueness, markup, and credit label conventions. The full editorial rules and the only publish checklist live in writing-system.md.

1. Length and depth

Most new specimen pages should be closer to recent fuller entries than to old stubs: roughly 90 to 130 source lines when the topic needs it. Do not pad. Add detail only when it improves recognition, evidence, prevention, or reframing.

A short sharp page is better than a long repetitive one. A page is too thin when the reader can name the bug but cannot recognize it in themselves or try a useful reframe.

2. Uniqueness

Every article needs a reason to exist apart from nearby entries.

  • Check bugs-by-category.json before adding a new page.
  • Use Related thinking bugs (and how they differ) to explain close neighbors.
  • Do not create a new domain category entry for a general-purpose bug just because the examples often happen there.
  • Use intent tags for context (money-biases, social-media, at-work) instead of duplicating taxonomy.

3. SEO conventions

  • Route title format: <Name> - <Category Singular> | Thinking Bugs.
  • Leave route description empty unless there is a real hand-written reason to add one.
  • The content <h3> is the short bug description used by widgets.
  • Intent tags live in data/bug-ratings.json and includes/bug-tags.php.
  • Tags should be search-intent phrases, not duplicate family slugs.
  • Use 1 to 3 tags per bug.

4. Markup rules

  • Never number section headings.
  • Do not add <h4>In one line</h4>.
  • Keep Examples immediately after Explained.
  • Do not add <h4>FAQ</h4>.
  • Use Questions & Answers only when the questions are specific and useful.
  • Do not use em dashes. Use - .
  • Avoid italics completely: no <i> or <em>.
  • Do not use bold or italics inside paragraph sentences. Bold is allowed only for structured lead labels.
  • Related links use <?php echo htmlspecialchars($basePath); ?>slug style.

5. Credits

Credits live in data/article-credits.json. Public model/person names should match playbook/data/authors.json.

Supported legacy edit row:

{"author": "Grok 4.5", "at": "2026-07-19 23:20:00", "message": "Rebuilt examples section"}

Preferred framework row for new passes:

{"date": "2026-09-26", "pass": "voice", "model": "Fable 5", "note": "Made examples more concrete and removed shaming language."}

Forbidden credit labels: Cursor Agent, Thinking Bugs Editorial, 8020.in Editorial, Writer tool, and guessed model names.

6. Validation

After adding or changing article metadata, run:

php tools/validate-bug-data.php

A new specimen is integrated when all of these exist:

  • content/<slug>.php
  • a routes.json entry with a title and an empty description
  • the same menu entry in index.php ($menuMapping) and tools/menu-mapping-data.php, placed next to the closest bug: '/slug' => ['category' => '<key>', 'current' => '<Abbr>']. Category keys: cbt, rebt, cd, lf, je, stt, ep, pb, bt, rb, modern, money. Abbreviation must be unique.
  • a footer block in includes/menu-bottom-<category>.php
  • data/bug-ratings.json with all 10 trait scores and 1 to 3 intent tags
  • data/article-credits.json

Then regenerate derived files:

php tools/export-bugs-json.php > tools/bugs-data.json
php tools/dump-bugs-by-category.php
php tools/build-og-thumbs.php --specimens --only=<slug>

On Windows PowerShell, write the export as UTF-8: php tools/export-bugs-json.php | Set-Content -Encoding utf8 tools/bugs-data.json. OG thumbs need Node; see tools/og-thumbs.md. The sitemap is generated from routes.json.