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

After adding a new specimen, regenerate derived catalog files as described in WRITING.md.