CLAUDE.md for personal knowledge base (KBX)

CLAUDE.md

CLAUDE.md — Wiki Maintenance Guide

This is an Obsidian wiki covering several knowledge domains (Leadership, Product, and others). Use this guide to keep new and edited articles consistent with the existing ones.

Structure

The wiki has two dimensions: domain (top level) and section (under each domain).

kbx/
├── Home.md                         — Entry point
├── Suggested Topics.md             — Backlog
├── Leadership/
│   ├── Concepts/                   — Mental models and frameworks
│   ├── Dualities/                  — Tensions and trade-offs
│   ├── Principles/                 — Core beliefs
│   ├── Advice/                     — Actionable guidance
│   └── Tools/                      — Techniques you can apply
├── Product/                        — same 5 sections
└── Other/                          — (future) same 5 sections

• Domain = subject area (Leadership, Product, Other, ...). New domains are just new top-level folders.
• Section = article type (Concepts, Dualities, Principles, Advice, Tools). Every domain uses the same 5 sections.
• Each section folder contains an index.md listing its articles alphabetically as [[wiki links]].

Which Section Does a New Topic Belong In?

• Concept — a mental model or named idea (e.g. Conway's Law, Servant Leadership).
• Duality — a tension with two sides, usually "X vs Y" or "X over Y" (e.g. Trust Over Control).
• Principle — a belief stated as a truth (e.g. "Clear communication is hard work").
• Advice — a directive addressed to the reader (e.g. "Hire slow, fire fast").
• Tool — a named technique, test, or framework you can apply (e.g. Keeper Test, STARS Model).

If unsure, Concepts is the safest default.

File Conventions

Filename

• Title case, spaces allowed. Match the topic name from the CSV/source.
• Strip punctuation that causes issues: apostrophes in filenames become nothing (Conways Law.md, Brainstorming Doesnt Work.md).
• Keep filenames reasonably short — shorten long titles for the filename while keeping the full title in the index link.

No H1 Title in File Body

Important: Obsidian renders the filename as the title. Do not include a # Title line at the top of the file — it causes double titles. Article body starts with the one-line hook.

Article Template

<one-line hook — a punchy sentence stating the core idea>

## <First section>
## <Second section>
## <Optional third section — nuance, counterpoint>
## Related

Common Section Headings

Every article follows the same arc: explain → justify → apply → qualify → link. Pick headings from the lists below to keep articles consistent.

Opening section — explain the idea (pick one):

• ## The Idea — default for most articles.
• ## What It Means — when the title already names a known concept.
• ## The Tension — preferred for Dualities.
• ## The Technique or ## The Tool — preferred for Tools.

Middle sections — justify and apply (pick one or two):

• ## Why It Matters — most common; explains stakes and consequences.
• ## How to Apply — actionable steps the reader can take.
• ## How to Navigate — preferred for Dualities instead of "How to Apply".
• ## The Two Sides — a comparison table, almost always in Dualities.
• ## Examples — concrete cases; use when the idea benefits from illustration.

Closing section — qualify (pick one, before Related):

• ## The Trap — most common; the mistake people make with this idea.
• ## The Nuance or ## The Counter — when "trap" doesn't fit; softer qualification.
• ## When It Doesn't Fit — for ideas that only apply in certain contexts.

Always last:

• ## Related — 3-5 wiki links (see Linking Conventions).

Section Patterns by Article Type

These are the most common flows. Deviate when the topic demands it, but prefer these as defaults:

• Concept: hook → The Idea / What It Means → Why It Matters → How to Apply → The Trap → Related
• Duality: hook → The Tension → The Two Sides (table) → How to Navigate → The Trap → Related
• Principle: hook → The Idea → Why It Matters → How to Apply → The Trap → Related
• Advice: hook → The Idea / Why → How to Apply → The Trap → Related
• Tool: hook → The Technique / The Tool → Why It Matters → How to Apply → The Trap → Related

Length

• Short. Target 15-40 lines of body content per file. If a file grows past ~50 lines, split it.
• Prefer bullet lists over paragraphs.
• One idea per section. 2-4 sections per file.

Voice & Style

• Plain language. Short sentences. Avoid jargon. Avoid academic tone.
• Direct. Address the reader as "you." State things as claims, not hedged suggestions.
• Concrete. Give examples, especially engineering-specific ones.
• Balanced. Most articles include a "when NOT to apply" or "the trap" section. Leadership ideas are rarely absolute.
• No emojis.
• British English spelling. Stay consistent within a file.

Formatting Conventions

• Use **bold** for key terms and labels in bullet lists (e.g. - **Speed vs Quality** - Ship fast or ship right?).
• Use > blockquotes for quotations and attributed sayings.
• Use tables for 2-column comparisons (common in Dualities).
• Headings use Title Case.

Linking Conventions

Wiki Links

• Same folder: [[Article Name]]
• Cross section within same domain: [[../Section/Article Name|Display Name]] (e.g. from inside Leadership/Tools/ link to [[../Principles/Some Article]])
• Cross domain: [[Domain/Section/Article Name|Display Name]] (vault-root-relative), e.g. [[Leadership/Concepts/Servant Leadership|Servant Leadership]]
• Use the pipe | to customise display text when the link would otherwise break reading flow.

Related Section

• Every article ends with a ## Related section.
• 3-5 links, no more.
• Link to the closest conceptual neighbours, not everything vaguely related.
• When you add a new article, update the Related sections of at least 2-3 existing articles that should link back to it.

When Adding a New Article

1. Decide on the domain (Leadership / Product / Other / ...). If the domain doesn't exist yet, create it as a top-level folder with the 5 section subfolders and an index.md in each.
2. Decide on the section (Concepts / Dualities / Principles / Advice / Tools).
3. Create the file in <Domain>/<Section>/, no H1 title.
4. Add a link to that section's index.md in alphabetical order.
5. Update Related sections of 2-3 existing articles to link back.
6. If the topic came from Suggested Topics.md, remove it from there.

When Editing an Existing Article

• Preserve the template structure (hook, 2-3 sections, Related).
• Keep the length short. If adding content pushes it long, consider whether it should be a new article instead.
• Don't add an H1 title.
• Keep spelling conventions consistent with the existing file.

Tone Summary — The Kind of Article This Wiki Wants

• Opens with a punchy one-liner stating the core idea.
• Explains in plain words what it means and why it matters.
• Gives concrete examples, ideally from engineering contexts.
• Includes a limit, trap, or counter-case — leadership ideas are balanced, not absolute.
• Ends with 3-5 links to related ideas.
• Feels like a note a senior engineer wrote to a junior one, not a textbook.

What to Avoid

• Long paragraphs.
• Academic or management-consultant language.
• Absolutist claims without nuance.
• Emojis.
• H1 titles in the file body (Obsidian already shows the filename).
• Creating new top-level folders without a strong reason.
• Cross-links that don't help the reader — every Related link should feel useful.