Writing system

Thinking Bugs Writing System

The playbook/ folder is the public writing system for Thinking Bugs. WRITING.md is the legacy detailed rule file; this playbook is the framework version that adds briefs, visible process, pass logs, author credits, receipt pages, and agent prompts.

Thinking Bugs explains common patterns of unhelpful thinking in plain language. Every page should help a reader recognize a pattern, understand why it happens, see the cost in real life, and practice a more useful reframe.

Related docs:

• engine.md - the reusable method behind the playbook.
• cursor-prompts.md - prompt packs for writing agents.
• style-guide.md - SEO, markup, and credit conventions.
• brief-template.md - copy before drafting a new article.
• data/authors.json - exact public names for models that have article credits.

1. Core promise

Every article must make four things clear:

1. What thinking bug is being described?
2. Why does it happen?
3. What does it cost in everyday life?
4. What can the reader try instead?

The article describes a pattern, not a bad person. It should give readers a handle, not a diagnosis or a moral label.

2. The belonging test

A new page earns a slot only when the pattern is:

• specific enough to recognize;
• distinct from existing entries;
• grounded in research, clinical writing, or a well-documented reasoning pattern;
• useful in everyday life;
• correctable through awareness, questioning, prevention, or reframing.

Do not add a page for a contested metaphysical position, a spiritual claim without an empirical kernel, or a near-duplicate of an existing bug. If the idea belongs inside another article, fold it in there.

3. Article shapes

Thinking Bugs uses a shared map so readers can scan, but not a rigid template. Pick the shape in the brief before drafting.

Shape names are internal scaffolding. Do not put them in reader-facing article prose.

4. Required article map

Specimen pages use this order unless the brief explains a deliberate exception:

1. <h1> - distortion or bug name.
2. <h3> - one-line description.
3. Explained - define the pattern in plain language and state the boundary when needed.
4. Examples - 4 to 8 concrete quote examples.
5. Real-world scenarios - optional, only when settings help.
6. Impact - practical cost.
7. Causes - why the pattern happens.
8. Research - 2 to 4 named sources where the article makes research claims.
9. How to spot it in yourself - optional, 3 to 6 crisp signs.
10. Prevention - practical moves calibrated to stakes.
11. Questions & Answers - optional, only for sharp bug-specific edge questions.
12. Reframing - 2 to 3 realistic reframes plus the app note.
13. Related thinking bugs (and how they differ) - 3 to 5 links at the bottom.

Fewer, denser sections beat many thin ones. Do not add a heading just to spend a template slot.

5. Evidence and sources

Every catalog entry should be connected to named research, a clinical concept, or a documented reasoning pattern. The Research section is where most named authors, years, and study details belong.

When a source is verified, add it to data/article-references.json. Never invent titles, DOIs, years, or effect sizes. If unsure, omit or hedge.

6. Voice

The voice is simple, direct, practical, and kind. It should sound like a clear explanation from someone helping the reader notice a pattern, not like a diagnosis, a moral lecture, or a therapy session.

• Prefer concrete examples over abstract labels.
• Use short paragraphs.
• Avoid prescriptive therapy language.
• Do not shame the reader.
• Do not overstate certainty.
• Keep humor gentle and rare.
• Explain boundaries without stamping the same boundary formula on every page.

7. Anti-template rules

Do not use:

• a separate In one line section;
• a separate stress/anxiety section;
• a What to do in 60 seconds section;
• a generic FAQ section;
• numbered section headings;
• numbered reframing labels;
• repeated author-year research hooks on every page;
• quote lists buried inside Explained;
• the same Work / Health / Relationships / Online scenario grid on every page.

A shared map is useful. Repeated sentence machinery is not.

8. AI authorship and public trust

Thinking Bugs can use AI-assisted writing openly. Trust comes from visible process: article credits, revision notes, source metadata, briefs, and receipt pages.

Credits

Article credits live in data/article-credits.json, keyed by slug. Public names should match playbook/data/authors.json. The roster is the models that appear in the credit log. An older label for the same model is mapped in playbook/config.php under model_aliases, so the playbook shows one name and one portrait.

For new framework-style passes, prefer this edit shape:

{
  "date": "YYYY-MM-DD",
  "pass": "research | draft | fact-check | voice | rewrite | review | publish check",
  "model": "Fable 5",
  "note": "One reader-facing line about what changed."
}

The legacy Thinking Bugs shape {author, at, message} is still supported. Do not rewrite old credit history just to normalize it.

Never credit Cursor Agent, Thinking Bugs Editorial, 8020.in Editorial, or a guessed model name. If the human did not provide the model name for an article pass, ask before logging the pass.

9. Brief gate

Before drafting a new article, copy playbook/docs/brief-template.md to playbook/briefs/<slug>.md and fill it. Do not outline until the brief contains:

• the reader's real question;
• the bug claim in one sentence;
• why the article belongs in the catalog;
• nearby bugs and how this one differs;
• sources to check;
• the article shape;
• the examples, prevention moves, and reframes planned;
• the credit model/person for the pass.

For rewrites, inventory the existing page first: sections, examples, sources, reframes, related links, credits, and distinctive wording. The rewrite must be better without becoming thinner.

10. Publish checklist

Human editorial gate

1. The article describes a correctable thinking pattern, not a person type.
2. The pattern is distinct from existing entries or the overlap is explained.
3. The article starts with a clear plain-language explanation.
4. Examples are concrete and varied.
5. Impact, causes, research, prevention, and reframing each add new value.
6. Research claims match real sources and data/article-references.json is updated when needed.
7. Advice is practical, non-clinical, and proportionate to stakes.
8. Tone is kind, direct, and not shaming.
9. Related links explain differences, not just navigation.
10. Credits are updated and the pass log names the real model/person.

Mechanical check

1. Required files are updated: content, route, ratings, menu mapping, footer nav, credits, and references when applicable.
2. No banned sections or numbered headings appear.
3. No em dash appears; use - .
4. No <i> or <em> appears in article content.
5. Reframing app CTA and bottom spacer are present on specimen pages.
6. php tools/validate-bug-data.php prints OK after metadata changes.
7. The article, category page, and home catalog render without PHP warnings.
8. Open /playbook/made/<slug> and review the public receipt.