<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
    <channel>
        <atom:link href="https://scribelet.app/blog/rss.xml" rel="self" type="application/rss+xml"/>
        <title>Scribelet Blog</title>
        <link>https://scribelet.app/blog</link>
        <description>Insights on knowledge management, productivity, and building a smarter second brain with AI.</description>
        <lastBuildDate>Fri, 06 Nov 2026 07:58:15 GMT</lastBuildDate>
        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
        <generator>https://github.com/jpmonette/feed</generator>
        <language>en</language>
        <image>
            <title>Scribelet Blog</title>
            <url>https://scribelet.app/logo.png</url>
            <link>https://scribelet.app/blog</link>
        </image>
        <copyright>All rights reserved 2026, Scribelet</copyright>
        <item>
            <title><![CDATA[The Best Obsidian Plugins in 2026 (and Which to Skip)]]></title>
            <link>https://scribelet.app/blog/best-obsidian-plugins</link>
            <guid isPermaLink="false">https://scribelet.app/blog/best-obsidian-plugins</guid>
            <pubDate>Thu, 05 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The best Obsidian plugins in 2026, grouped by what you actually do: core plugins, essentials, picks for developers, students, and writers, with honest tradeoffs.]]></description>
            <content:encoded><![CDATA[
Obsidian does not have a plugin problem. It has a plugin abundance problem. There are [more than two thousand community plugins](https://community.obsidian.md/), and the moment you discover that, the temptation is to install twenty of them in an afternoon and turn your vault into a dashboard you spend more time configuring than writing in.

So the useful question is not "what are all the best Obsidian plugins." It is "which handful actually earns a permanent place in my vault, and which ones look impressive for a week and then sit there as dead weight." Because every plugin you install is one more thing that can break after an app update, go unmaintained when its author moves on, or quietly change behavior in a way you only notice when a note looks wrong.

This guide covers the plugins worth keeping, grouped by what you are actually trying to do, with an honest note on what each one costs you in upkeep. Start with the core plugins, then add community ones deliberately, not by the dozen.

## What are the best Obsidian plugins?

The best Obsidian plugins are the few that change how you work rather than how your vault looks. For most people that is a short list: **Dataview** to turn notes into queryable data, **Templater** to automate repetitive note creation, **Obsidian Tasks** for task management across your vault, and the built-in **Backlinks**, **Daily notes**, and **Bases** core plugins before you install anything from the community at all.

The right set depends on the job. The table below is the quick version; the rest of this guide is the reasoning, including what each plugin is bad at.

| Plugin | Type | What it does | Watch out for |
|---|---|---|---|
| Bases | Core (built-in) | Database-like views over note properties | Newer, no relational links between tables |
| Dataview | Community | Queries notes, tasks, and metadata as a live database | A query language to learn; heavy vaults slow down |
| Templater | Community | Scriptable templates and automated note creation | Scripting power invites over-engineering |
| Obsidian Tasks | Community | Due dates, recurrence, and a global task query | Only sees tasks you format its way |
| Calendar + Periodic Notes | Community | Sidebar calendar and weekly/monthly notes | Two plugins to keep in sync |
| Omnisearch | Community | Fuzzy, full-text search across the whole vault | Duplicates some native search |
| Obsidian Git | Community | Version history and backup via Git | Assumes you are comfortable with Git |
| Excalidraw | Community | Hand-drawn diagrams and sketches inside notes | Drawings live in their own file format |

If you already suspect the real issue is not which plugins to add but keeping what is in your notes accurate over time, you can [try Scribelet free](https://scribelet.app/pricing) and come back. Otherwise, start where every vault should: the core plugins.

## Turn on the core plugins first

Before you open the community directory, go to Settings and look at the core plugins. These ship with Obsidian, are maintained by the Obsidian team, and will never be abandoned by a solo developer. They cover more than most people realize ([Obsidian Help](https://help.obsidian.md/)).

- **Backlinks and Outgoing links** are the whole point of a linked notes system. Turn them on and every note shows what references it. This is what people install graph plugins to approximate, and it is already built in.
- **Daily notes** gives you a dated note on demand, the backbone of journaling and meeting capture.
- **Templates** handles the common case of inserting a boilerplate structure. Only reach for Templater (below) when you need logic the core plugin cannot do.
- **Bases** is now a core plugin, not a community add-on. It gives you database-like table, card, and list views over the properties in your notes, which closes a lot of the gap people used to fill with Dataview. It is newer, so it does not yet do relational links between tables the way a true database does.
- **Canvas** is an infinite spatial board for arranging notes visually, also built in.

The lesson of the core plugins is the lesson of the whole ecosystem: add capability only when the built-in tool genuinely falls short. If you want the longer version of that argument, Obsidian's whole premise is that a [folder of plain Markdown files](https://scribelet.app/blog/markdown-note-taking-apps) should outlive any one app, and every plugin you bolt on is a small bet against that portability.

## The essential community plugins

If you install nothing else from the community, install these. They are mature, widely used, and solve problems the core plugins leave open.

### Dataview

Dataview turns your vault into a database. You write a query in a code block and it renders a live table or list of notes matching your criteria: every book note with a rating above four, every task due this week, every meeting that mentions a project. It is the single most powerful thing you can add to Obsidian ([Dataview](https://github.com/blacksmithgu/obsidian-dataview)).

Watch out for: it is a query language, so there is a learning curve, and on a very large vault complex queries can slow rendering. With Bases now built in, try the core plugin first for simple table views and reach for Dataview when you need real querying. This is the same [database versus a folder of files](https://scribelet.app/blog/notion-vs-obsidian) question that separates Obsidian from Notion, except here you get to choose how far down the database road you go.

### Templater

Templater is the scriptable version of the core Templates plugin. It can insert the current date, prompt you for input, run small scripts, file a new note into the right folder automatically, and chain all of that into one command. If you create the same kind of note often, Templater removes the friction.

Watch out for: the power to script invites over-engineering. A template that calls three functions and prompts for four fields is a template you will eventually stop using because capturing a thought should not feel like filling in a form.

### Obsidian Tasks

Obsidian Tasks adds real task management on top of Markdown checkboxes: due dates, scheduled dates, recurring rules, priorities, and a global query that pulls every open task across your vault into one view. For people who keep tasks next to the notes that spawned them, it is close to essential.

Watch out for: it only recognizes tasks written in its format, so the discipline has to be yours. A checkbox you typed quickly without the right emoji syntax will not show up in the query.

### QuickAdd, Calendar, Periodic Notes, and Omnisearch

Four more that routinely make "essential" lists for good reason. **QuickAdd** turns multi-step captures into one keyboard shortcut. **Calendar** adds a clickable month view tied to your daily notes, and **Periodic Notes** extends that to weekly, monthly, and yearly notes. **Omnisearch** gives you fuzzy, full-text search that many people find faster than the native search.

Watch out for: Calendar and Periodic Notes are two plugins doing one job, so you have two update streams to track, and Omnisearch overlaps the built-in search enough that you should confirm you actually prefer it before keeping both.

## The best Obsidian plugins for developers

If you live in a terminal, a few plugins make Obsidian feel like part of your toolchain.

- **Obsidian Git** commits your vault to a Git repository on a schedule, giving you real version history and an off-device backup. It is the most reliable backup story for a local vault, as long as you are comfortable with Git conflicts when you edit from two machines.
- **Advanced Tables** makes Markdown tables bearable to edit, auto-formatting columns as you type and adding spreadsheet-style navigation.
- **Excalidraw** embeds hand-drawn diagrams and sketches directly in notes. Architecture sketches, flow diagrams, and whiteboard thinking all live inside the vault instead of in a separate app. The drawings save in their own file format, so they are a little less portable than the rest of your Markdown.

For anything involving diagrams you want to keep in version control rather than as exported images, the same instinct that makes developers reach for these plugins is why diagrams-as-text approaches exist at all.

## The best Obsidian plugins for students and research

For reading-heavy work, two categories matter.

- **Citations and Zotero integration** plugins pull references from your Zotero library into notes, so a literature note links back to its source with a proper citation. This is the backbone of a research vault.
- **Spaced Repetition** turns notes into flashcards and schedules reviews, bringing active recall into the same app you take notes in. If you are a student choosing a tool for the first time, it is worth seeing how Obsidian stacks up against the dedicated options in a broader roundup of [the best note-taking apps for students](https://scribelet.app/blog/best-note-taking-app-for-students) before you commit to building a plugin stack.

Watch out for: research plugins are often maintained by one person, and a Zotero connector that breaks after a Zotero update can strand your workflow mid-semester. Keep the plain citation text in the note, not only the plugin-rendered version.

## The best Obsidian plugins for writers

Long-form writers have their own shortlist. **Longform** organizes scenes and chapters into a single compiled manuscript, so a novel or a dissertation lives as linked notes but exports as one document. Focus and typewriter-style plugins dim everything except the active line and keep your cursor centered, which some writers find removes the friction of a busy interface.

Watch out for: a manuscript spread across dozens of plugin-managed files is only as recoverable as the plugin that assembles it. Export a plain copy periodically so a chapter is never trapped inside a tool.

## Plugins for mobile and sync

Not every plugin works on the Obsidian mobile app, and the ones that do can drain battery or slow startup on a large vault. Check a plugin's mobile support before you rely on it away from your desk. Sync is its own decision: Obsidian's official Sync is the simplest, Obsidian Git works if you are technical, and third-party options exist with their own tradeoffs.

This is also where the plugin model shows its edges. A vault that depends on ten plugins to be usable is a vault that behaves differently on every device, which is the opposite of what you want from [a note app that works everywhere](https://scribelet.app/blog/cross-platform-note-taking-app).

## A note on AI plugins

AI in Obsidian is its own topic, with several routes that each send a different share of your vault to a model. Rather than squeeze it into this list, we wrote it up separately: here are [the AI plugins for Obsidian, with a verdict on each](https://scribelet.app/blog/obsidian-ai), including the privacy tradeoff of each approach.

## Which plugins should you actually install?

Here is the short answer by what you do. Install the core plugins in every case; add from this list only what your actual work calls for.

| If you mostly | Install |
|---|---|
| Want structure without a learning curve | Bases (core), Templates (core) |
| Query and track things across notes | Dataview, Obsidian Tasks |
| Automate repetitive capture | Templater, QuickAdd |
| Write code or keep backups | Obsidian Git, Advanced Tables |
| Do reading-heavy research | Citations, Spaced Repetition |
| Write long-form | Longform, a focus plugin |
| Draw and diagram | Excalidraw, Canvas (core) |

![A decision map matching what you mostly do in Obsidian to the plugins worth installing: wanting structure without a learning curve points to the built-in Bases and Templates, querying and tracking across notes points to Dataview and Obsidian Tasks, automating capture points to Templater and QuickAdd, writing code or keeping backups points to Obsidian Git and Advanced Tables, and reading-heavy research points to Citations and Spaced Repetition.](/blog/best-obsidian-plugins/pick-by-what-you-do.svg)

The honest version of this table is a number: most people are well served by four or five plugins, and the difference between a vault that helps and a vault that fights you is usually restraint, not coverage.

## When the plugin stack becomes the maintenance problem

Here is the pattern worth naming. You install plugins to make your notes do more. Each one adds capability. Each one also adds a thing that can break, an author who can disappear, and a format that may not survive the next migration. Past a certain point, the plugins stop being tools and become the maintenance burden they were supposed to remove.

And none of them address the quieter problem underneath. A plugin can query, format, link, and schedule your notes beautifully, and every one of those notes can still be wrong. The React pattern you documented got deprecated. The pricing you noted changed. The link you saved rotted. No plugin on this list checks whether what you wrote is still true.

That is the gap Scribelet is built around. Scribelet is not an Obsidian plugin; it is a notes app whose AI runs background checks against the web on a schedule you set and shows you a diff when something you wrote has gone out of date, with the source. You bring your own API key if you want provider control, or use the included AI out of the box. If the real reason you keep adding plugins is that your notes feel like they need looking after, you may want [an Obsidian alternative that maintains your notes](https://scribelet.app/blog/obsidian-alternative) rather than one more plugin to maintain.

Either way, the principle holds across every PKM system: capturing and organizing are solved problems, and [the maintenance step every framework skips](https://scribelet.app/blog/personal-knowledge-management) is where notes quietly go stale. Plugins make Obsidian more capable. They do not make your notes more trustworthy.

## The short list

If you take one thing from this guide, make it restraint. Turn on the core plugins, especially Backlinks, Daily notes, and Bases. Add Dataview and Templater when you have a real use for them. Add the rest only when your work asks for it, and remove anything you have not touched in a month. A lean vault is faster, more portable, and far less likely to break the week you need it most.

And when the thing you actually want is not more capability but more confidence that your notes are still accurate, that is a different tool. [Try Scribelet free](https://scribelet.app/pricing) and see your first diff.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>obsidian</category>
            <category>obsidian-plugins</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>productivity</category>
        </item>
        <item>
            <title><![CDATA[The Best Note-Taking App for Students in 2026]]></title>
            <link>https://scribelet.app/blog/best-note-taking-app-for-students</link>
            <guid isPermaLink="false">https://scribelet.app/blog/best-note-taking-app-for-students</guid>
            <pubDate>Wed, 04 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The best note-taking app for students depends on how you study. Eight apps compared by use case: handwriting, typing, flashcards, ownership, and AI.]]></description>
            <content:encoded><![CDATA[
Nobody has a note-taking problem in the first week of a semester. The notebook is clean, the app is new, and every lecture lands neatly in the right place. The problem shows up around week nine, the night before a midterm, when you go looking for one definition and find it in an app you abandoned in September, or buried in a 40-page document with no headings, or written down wrong because the lecturer corrected it the following week and you never went back.

So the honest answer to what is the best note taking app for students is not a single name. It depends on how you capture (handwriting or typing) and how you study (reviewing, connecting ideas, or drilling for recall). A pre-med student memorizing anatomy with flashcards needs a different tool than a philosophy student building one argument across a semester of reading. This guide covers eight apps, grouped by the job each is actually good at, so you can match the tool to how you work instead of to a feature list.

## What is the best note-taking app for students?

There is no universal best note-taking app for students, but there is a clear best one for each way of working. If you handwrite on an iPad, choose Goodnotes or Notability. If you type and want folders and structure, choose Notion, OneNote, or Apple Notes. If you study with flashcards and spaced repetition, choose RemNote. If you want a portable system you own outright, choose Obsidian. And if your notes are mostly typed and you want to ask questions across all of them and catch the ones that have gone out of date, choose Scribelet.

The quick version is the table below. The rest of this guide is the reasoning behind each pick, including what every app is bad at, because the thing an app does badly is usually the reason students quietly stop opening it by October.

| App | Platforms | Capture style | Free tier | Best for |
|---|---|---|---|---|
| Goodnotes | iPad-first (also Mac, Windows, Android) | Handwriting | Limited | Annotating slides and PDFs by hand |
| Notability | iPad, iPhone, Mac | Handwriting plus audio | Limited | Recorded lectures tied to your notes |
| Notion | Web, Mac, Windows, iOS, Android | Typing | Yes (personal) | An all-in-one semester workspace |
| OneNote | Windows, Mac, Web, iOS, Android | Typing plus handwriting | Yes | A free-form digital binder |
| Apple Notes | Apple devices only | Typing plus handwriting | Yes | Instant capture you already have |
| RemNote | Web, Mac, Windows, iOS, Android | Typing (flashcards) | Limited | Memorization and active recall |
| Obsidian | Mac, Windows, Linux, iOS, Android | Typing (Markdown) | Yes (personal) | A portable system you own |
| Scribelet | iOS, Web | Typing plus voice | Yes (AI capped) | Querying and fact-checking notes |

If you already know you type far more than you handwrite, you can [try Scribelet free](https://scribelet.app/pricing) and jump to how an AI-first notes app handles study material. Otherwise, start with how you capture.

![A five-row decision map matching a study situation to a recommended app: handwriting on an iPad to Goodnotes or Notability, typing with organization to Notion, OneNote, or Apple Notes, flashcard revision to RemNote, a portable linked system to Obsidian, and querying and fact-checking with AI to Scribelet.](/blog/best-note-taking-app-for-students/pick-by-what-you-do.svg)

## Best for handwriting: Goodnotes and Notability

If you take notes by hand, nothing beats an iPad, a stylus, and an app built around them. Typing is faster, but handwriting wins in any subject heavy on diagrams, equations, or marking up a lecturer's slides.

### Goodnotes

Goodnotes turns an iPad and an Apple Pencil into a near-perfect replacement for paper. Writing feels natural, you can annotate imported PDFs and slide decks directly, and search can even read your handwriting. It is the default in subjects full of diagrams and worked problems, like biology, engineering, and mathematics ([Goodnotes](https://www.goodnotes.com/)).

Watch out for: it is built for tablets, so without an iPad and a stylus you lose most of the point, and it keeps your pages in its own format rather than plain files. Best for: handwriting lecture notes and annotating slides and PDFs on a tablet.

### Notability

Notability covers the same ground with one feature students prize above all others: it records audio while you write and links each pen stroke to the moment in the recording. Tap a word in your notes three weeks later and it jumps straight to what the lecturer was saying when you wrote it. For fast-talking lectures, that is close to a superpower.

Watch out for: the features students want most sit behind a subscription, and like Goodnotes it is happiest on Apple hardware. Best for: recorded lectures where you want to replay the exact moment behind a note.

## Best for typing and organizing: Notion, OneNote, and Apple Notes

Most students type. If that is you, the question is how much structure you want and how much lock-in you can live with.

### Notion

Notion is a flexible workspace: pages nested inside pages, databases, tables, and templates for everything from a reading list to a thesis tracker. Students use it to run an entire semester in one place. It is free for personal use, and students can unlock an upgraded plan at no cost with a school email ([Notion](https://www.notion.com/)).

Watch out for: the flexibility is also the trap. It is easy to lose an evening building a beautiful dashboard instead of studying, and large workspaces get slow and lean on a connection. If you want the trade-offs spelled out against the other heavyweight, our [Notion vs Obsidian](https://scribelet.app/blog/notion-vs-obsidian) comparison covers the two apps most students weigh against each other.

### OneNote

OneNote is the free-form binder: type anywhere on an infinite canvas, mix typing and handwriting, and organize into notebooks, sections, and pages. It is genuinely free from Microsoft, and many students already have it through a school Microsoft 365 account ([Microsoft OneNote](https://www.microsoft.com/en-us/microsoft-365/onenote/digital-note-taking-app)).

Watch out for: the free-form canvas that feels liberating in September gets hard to search by April, and your notes are tied to Microsoft and OneDrive. Best for: a flexible digital binder when you already live in the Microsoft ecosystem.

### Apple Notes

Apple Notes is the one you already have. Instant capture from the lock screen, solid handwriting and document scanning, reliable iCloud sync, and no cost. For a lot of students it is simply enough, and the best app is the one you actually open.

Watch out for: it is Apple-only, and getting your notes out later, with formatting and attachments intact, is genuinely hard. That matters the day you switch phones or decide you want your notes in a portable format. We dig into that exact trade-off in [Obsidian vs Apple Notes](https://scribelet.app/blog/obsidian-vs-apple-notes).

## Best for revision: RemNote

RemNote is built for the one thing most apps treat as an afterthought: turning notes into flashcards for spaced-repetition review. Write a note, mark the parts you need to remember, and it schedules them to come back at the moment you are about to forget. Medical, law, and language students lean on it hard, because their courses are memorization at scale ([RemNote](https://www.remnote.com/)).

Spaced repetition and active recall are not RemNote marketing; they are the two study methods with the strongest evidence behind them, which is why it is worth structuring your notes around them. If you want the habit without committing to one app's model, our guide on how to [remember what you read](https://scribelet.app/blog/how-to-remember-what-you-read) covers the same principles.

Watch out for: the flashcard-first structure is more scaffolding than casual note-takers want, and the best features are paid. Best for: memorization-heavy courses where recall is the whole game.

## Best for a system you own: Obsidian

Obsidian stores your notes as plain Markdown files on your own device, with backlinks and a graph that connect ideas across an entire degree. For a student building a long-term body of knowledge (a dissertation, a research area, a set of notes you want to keep after graduation), it is the one that still opens in five years, because the notes are just files on a disk.

It is free for personal use, and it runs on every major operating system, which matters if you move between a university lab machine and your own laptop. If plain-text portability is what you care about, it sits alongside the other [markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) worth comparing, and the broader case for a tool that follows you everywhere is in our guide to [cross-platform note apps](https://scribelet.app/blog/cross-platform-note-taking-app).

Watch out for: it asks for more setup than the others, and it has no handwriting. Best for: students building a connected, portable knowledge base they intend to keep for years.

## Best for querying and fact-checking your notes: Scribelet

Scribelet is an AI-first notes app, and it is honest about who it is not for: if you take notes by hand with a stylus, pick Goodnotes or Notability instead, because Scribelet has no handwriting. It is built for students who type their notes and want to do two things the apps above cannot.

The first is asking questions across every note at once. Scribelet's chat searches your own notes and answers with citations back to the exact note, so before an exam you can ask what the lecturer said about a topic and get an answer grounded in your own material rather than the open internet. The second is catching the notes that have gone out of date. Background checks compare your notes against current sources and show you a diff when a fact has changed, which is precisely the week-nine problem from the start of this guide: the corrected formula, the new textbook edition, the study that got retracted while your notes kept repeating the old claim with total confidence. Notes going quietly stale is a real and under-discussed problem, and we explain the mechanism in our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay). Treating [AI fact-checking for notes](https://scribelet.app/blog/ai-fact-checking-for-notes) as its own discipline, separate from writing, is what keeps study material trustworthy.

It runs on iOS and in any browser, and the free tier includes AI, with verification capped on the free plan and the full set on Pro. You can bring your own API key if you want to choose the model and keep your data routed through a provider you trust rather than one picked for you. If your notes are sensitive, a [secure note-taking app](https://scribelet.app/blog/secure-note-taking-app) that encrypts your content at rest matters more than any single feature. Best for: students who type and want their notes searchable, answerable, and kept accurate. You can [try it free](https://scribelet.app/pricing).

## How to choose: a pick-by-situation table

Skip the feature comparison and match your situation to a starting point.

| Your situation | Start with |
|---|---|
| I handwrite on an iPad and annotate slides | Goodnotes |
| I handwrite and want lectures recorded alongside | Notability |
| I type and want one organized workspace | Notion or OneNote |
| I want the simplest thing already on my phone | Apple Notes |
| I need to memorize a lot for exams | RemNote |
| I want notes I will still own after graduation | Obsidian |
| I type and want to query and fact-check my notes | Scribelet |
| I am on a tight budget | OneNote, Apple Notes, or Obsidian (all free) |

Most students end up using two apps, not one, and that is fine. A common pairing is one for fast capture (Apple Notes or Goodnotes) and one for the knowledge you keep and revise (Obsidian, RemNote, or Scribelet). The seam only hurts if you never move anything from the first into the second.

## The part every note-taking app for students skips

Every app on this list helps you capture and organize. Not one of them, by default, tells you when a note has gone wrong. That is the gap that catches students out, because course material is not static: a lecturer corrects something the next week, a reading gets a new edition, a cited study is retracted, and your notes carry on stating the old version with complete confidence. You do not find out until the exam, or worse, until after it.

Capture and organization are solved problems; a dozen good apps do them well. What almost nothing does is maintenance, the quiet work of keeping notes accurate after you write them. When you compare note-taking apps for students, weight that row the way you weight handwriting or price, because it is the one that decides whether the notes you spend a semester building are an asset at finals or a liability you half-remember to distrust.

## The bottom line

The best note-taking app for students is the one that fits how you actually capture and study, not the one with the longest feature list. Handwrite on an iPad and it is Goodnotes or Notability. Type and organize and it is Notion, OneNote, or Apple Notes. Drill for recall and it is RemNote. Build something you keep and it is Obsidian. Type and want your notes searchable, answerable, and kept accurate and it is Scribelet.

Whichever you pick, remember the row the comparison charts leave off: the notes still drift out of date across a semester, and the tool that flags what changed is doing the one job that protects the hours you put into them. If that is the problem you keep running into, you can [try Scribelet free](https://scribelet.app/pricing) and see what it looks like when your notes check themselves.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>note-taking</category>
            <category>students</category>
            <category>note-taking-apps</category>
            <category>productivity</category>
            <category>study</category>
        </item>
        <item>
            <title><![CDATA[Hanlon's Razor: Assume Error Before You Assume Malice]]></title>
            <link>https://scribelet.app/blog/hanlons-razor</link>
            <guid isPermaLink="false">https://scribelet.app/blog/hanlons-razor</guid>
            <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Hanlon's razor: never attribute to malice what is adequately explained by error. How to apply it to broken builds, AI answers, and your own notes. Try it free.]]></description>
            <content:encoded><![CDATA[
The deploy goes out, and ninety seconds later your service is throwing errors it was not throwing before. You check the commit log and the only change is a merge from the one teammate you have been quietly annoyed with all week. The thought arrives before you can stop it: they knew this would land on me. You are already half-composing the message, the one with the cold, careful politeness that means you are furious. Then you actually read the diff. They renamed a field three layers down, the kind of rename nobody traces by hand, and the break is honest. There was never a plan. There was a person moving fast who could not see your corner of the system from where they stood.

There is a rule for the gap between the explanation you reached for and the one that was true, and it is more useful than its blunt wording suggests. It is Hanlon's razor, and most write-ups give you the slogan and a traffic anecdote and stop. What is worth more is seeing what it actually decides (how to read the cause of a bad outcome, not whether someone is a good person), how it differs from the razors it gets shelved next to, why generated text and automated systems have made it a daily working tool rather than a cynic's comfort, and what it means for the terse, half-finished claims sitting in your own notes. Here is Hanlon's razor in full, with a comparison table, worked examples, and the version running quietly against your past self.

## What is Hanlon's razor?

Hanlon's razor is [an adage](https://en.wikipedia.org/wiki/Hanlon%27s_razor) stating that you should never attribute to malice that which is adequately explained by stupidity, or, in its less insulting and more usable forms, by incompetence, ignorance, haste, or a broken system. The specific phrasing was popularized by Robert J. Hanlon, who [submitted it to a 1980 collection of Murphy's Law jokes](https://www.britannica.com/topic/Hanlons-razor), though the thought is old: Goethe and others reached for versions of it long before it had a name. A razor, in philosophy, is a rule of thumb that lets you shave off an unpromising line of reasoning without chasing it down. This one shaves off the reflex to read hostile intent into outcomes that a plain mistake already covers.

The core of it is a rule about which explanation to reach for first. When something goes wrong in a way that affects you, two accounts are usually available: someone did it on purpose, or someone (or something) erred. Hanlon's razor says the error explanation is the better default, not because people are never malicious, but because mistakes, oversights, miscommunication, and bad incentives are vastly more common than coordinated ill will, and they cost far less to produce. The razor does not claim malice never happens. It says you should not assume it until the evidence for intent is actually there, and that treating "this hurt me" as proof of "this was aimed at me" is a predictable error in its own right.

## Why error is the better default

The razor looks naive until you count the two explanations honestly. Malice requires a lot: someone has to notice you, model how an action would affect you, decide to cause that effect, and then act on it, all while the ordinary friction of work gives them a hundred easier things to think about. Error requires almost nothing. A rename nobody traced, a Slack message read in the wrong tone, a config copied from a stale example, a deadline that squeezed out the double-check. The base rates are not close. In any system with more than a few people in it, the overwhelming majority of the outcomes that feel personal were produced by someone who was not thinking about you at all.

Assuming malice is also expensive in a way that compounds. It poisons the next interaction before it happens, it spends your attention on a conflict that does not exist, and it makes you worse at finding the real cause, because "they did this on purpose" closes the investigation while "something broke" keeps it open. Many of the outcomes that look like somebody's bad intent are better explained one level up, as [the product of a structure or an incentive rather than a villain](/blog/perverse-incentive): the system rewarded the behavior that hurt you, and the person was just standing where the system put them. Reaching for malice skips past all of that. It is the costliest explanation masquerading as the obvious one.

## Hanlon's razor versus the other razors

The razors get stacked in the same mental drawer and pulled out interchangeably, which is how people misuse all of them. Each shaves off a different unpromising move and answers a different question. The table sorts the ones that come up most, plus Grey's law, which is the honest limit on Hanlon's.

| Principle | One-line form | What it decides | Use it when |
|---|---|---|---|
| Hanlon's razor | Never attribute to malice what is adequately explained by error | How to read the cause of a bad outcome | An outcome looks hostile and you are about to assume intent |
| Occam's razor | Prefer the explanation with the fewest assumptions | Which of several explanations to favor first | You are choosing between competing accounts and want the simplest |
| Hitchens's razor | What is asserted without evidence can be dismissed without evidence | Who carries the burden of proof | A claim arrives with nothing behind it |
| Grey's law | Sufficiently advanced incompetence is indistinguishable from malice | When the error framing stops mattering | The harm repeats after it has been flagged, regardless of intent |

Hanlon's razor is really Occam's razor pointed at human behavior: malice is the explanation with more moving parts, so it needs more evidence before you prefer it. The row that keeps Hanlon honest is the last one. Grey's law notes that past a certain point the distinction between malice and incompetence stops paying rent. If a person or a team keeps producing the same harm after being told, the question of what is in their heart becomes academic; the outcome is the same and so is your response. Hanlon's razor is a default for the first occurrence, not a permanent excuse, and [a sharper, evidence-based cousin](/blog/hitchens-razor) governs the moment someone actually offers proof of intent: once evidence is on the table, you weigh it rather than wave it away.

![A bad outcome reaches one test, is there specific evidence of intent: no leads to explaining it by error, yes leads to weighing malice against that evidence.](/blog/hanlons-razor/explanation-order.svg)

## Hanlon's razor in the age of AI

Hanlon's razor earned its first fame in software. It spread through [the Jargon File](http://www.catb.org/jargon/html/H/Hanlons-Razor.html) in the 1990s as a reminder that weird bugs and server glitches are honest coding mistakes, not sabotage, and the reflex it corrects is the same one every on-call engineer knows: the outage looks deliberate because it is so perfectly timed, and it never is. The place the razor earns fresh keep now is one step past that, in how people read the output of AI systems.

When a model gives you a confidently wrong answer, invents a citation, or ignores an instruction you gave it clearly, the language that comes to mind is the language of intent. It lied to me. It is being lazy. It is hiding the real answer. That framing feels natural because the output arrives in fluent, human-sounding sentences, and we read intent into anything that talks. But there is no one in there to have an intent. A model has no plan for you, no agenda, no capacity for malice; it produced a wrong token sequence the same mechanical way it produces a right one. Attributing the error to deception is Hanlon's razor failed in a new setting, and it leads you to exactly the wrong response: arguing with the system, or distrusting it theatrically, instead of treating the failure as what it is.

Reframing the wrong answer as error rather than malice changes what you do next. You stop demanding the model confess and start building the guardrail: narrow the prompt, supply the missing context, and above all [check the claim against something real before you let it into your work](/blog/ai-fact-checking-for-notes), because a mistake you can catch is more useful to plan around than a betrayal you can only resent. It also keeps your trust calibrated correctly. A model that was confidently wrong once is not out to get you, but it has shown you something about its reliability on that kind of question, and the right lesson is [the measured distrust you would apply to any source you have caught being wrong](/blog/gell-mann-amnesia-effect), not a story about bad faith. Error is a property you can engineer around. Malice is a story that leaves you helpless.

## Examples: applying the razor

The razor is easy to nod along to and easy to abandon the moment something stings, so it helps to see it run against the outcomes that actually cross a working day. In each case the first move is the same: before you assume intent, ask whether a plain error already covers it.

| The outcome | The malice reading | What the razor says |
|---|---|---|
| A teammate's merge breaks your service | They knew this would land on me | A rename they could not trace to your code. Assume error, read the diff. |
| A reviewer leaves a terse, blunt comment | They are being hostile | Terse usually means busy, not cruel. Read it as haste before contempt. |
| An AI tool ignores an explicit instruction | It is being deliberately unhelpful | No intent exists to be unhelpful. Treat it as a limit, fix the prompt. |
| A vendor ships a change that breaks your integration | They are trying to lock us in | More likely nobody modeled your use case. Assume oversight, then confirm. |
| A colleague omits context you needed | They are withholding to look smart | Missing context is the default state of handoffs, not a power play. |
| The same bug ships for the third time after you flagged it | They do not care | Grey's law. Intent stops mattering; treat the pattern as the problem. |

The pattern across the rows is that the razor almost never asks you to decide someone is good. It asks you to spend the first explanation on error, because that is where the odds and the cheap fix both are. Five of the rows resolve to a mistake and a concrete next step. The last one is the exception that proves the edge: once the harm repeats after a warning, Hanlon's razor has done its job and hands off to the pattern, which you treat on its outcome regardless of what anyone intended.

## How to apply Hanlon's razor well

The razor is a reflex worth building, and a few habits do most of the work.

**Reach for the boring explanation first.** Before you draft the pointed message, list the ways this could have happened with nobody meaning it. There are almost always several, and one of them is usually right. The habit is not to deny that malice exists; it is to make error your first hypothesis and malice the one that has to earn its place, which is the reverse of what stress does to you.

**Let intent back in when evidence actually appears.** Hanlon's razor is a default, not a blindfold. If someone shows a clear pattern, a motive, and an action that fits only the hostile reading, the default has been overcome and you should act on what the evidence says. Using the razor honestly means applying it to the ambiguous first case and dropping it the moment real signs of intent are on the table.

**Separate "not malicious" from "not a problem."** A mistake can be as damaging as an attack, and reading it charitably does not mean ignoring it. The point of the error framing is to route you toward the fix (the broken process, the missing context, the unclear spec) instead of toward a fight. [Deciding which bad outcomes are even worth a full investigation](/blog/second-order-thinking) is its own call, made deliberately rather than by the heat of the moment.

**Point it at systems, not just people.** The most useful version of Hanlon's razor widens from "this person erred" to "this system let the error through." A bad outcome is often nobody's mistake in particular and [the predictable shape of how the work is organized](/blog/conways-law): the handoff with no owner, the deploy with no check, the incentive that rewarded speed over care. That reframe turns blame into a design problem you can actually solve.

## The version hiding in your own notes

The sharpest place to turn the razor is inward, on the notes your past self left you. You open a note from six months ago and it says, flatly, "don't use the batch endpoint." No reason, no context, no link. The reflex is a small, familiar irritation at past you: why would you write that and not say why, what were you thinking. That irritation is a tiny malice reading aimed backward in time, and it is wrong for exactly the reason the razor describes. Past you was not withholding. Past you was moving fast, the reason was obvious in the moment, and the context was the first thing to evaporate.

The fix is structural, not a matter of being kinder to yourself. A note that carries its own reason survives the gap; a bare instruction becomes a claim you have to re-litigate or nervously ignore every time you meet it again. This is the same failure that lets [a line that was once well-grounded harden into a stale rule you follow without knowing why](/blog/knowledge-decay), and it is the private version of the terse teammate: the information was never hostile, it was just incomplete, and the cost landed later. The same charity you extend to a colleague's blunt review, you owe your own records, and the way to pay it is to capture the reason with the instruction while the reason is still in front of you. A stale internal doc is the team-scale version of the same thing, which is why [an out-of-date page is better read as neglect than as a trap](/blog/outdated-documentation).

## When Hanlon's razor does not apply

The razor gets overextended, so the guard matters. It is narrow on purpose, and it has two failure modes at opposite ends.

The first is using it to excuse the inexcusable. Real malice exists; fraud, harassment, and deliberate sabotage are not hallucinations, and someone who keeps "accidentally" doing the same harmful thing is described by Grey's law, not protected by Hanlon's. The razor applies to the first ambiguous case, not to a pattern that has already announced itself. When evidence of intent is genuinely present, invoking the razor is no longer charity; it is looking away. The second failure is subtler: treating "not malicious" as "not serious." An error can do real damage, and reading it charitably is only the first step, the one that gets you to the actual cause instead of a grievance. Hanlon's razor is a tool for finding the problem faster, not a reason to let it stand. Point it at the ambiguous outcome in front of you, extend the error assumption exactly once, and let both the evidence and the pattern take it back from you when they have earned it.

## Getting started

Hanlon's razor is not a way to think the best of everyone. It is a way to stop spending your attention on conflicts that were never there, and to get to the real cause of a bad outcome faster than resentment ever will. The test is small and mechanical: when something goes wrong and feels personal, reach for the boring explanation first, hold the malice reading until the evidence for intent actually shows up, and when a harm repeats after a warning, stop asking what anyone intended and treat the pattern itself. It is most valuable exactly where intent is easiest to imagine and hardest to confirm, which today means the confidently wrong output of a system that has no intent at all.

Start with your own knowledge base, where the terse, context-free notes are quietly the ones you are hardest on. Capture each claim with its reason, a line on why you believed it and what it depends on, so a note does not come back months later as a bare instruction you resent or ignore. Read a confusing past note as a mistake to recover from, not a failure to judge. And treat a wrong AI answer as an error to engineer around rather than a betrayal to argue with. [Try Scribelet free](https://scribelet.app) and let it keep your notes with their reasons attached, and check them against the world, so the context you had today is still there the day the note is all you have left.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>hanlons-razor</category>
            <category>thinking</category>
            <category>mental-models</category>
            <category>ai</category>
            <category>software-engineering</category>
        </item>
        <item>
            <title><![CDATA[Obsidian vs Apple Notes: an honest 2026 comparison]]></title>
            <link>https://scribelet.app/blog/obsidian-vs-apple-notes</link>
            <guid isPermaLink="false">https://scribelet.app/blog/obsidian-vs-apple-notes</guid>
            <pubDate>Sat, 31 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Obsidian vs Apple Notes, round by round: capture, cross-platform reach, linking, AI, pricing, and lock-in. Plus the one thing neither tool measures. Read on.]]></description>
            <content:encoded><![CDATA[
The fastest way to start an argument among people who take notes is to ask whether Obsidian or Apple Notes is better. Both camps are right, because they are answering different questions. One person reaches for Apple Notes to jot a grocery list from the lock screen before the thought is gone. Another has spent two years building a linked vault in Obsidian that maps how every idea connects to every other. Neither is using the tool wrong. They are just not using it for the same thing.

That is the flaw in most Obsidian vs Apple Notes comparisons. They stack features in two columns as if the apps are racing to win the same event, when Apple Notes is trying to be the frictionless pocket notebook that is already on your phone and Obsidian is trying to be a knowledge system you own outright. Score them on feature count and you will pick the one that looks busier, not the one that fits how you actually work.

So here is a round-by-round comparison: who wins each dimension, where your notes actually live, how hard it is to move them, and the single thing neither app does. By the end you will know which one suits the way you think. And if the honest answer turns out to be "both," you will know how to run them together without the seam showing.

## Obsidian vs Apple Notes at a glance

Apple Notes is Apple's built-in notes app: instant capture, handwriting, scanning, and tight iCloud sync, best for anyone who lives inside the Apple ecosystem and wants zero setup. Obsidian is a local-first knowledge base built on plain Markdown files, with backlinks, a graph view, and community plugins, best for people building a long-term, portable thinking system. The honest split: Apple Notes for capture, Obsidian for connection and ownership.

| Dimension | Apple Notes | Obsidian | Winner |
|---|---|---|---|
| Core model | Frictionless native capture | Local Markdown knowledge system | Depends |
| Quick capture and handwriting | Instant, lock-screen, Apple Pencil, scanning | No native handwriting; capture needs the app open | Apple Notes |
| Cross-platform reach | Apple devices only (plus iCloud.com web) | macOS, Windows, Linux, iOS, Android | Obsidian |
| Linking and knowledge graph | Folders, tags, Smart Folders, no graph | Bi-directional links, backlinks, graph view | Obsidian |
| Customization and plugins | None (fixed, out of the box) | Large community plugin and theme ecosystem | Obsidian |
| Offline access | Full offline on every Apple device | Full offline; files live on disk | Tie (both strong) |
| Built-in AI | Apple Intelligence on recent hardware | None built in; plugins or bring your own | Depends |
| Where notes live | Proprietary store synced through iCloud | Plain `.md` files in a folder you control | Obsidian |
| File format and export | Apple's own format; export resists you | Markdown you already own; nothing to export | Obsidian |
| Pricing | Free with your Apple device | Free for personal use; optional paid add-ons | Depends |
| Keeping notes accurate over time | None (manual) | None (manual) | Neither |

Read the last row before any of the others. Every comparison online covers the rows above it. Almost none covers that one, and it is the row that decides whether your notes stay an asset or quietly become a liability. If you have ever opened a note you trusted and found it half wrong, our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why it happens to everyone, not just the disorganized.

Now the rounds.

## Round 1: Core model, capture vs knowledge system

This is the whole decision in one dimension, so it goes first.

Apple Notes behaves like the notebook that is always within reach. It is already on your iPhone, iPad, and Mac, signed in, synced, one tap from the lock screen. You open it and you are writing. The structure is deliberately light: folders, subfolders, tags, and Smart Folders that gather notes by rule. It is built so that capturing a thought costs you nothing.

Obsidian behaves like a workshop you build over time. Every note is a plain text file on your disk, and the power comes from connecting them: type `[[` and link one note to another, then watch the backlinks and the graph reveal structure you never planned. Obsidian rewards people who want their notes to compound, where today's note is wired into everything related you have ever written.

The mistake is reading this as better versus worse. It is capture versus connection. If your notes are fleeting, lists, reminders, a photo of a whiteboard, Apple Notes fits the moment. If your notes are a body of knowledge you return to and build on, Obsidian's links fit the long game. Most people lean one way the instant they stop counting features and ask what their notes are actually for.

**Winner: depends.** Fast capture goes to Apple Notes. A connected, lasting system goes to Obsidian.

![A two-axis map with Apple Notes in the effortless-capture and proprietary corner and Obsidian in the deep-knowledge-system and portable corner, the two apps sitting in opposite corners.](/blog/obsidian-vs-apple-notes/capture-vs-system.svg)

## Round 2: Quick capture and handwriting

Apple Notes wins this one cleanly, and it is not close.

Capture is where Apple Notes was born. Open it from the lock screen, the Control Center, or a tap on the back of the phone, and you are typing in under a second. On an iPad you write by hand with the Apple Pencil, convert that handwriting to text, scan a document straight into a note, and sketch a diagram inline. There is no decision to make before you can write, which matters far more than it sounds when you are trying to catch a thought before it evaporates.

Obsidian has no native handwriting, and capture always runs through the app. You open Obsidian, choose or create a note, and then write. On desktop that is quick. On mobile it is a few taps more than Apple Notes, and the gap is exactly the friction that decides whether a passing idea gets recorded at all. Obsidian is where you organize and connect what you captured, not usually where you capture it in the first place.

If you handwrite, sketch, or want the lowest-friction "just get it down" surface, Apple Notes wins before the other rounds begin.

**Winner: Apple Notes.**

## Round 3: Cross-platform reach

Here Obsidian takes the lead, and for a lot of people this single round ends the debate.

Apple Notes runs on Apple hardware and nowhere else. Mac, iPhone, iPad, and a stripped-down web view at iCloud.com. If every device you touch has an Apple logo, that is invisible. The moment a Windows laptop, an Android phone, or a Linux box enters your week, Apple Notes stops being an option on that device, and your notes are effectively trapped behind the ecosystem boundary.

Obsidian runs on macOS, Windows, Linux, iOS, and Android, reading the same Markdown files everywhere. Your vault is the same vault on every platform. For anyone who works across operating systems, or who refuses to let a notes app dictate which phone they buy next, that reach is decisive. We make the same case in our guide to picking a [cross-platform note-taking app](https://scribelet.app/blog/cross-platform-note-taking-app): the tool that follows you everywhere beats the one that is slightly nicer on a single device.

**Winner: Obsidian.**

## Round 4: Linking, backlinks, and the knowledge graph

This is Obsidian's home turf, and it is just as lopsided as Round 2 was the other way.

Obsidian is built around bi-directional links. Reference another note and both notes now know about each other, so you can follow a thread of thinking in either direction. The graph view turns your vault into a map of how ideas connect, and plugins extend that into dashboards, spaced repetition, canvas boards, and more. For a research library, a zettelkasten, or any body of knowledge where the connections are the point, nothing in Apple Notes comes close.

Apple Notes organizes with folders, tags, and Smart Folders, and links one note to another manually, but it has no backlinks and no graph. You can find a note. You cannot see the web it sits in. For simple structure that is fine. For thinking that grows by connection, it is a ceiling you hit early.

**Winner: Obsidian.**

## Round 5: AI features

Both have an AI story now, and the split follows the same ecosystem lines as everything else.

Apple Notes leans on Apple Intelligence, which can summarize a note, rewrite a passage, and clean up handwriting, with much of it running on device for privacy ([Apple Intelligence](https://www.apple.com/apple-intelligence/)). The catch is hardware: the features only appear on recent iPhones, iPads, and Macs, so an older device gets none of it. Obsidian ships no built-in AI at all. Instead you add it through community plugins, which means you choose the model and, often, bring your own API key.

The honest caveat for both is the same, and it is the one the marketing skips. AI that writes into your notes raises a question neither app answers: is what it wrote still true next month? An assistant that confidently restates an outdated fact is worse than no assistant. That is why we treat [AI fact-checking for notes](https://scribelet.app/blog/ai-fact-checking-for-notes) as a discipline separate from generation, and why the control you have over the model matters as much as the model itself.

**Winner: depends.** Apple Intelligence if you own recent Apple hardware and want zero setup. Obsidian plus a plugin if you want to pick the model and keep control.

## Round 6: Pricing

Apple Notes is free. It comes with the device, and the only cost is iCloud storage if your notes and attachments outgrow the free tier, which text notes rarely do on their own.

Obsidian is free for personal use, and stays free for the core app no matter how large your vault grows. The optional costs are add-ons: Sync for official end-to-end encrypted sync across devices, and Publish for putting notes on the web. Neither is required. You can sync a vault yourself through any file-sync service and never pay Obsidian a cent ([Obsidian pricing](https://obsidian.md/pricing)).

For a solo user, both can cost nothing. The real price difference is not dollars. It is what you are tied to: Apple Notes is free as long as you stay on Apple hardware, while Obsidian is free and goes wherever you do.

**Winner: depends on what you already own.**

## Round 7: Migration, and the lock-in nobody mentions

This is the round that should change how you read all the others.

Getting out of Apple Notes is genuinely hard. Notes live in Apple's proprietary store, and exporting them cleanly, with attachments, formatting, and handwriting intact, resists you at every step. There is no "export my vault as files" button, because in Apple's model there is no vault, only the app. Obsidian, by contrast, is already just a folder of Markdown files. There is nothing to export, because nothing was ever locked in. Obsidian even ships an official importer to pull your Apple Notes across into durable Markdown ([Obsidian Apple Notes Importer](https://obsidian.md/help/import/apple-notes)), which tells you which direction the escape hatch points.

Step back and the pattern is clear. Apple Notes locks your notes inside an app tied to one company's hardware. Obsidian hands you plain text files you own forever, readable by any editor, today and in ten years. This is the core of Obsidian's "file over app" philosophy, and it is the strongest reason people switch. If owning your notes in a portable format is what you care about most, the comparison is already over, and the same logic drives people toward plain [Markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) or a dedicated [Obsidian alternative](https://scribelet.app/blog/obsidian-alternative) when Obsidian itself asks for more tinkering than they want.

But owning the files only solves half the problem. Plain Markdown in a folder is portable and yours, and it is also completely on its own: nothing syncs it securely across devices unless you wire that up, and nothing checks whether what you wrote is still accurate. That open gap is where the real question lives.

**Winner: Obsidian.** It traps nothing. The catch is that ownership is the floor, not the finish line.

## The dimension neither tool measures

Every round above is about where your notes live and how you edit them. None of it touches whether your notes are still *true*.

A note is a snapshot of what you understood on the day you wrote it. The API you documented ships a breaking change. The price you noted goes up. The link you saved rots. Neither Apple Notes nor Obsidian has any idea this is happening. They store what you wrote and hand it back a year later with the same confidence, long after half of it stopped being accurate. This is the uncomfortable truth we build Scribelet on: knowledge has a half-life, and most tools pretend it does not.

That is the row both apps score zero on, and it is the one we care about most. Scribelet runs background checks that compare your notes against current sources and show you a diff when something has changed, so the notes you rely on stay trustworthy instead of quietly going stale. You bring your own API key, we encrypt it at rest, and you see exactly what changed and why, your keys and your models, not ours. If you keep sensitive notes, a [secure note-taking app](https://scribelet.app/blog/secure-note-taking-app) that encrypts your content and never trains on it matters more than any feature checklist. Try it free.

## So which should you choose?

Strip away the feature lists and it comes down to how you think and where you work.

- **Choose Apple Notes** if you live entirely on Apple devices, you capture fast and loose, you handwrite or scan, and you want a notes app that needs zero setup and is already in your pocket.
- **Choose Obsidian** if you want a connected, lasting knowledge system you own outright: backlinks, a graph, plugins, plain-text files, and the freedom to work on any operating system.
- **Run both** if your honest answer is that you capture everywhere and think deeply in one place. Many people use Apple Notes as the inbox and move the keepers into Obsidian, which the top of this field quietly agrees is the sanest setup.
- **Reach past both** if what you care about most is keeping your notes accurate over time. That is the gap each of them leaves wide open.

If you are still weighing the wider field, our [Notion vs Obsidian](https://scribelet.app/blog/notion-vs-obsidian) and [Obsidian vs OneNote](https://scribelet.app/blog/obsidian-vs-onenote) comparisons cover the two apps most people consider next. The best note-taking tool is not the one with the most features, or even the one you own most completely. It is the one whose notes you will still trust after everything in them has had a year to change.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>obsidian-vs-apple-notes</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>obsidian</category>
            <category>apple-notes</category>
            <category>personal-knowledge-management</category>
        </item>
        <item>
            <title><![CDATA[Notion vs OneNote: an honest 2026 comparison]]></title>
            <link>https://scribelet.app/blog/notion-vs-onenote</link>
            <guid isPermaLink="false">https://scribelet.app/blog/notion-vs-onenote</guid>
            <pubDate>Thu, 29 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Notion vs OneNote, compared round by round: structure, handwriting, offline, AI, pricing, and migration. Plus the one thing neither tool measures. Read on.]]></description>
            <content:encoded><![CDATA[
Ask whether Notion or OneNote is better and you will get two confident answers that both sound right, because the people giving them are using the tools for different jobs. One person swears by OneNote for the freeform page where they sketch, clip, and scrawl. Another swears by Notion for the database that runs their whole team. Neither is wrong. They are just not comparing the same thing.

That is the trap in most Notion vs OneNote comparisons. They line up features side by side as if the two apps are competing to win the same race, when OneNote is trying to be an infinite sheet of paper and Notion is trying to be a lightweight database with a word processor bolted on. Pick by feature count and you will end up with the tool that does more on paper and less for how you actually work.

So this is a round-by-round comparison of Notion and OneNote: who wins each dimension, what each one costs, how hard it is to move your notes between them, and the single thing neither of them does. By the end you will know which one fits the way you think, not just which one has a longer feature list.

## Notion vs OneNote at a glance

OneNote is a freeform digital notebook from Microsoft, best for handwriting, infinite-canvas layouts, quick capture, and anyone already living in Microsoft 365. Notion is a block-based workspace built around relational databases, wikis, and project management, best for structured knowledge and teams. The honest split: OneNote for capture and ink, Notion for structure and systems.

| Dimension | OneNote | Notion | Winner |
|---|---|---|---|
| Core model | Freeform canvas, type or draw anywhere | Block-based pages and databases | Depends |
| Structure and databases | Basic tables and tags | Relational databases with Kanban, calendar, gallery views | Notion |
| Handwriting and stylus | Native ink, palm rejection, ink-to-text | No native handwriting | OneNote |
| Quick capture | Click and type anywhere instantly | Slower; pick a page or database first | OneNote |
| Offline access | Full offline on desktop and mobile | Limited; heavy editing wants a connection | OneNote |
| Collaboration and wikis | Shared notebooks, real-time co-editing | Team wikis, permissions, comments, databases | Notion |
| Templates and extensibility | Small add-in gallery | Huge template ecosystem and an API | Notion |
| Built-in AI | Microsoft Copilot in paid plans | Notion AI with workspace Q&A | Depends |
| Where notes live | Proprietary files synced in OneDrive | Notion's servers, blocks in a database | Tie (both closed) |
| File format and export | Microsoft's own format; export resists | Markdown and HTML export, but structure breaks | Tie (both lossy) |
| Pricing | Free; storage via Microsoft 365 | Free personal tier; paid team plans | Depends |
| Keeping notes accurate over time | None (manual) | None (manual) | Neither |

Look at the last row before anything else. Every comparison covers the ones above it. Almost none covers that one, and it is the row that decides whether your notes stay an asset or quietly turn into a liability. If you have watched your own notes drift out of date without noticing, our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why it happens to everyone, not just disorganized people.

Now the rounds.

## Round 1: Core model, canvas vs database

This is the whole decision in one dimension, so it goes first.

OneNote gives you a page that behaves like paper. Click anywhere and start typing. Drag a text box, drop in a screenshot, draw a diagram with your finger, record audio in the margin. Nothing has to line up. The structure is loose on purpose: notebooks hold sections, sections hold pages, and inside a page you do whatever you want.

Notion gives you a page made of blocks, and the real power is that any page can become a database. A table of projects where each row opens into its own full page. A board that shows the same data as Kanban. A calendar view of the same rows again. Notion rewards people who think in systems and want their notes to behave like structured, queryable data.

The mistake is treating this as better versus worse. It is capture versus organization. If your notes are messy by nature, meeting scrawls, half-ideas, clipped research, OneNote's canvas fits. If your notes are records you will filter, sort, and relate, Notion's databases fit. Most people lean clearly one way once they stop comparing feature lists and ask what their notes actually are.

**Winner: depends.** Freeform thinking goes to OneNote. Structured systems go to Notion.

![A two-axis map placing OneNote in the freeform and proprietary corner, Notion in the structured and proprietary corner, and plain Markdown in the empty portable corner.](/blog/notion-vs-onenote/canvas-vs-database.svg)

## Round 2: Handwriting and quick capture

OneNote wins this one cleanly, and it is not close.

OneNote was built for ink. On a Surface, an iPad, or any touchscreen, you write by hand with palm rejection, convert handwriting to text, and draw diagrams inline. Capture is instant: open any page, click, type. There is no decision to make before you can write, which matters more than it sounds when you are trying to catch a thought before it evaporates.

Notion has no native handwriting at all. To capture a quick note you first choose where it goes, which page or which database, and that small friction is the opposite of how capture should feel. Notion is a place you organize things you already captured, not the place you capture them.

If you take handwritten notes, or you want the lowest-friction "just write it down" surface, OneNote wins before the other rounds even start. Notion is simply not where fast capture happens.

**Winner: OneNote.**

## Round 3: Offline and speed

OneNote works offline by design. Your notebooks live on your device and sync to OneDrive when you reconnect, so a flaky connection does not stop you from writing. Microsoft documents full offline access as a core feature of the app ([Microsoft 365 OneNote](https://www.microsoft.com/en-us/microsoft-365/onenote/digital-note-taking-app)).

Notion is cloud-first. It has an offline mode, but a limited one: pages you have not opened recently may not be available, and heavy editing expects a connection. For a tool people use as their operating system for work, that is a real constraint, not a footnote.

**Winner: OneNote.**

## Round 4: Structure, databases, and collaboration

Here Notion takes back the lead, and it is just as lopsided as Round 2.

Notion's relational databases are genuinely powerful. One source of truth, many views, rows that relate to other rows, filters and rollups that turn notes into something closer to a lightweight app. For a team wiki, a content calendar, a CRM, or a project tracker, nothing in OneNote comes close. Notion also handles permissions, comments, and real-time collaboration in a way that suits teams building shared knowledge.

OneNote collaborates too, through shared notebooks and Microsoft 365 co-editing, and for a family or a small group passing notes around it is fine. But it has no concept of a relational database. Tables are tables. If your notes want to behave like data, OneNote cannot get you there.

**Winner: Notion.**

## Round 5: AI features

Both ship AI now, and the split follows the ecosystems.

OneNote's AI is Microsoft Copilot, which summarizes, drafts, and answers questions across your notes, but it requires a Copilot or Microsoft 365 license on top of the free app. Notion AI is built into the workspace and does the headline trick well: ask a question and it answers across your pages, which is useful precisely because Notion holds structured data it can reason over.

The honest caveat for both: AI that writes into your notes raises a question neither tool answers, which is whether what it wrote is still true next month. An assistant that confidently restates an outdated fact is worse than no assistant. That is why we treat [AI fact-checking for notes](https://scribelet.app/blog/ai-fact-checking-for-notes) as a separate discipline from generation, and why the control you have over the model matters as much as the model itself.

**Winner: depends.** Copilot if you are in Microsoft 365, Notion AI if your notes are already structured.

## Round 6: Pricing

OneNote is free. The app costs nothing, and you only pay if you want more OneDrive storage or the Microsoft 365 bundle, which many people already have for Office. Copilot is the one real add-on cost.

Notion has a free personal tier that is generous for a single user, with paid plans for teams that add members, advanced permissions, and more automation ([Notion pricing](https://www.notion.com/pricing)). Notion AI is typically an add-on on top of that.

For a solo user, both can be free. For a team, OneNote leans on a Microsoft 365 subscription you may already pay for, while Notion is priced per member as a standalone product. Which is cheaper depends entirely on what you already own.

**Winner: depends on your existing stack.**

## Round 7: Migration, and the lock-in nobody mentions

This is the round that should change how you read all the others.

Moving between these two tools is painful in both directions. OneNote stores notes in Microsoft's proprietary format, and getting them out cleanly, with your ink, layout, and attachments intact, resists you. Notion exports to Markdown and HTML, which sounds better, but its structure does not survive the trip: databases flatten, relations break, and nested pages scatter into folders. One blogger's widely-cited account of switching described Notion's import of a decade of OneNote notes as poor enough to send them back ([The Productive Indie Fiction Writer](https://productiveindiefictionwriter.com/i-used-notion-for-a-week-8-reasons-i-switched-back-to-onenote/)).

Step back and the real pattern is clear. Both tools are closed ecosystems. OneNote locks your notes in a proprietary file in Microsoft's cloud. Notion locks them in blocks on Notion's servers. In both cases the app is the door, and the door only opens so far. You can switch tools, but you cannot easily take your notes with you in a form the next tool fully understands.

This is where a third model exists that neither comparison usually mentions: plain [Markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) keep your notes as portable text files you own outright, readable by any editor, today and in ten years. If what you actually want is to not be locked in, the Notion vs OneNote question has a third answer. The same logic drives people toward a [Notion alternative](https://scribelet.app/blog/notion-alternative) or a [OneNote alternative](https://scribelet.app/blog/onenote-alternative) once lock-in becomes the deciding factor.

**Winner: neither.** Both trap your notes; the escape is a format you own.

## The dimension neither tool measures

Every round above is about where your notes live and how you edit them. None of it touches whether your notes are still *true*.

A note is a snapshot of what you understood on the day you wrote it. The API you documented changes. The pricing you noted goes up. The link you saved rots. Neither Notion nor OneNote has any idea this is happening. They store what you wrote and show it back to you with the same confidence a year later, long after half of it stopped being accurate. This is the brand we build on: knowledge has a half-life, and most tools pretend it does not.

That is the row we care about most, and it is the one both tools score zero on. Scribelet runs background checks that compare your notes against current sources and show you a diff when something has changed, so the notes you trust stay trustworthy instead of quietly going stale. You bring your own API key, we encrypt it at rest, and you see exactly what changed and why. If you keep sensitive notes, a [secure note-taking app](https://scribelet.app/blog/secure-note-taking-app) that never reads your content matters more than a feature checklist. Try it free.

## So which should you choose?

Strip away the feature lists and it comes down to how you think.

- **Choose OneNote** if you handwrite, sketch, or capture fast and loose; if you need full offline access; or if you already live in Microsoft 365 and want notes that fit beside Word and Outlook.
- **Choose Notion** if your notes want to behave like data: databases, wikis, project trackers, team knowledge bases with real structure and permissions.
- **Choose neither, and reach for a Markdown-first tool,** if the thing you care about most is owning your notes in a portable format and keeping them accurate over time. That is the gap both of these leave open.

If you are still weighing the wider field, our [Notion vs Obsidian](https://scribelet.app/blog/notion-vs-obsidian) and [Obsidian vs OneNote](https://scribelet.app/blog/obsidian-vs-onenote) comparisons cover the two apps most people consider next. The best note-taking tool is not the one with the most features. It is the one whose notes you will still trust after everything in them has had a chance to change.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>notion-vs-onenote</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>notion</category>
            <category>onenote</category>
            <category>personal-knowledge-management</category>
        </item>
        <item>
            <title><![CDATA[What a Decision Log Is, and a Template That Lasts]]></title>
            <link>https://scribelet.app/blog/decision-log</link>
            <guid isPermaLink="false">https://scribelet.app/blog/decision-log</guid>
            <pubDate>Wed, 28 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A decision log records what you chose and why so the reasoning survives. Copy the markdown template and see when to use one over an ADR. Try it free.]]></description>
            <content:encoded><![CDATA[
A new engineer wants to delete the retry setting. It is weird, it is undocumented, and it looks like someone pasted it in during an incident and never cleaned it up. You have a feeling there was a reason, so you go looking. The pull request that added it is closed and says "fix flaky job." The Slack thread where it was argued out scrolled into the archive months ago. The calendar event for the meeting has no notes. The setting is still running in production, still doing its job, and the reasoning behind it has completely evaporated.

That is the gap a decision log fills. Not the choice itself, which the code already records, but the "why" around it: what forced the call, what else you considered, and what you were betting would stay true. The pull request captures what changed. The decision log captures why anyone agreed to it, which is the part that goes missing exactly when someone needs it to decide whether the decision still holds.

## What is a decision log?

A decision log is a single, append-only record of the meaningful choices a team or a project makes, each entry capturing the decision, the context that forced it, the options considered, and the reasoning behind the one that won. It is a running list, not a per-file document: one place you can scroll back through to see what was decided, when, by whom, and on what assumptions. The point is to make the reasoning available to people who were not in the room, including your future self, after the memory of the discussion is gone.

It earns its keep in the moment the retry setting earns a second look. Without the log, a decision that is questioned later has to be reconstructed from memory or reopened from scratch, and both are expensive. With it, the answer to "why is this here?" is one entry away, and the follow-up question, "does that reason still apply?", becomes answerable instead of a shrug.

## What belongs in a decision log entry

Most of the value in a decision log is in two fields people are tempted to skip: the options you rejected, and the assumptions the choice depends on. The decision and the date are easy and nearly useless on their own. A bare "we chose Postgres, 2026-10-14" tells a future reader nothing about whether to trust it. The rejected options tell them what was already weighed so they do not re-litigate it, and the assumptions tell them the exact conditions under which the decision stops being correct.

A workable entry has six fields:

- **Decision**: the choice, in one sentence.
- **Date and owner**: when it was made, and who made or approved it.
- **Context**: what forced the choice now, not the whole backstory.
- **Options considered**: including the ones you rejected, and the reason each lost.
- **Assumptions**: the facts this decision depends on being true.
- **Status**: active, or superseded by a later entry (with a link to it).

That last field is what turns a list of decisions into a log you can trust. A decision is a bet on its assumptions, and bets get called. When a later choice reverses an earlier one, you do not delete the old entry; you mark it superseded and point at the entry that replaced it, so the history of "why we changed our mind" stays legible. This is the same supersession discipline that a well-maintained architecture decision record uses, borrowed down to a lighter weight.

## A decision log template you can copy

You do not need a spreadsheet or a tool for this. A decision log is text, and the most durable form is a markdown table or a list of short entries kept wherever your team already writes. The ranking template results for this term are Excel and Word galleries, which is fine for a project manager tracking approvals, but a log that lives in a `.xlsx` on someone's drive is a log nobody reads. Keep it in plain text, next to the work.

Here is a table form for a project or a team:

```markdown
| Date | Decision | Context | Options (rejected -> why) | Assumptions | Owner | Status |
|------|----------|---------|---------------------------|-------------|-------|--------|
| 2026-10-14 | Use Postgres for the billing service | Needed a store before launch; team knows relational | DynamoDB (nobody has run it in prod); SQLite (no concurrent writes) | Write volume stays under ~500/s this year | A. Okafor | Active |
```

And here is a longer per-entry form when a single table cell is too cramped for the reasoning:

```markdown
2026-10-14 | Use Postgres for the billing service

- **Context**: We need a datastore before the launch date, and the team
  already runs Postgres for two other services.
- **Options**: DynamoDB (rejected: no one here has operated it in
  production, and billing is a bad place to learn); SQLite (rejected:
  concurrent writes from the workers).
- **Assumptions**: write volume stays under ~500/s this year; we stay on
  a single region.
- **Owner**: A. Okafor. **Status**: Active.
```

Pick one shape and keep every entry in it. Consistency is what lets you scan the log in a year without re-reading each entry in full, and it is the thing a spreadsheet template quietly gives up the moment two people fill it in differently.

## A worked example: one decision, then superseding it

Say the Postgres entry above is a year old now. The service grew, write volume blew past the assumption, and the team has moved the hot path to a queue with a separate store. The wrong move is to edit the old entry to say "we use a queue now," because that erases the fact that the original call was reasonable on the information it had. The right move is a new entry that supersedes it:

```markdown
2027-02-02 | Move billing writes to a Kafka + Postgres split

- **Context**: Write volume hit ~2,000/s, past the 500/s the 2026-10-14
  decision assumed. Latency on the synchronous path became the incident.
- **Options**: Shard Postgres (rejected: operational load for a team of
  three); managed DynamoDB (reconsidered and chosen this time, for the
  write path only).
- **Assumptions**: read-heavy reporting stays on Postgres.
- **Owner**: A. Okafor. **Status**: Active.
- **Supersedes**: 2026-10-14 (Use Postgres for the billing service).
```

Then you go back to the October entry and change its status to `Superseded by 2027-02-02`, and nothing else. Read top to bottom, the log now tells a true story: a sound decision, the assumption that expired, and the decision that replaced it. That narrative is worth more than either entry alone, because it is how a team learns that its real failure was not the database choice but [not writing down the assumption so anyone would notice when it broke](/blog/second-order-thinking).

## Decision log vs ADR vs decision framework

Three practices sit near each other and get confused, and reaching for the wrong one is why teams either over-document small calls or under-document big ones. A decision log is the running list. An [architecture decision record is the formal, per-decision document](/blog/architecture-decision-record-examples) for architecturally significant choices, kept in the repository next to the code and never edited after acceptance. A [decision-making framework is the process you run to reach the choice](/blog/decision-making-framework) in the first place, before there is anything to log.

| | Decision log | Architecture decision record (ADR) | Decision-making framework |
|---|---|---|---|
| What it is | A running list of decisions and their reasoning | One formal document per architectural decision | A process for making the choice (RAPID, WRAP, a decision matrix) |
| Scope | Any team or project decision | Architecturally significant choices only | The decision you are making right now |
| Lives | A wiki page, a notes doc, a `DECISIONS.md` | `docs/adr/` in the repo, one file per ADR | In the meeting or the moment of choosing |
| When to reach for it | You want one place to see every decision | A structural choice future engineers must not quietly undo | You are stuck on how to decide, not on recording it |
| Granularity | One row or short entry each | A page each, with consequences and alternatives | Not a record at all |

The clean rule: use a framework to *make* the call, write it to the decision log so the reasoning survives, and promote the heavyweight structural ones into ADRs. The Microsoft engineering playbook keeps exactly this split, treating [the decision log as the lightweight design-review artifact](https://microsoft.github.io/code-with-engineering-playbook/design/design-reviews/decision-log/) and ADRs as the formal ones. Most teams need the log far more often than the ADR, because most decisions that get questioned later were never "architectural" enough for anyone to feel they warranted a document.

## Where to keep a decision log so it survives

![A line chart contrasting how recoverable a decision's reasoning is over time: without a decision log the recoverable reasoning decays toward zero within a year as memory fades and people turn over, while with a decision log it stays high](/blog/decision-log/rationale-recoverability.svg)

A decision log is only as good as your odds of finding it when you need it, and those odds are decided by where it lives. Three options, in rough order of how well they hold up:

A `DECISIONS.md` in the repository is the strongest for engineering decisions, for the same reason [an ADR works kept next to the code](/blog/internal-documentation): it is version-controlled, it travels with the project, and it shows up in the diff when someone touches the thing the decision was about. A team wiki page works for cross-functional calls that are not tied to one codebase, as long as someone owns keeping it from sprawling. A log in your notes app is often where it actually happens, because the reasoning gets captured at the moment of the decision instead of reconstructed at review time, and [a running work log you already keep](/blog/ai-work-log) is a lower-friction home than a file you have to remember to open.

The deeper benefit of a plain-text log, wherever it lives, is that it stays readable by the tools you will use to search it later. A decision logged as text is something an AI assistant can read back when you ask "why did we choose Postgres for billing?", and answer with the actual entry and its assumptions, instead of you scrolling an archive. A decision trapped in a spreadsheet cell or a closed ticket is not. The whole value of the log is retrieval, and plain text keeps it retrievable.

## Why decision logs rot, and how to keep one honest

The failure mode of a decision log is not that people stop writing it. It is that the entries keep standing after their assumptions have moved, and a written decision that has quietly gone stale is more dangerous than one you never recorded, because [a confident, outdated record gets trusted](/blog/outdated-documentation). People cite it, build on it, and defend it long after the reasoning underneath stopped being true. This is [the half-life that sits under every written artifact](/blog/knowledge-decay): nobody edits a decision to make it wrong, it goes wrong by standing still while the world moves.

The fix is built into the fields above. The `Assumptions` field names the conditions that have to hold, and the `Status` field is where their expiry gets recorded. A log kept this way is not just a record of what you decided; it is a list of bets with their terms attached, which is the only form of decision record that can tell you when to re-check it. The habit that makes it pay off is a periodic read, the [decision journal Shane Parrish popularized](https://fs.blog/decision-journal/), where you go back over old entries against what actually happened and grade your own calls. That review is also the cheapest insurance against a [bus factor of one](/blog/bus-factor): when the person who made a decision leaves, the log is the difference between the reasoning walking out the door and staying on the page.

This is the problem Scribelet is built around. A decision log should not be a file you trust and forget; it should be a set of notes that reads its own assumptions and tells you which of your team's decisions have quietly gone out of date since anyone last looked, and answers "why did we decide this?" when you ask. You can [try it free](https://scribelet.app) and keep the reasoning behind your decisions somewhere it gets re-checked instead of merely believed.

Start the log before you need it. The entry you will wish you had is the one for the weird retry setting, written on the day it stopped being obvious and kept somewhere the next engineer can find it before they reach for the delete key.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>decision-log</category>
            <category>engineering-docs</category>
            <category>documentation</category>
            <category>decision-making</category>
            <category>teams</category>
            <category>knowledge-management</category>
        </item>
        <item>
            <title><![CDATA[Obsidian vs OneNote: an honest 2026 comparison]]></title>
            <link>https://scribelet.app/blog/obsidian-vs-onenote</link>
            <guid isPermaLink="false">https://scribelet.app/blog/obsidian-vs-onenote</guid>
            <pubDate>Tue, 27 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Obsidian vs OneNote, compared round by round: storage, handwriting, canvas, AI, pricing, and the messy migration. Plus the one thing both ignore. Read on.]]></description>
            <content:encoded><![CDATA[
You have years of OneNote notebooks: clipped articles, handwritten margins, a half-drawn diagram from a meeting you can still picture. Then Microsoft retires the app you were using, nudges you to a different OneNote, and someone on Reddit tells you to "just switch to Obsidian." You download it, open a blank vault, and nothing looks like your notebooks at all.

That is the real Obsidian vs OneNote decision, and most comparisons skip straight past it. They hand you a tidy rule: Obsidian for plain-text ownership, OneNote for freeform canvas and Microsoft. The rule is mostly right, and this guide gets to why, dimension by dimension, with a winner called on each.

But the rule answers the wrong question. It tells you which app fits the way you take notes today. It says nothing about which notes you will still trust a year from now, after the API you documented has changed and the source you pasted has moved.

So this is a round-by-round comparison of Obsidian and OneNote: who wins each dimension, what each one actually costs, how painful it is to move your notes across, and the single thing neither of them does.

## Obsidian vs OneNote at a glance

OneNote is a freeform digital notebook from Microsoft, best for handwriting, infinite-canvas layouts, and anyone already living in Microsoft 365. Obsidian is a local-first Markdown editor, best for private, fast, deeply linked plain-text notes you own outright. The honest split: OneNote for canvas and ink, Obsidian for ownership and linked thinking.

| Dimension | OneNote | Obsidian | Winner |
|---|---|---|---|
| Where notes live | Proprietary files synced in OneDrive | Local Markdown files on your device | Obsidian |
| File format | Microsoft's own `.one` format | Plain Markdown, yours by default | Obsidian |
| Speed and offline | Syncs through the cloud; large notebooks lag | Instant, offline-first | Obsidian |
| Handwriting and stylus | Built for ink, palm rejection, drawing | No native ink; sketch plugins only | OneNote |
| Freeform canvas | Click anywhere, type or draw anywhere | Structured text, not a blank canvas | OneNote |
| Linking and graph | Basic page links | Wikilinks plus an interactive graph | Obsidian |
| Collaboration | Real-time co-editing via Microsoft 365 | Paid sync or third-party services | OneNote |
| Built-in AI | Microsoft Copilot in paid plans | None native; community plugins | Depends |
| Mobile and cross-platform | iOS, Android, web, Windows; weaker on Mac | Desktop and mobile as separate apps | Split |
| Plugins and extensibility | A small add-in gallery | 2,700+ community plugins | Obsidian |
| Pricing | Free; storage needs Microsoft 365 | Free for personal use; paid add-ons | Depends |
| Keeping notes accurate over time | None (manual) | None (manual) | Neither |

Notice the last row. Every comparison covers the others. Almost none covers that one, and it is the row that decides whether your notes stay an asset or quietly turn into a liability. If you have watched your own notes drift out of date without noticing, our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why it happens to everyone, not just disorganized people.

## The real difference: a freeform canvas vs a folder of files

Most feature-by-feature debates miss the design choice underneath everything else, and it is the choice that decides every round below.

OneNote's source of truth is a Microsoft-managed notebook stored in OneDrive and saved in its own `.one` format. The app is the door to that notebook, and for most purposes it is the only door. That is what makes OneNote's infinite canvas, inked pages, and real-time sharing possible, and it is also why pulling a decade of notebooks back out as clean, portable text is harder than it should be.

Obsidian's source of truth is a folder of plain Markdown files on your own machine. The [app sits on top of that folder](https://help.obsidian.md/Getting+started/Create+a+vault) and gives you ways to link, search, and visualize the files. A note can be read outside the app, backed up like any other folder, and opened in twenty years by anything that reads text.

Everything downstream follows from this. OneNote trades portability for a rich canvas and Microsoft's ecosystem. Obsidian trades that canvas for control and longevity. Neither choice is wrong; they are built for different fears.

![Side-by-side diagram contrasting OneNote's proprietary notebook reached only through its app with Obsidian's local Markdown folder the app sits on top of](/blog/obsidian-vs-onenote/canvas-vs-folder.svg)

## Round by round: who wins each dimension

The at-a-glance table calls the winners. Here is the reasoning behind each one, so you can weight the rounds that matter to you and ignore the ones that do not.

### Storage and ownership: Obsidian

Obsidian notes are plain text on your disk. They open without the app, survive the vendor changing direction, and back up like any other folder. OneNote keeps everything in a proprietary format inside OneDrive, reachable through the interface. For anyone whose fear is lock-in or longevity, this round is not close.

### Speed and offline: Obsidian

Obsidian opens instantly, searches without lag, and works on a plane. OneNote leans on cloud sync and gets visibly slower as notebooks grow large or fill with images and ink. If you capture fast and often, the difference shows up every day.

### Handwriting and stylus: OneNote

This is OneNote's home turf. It was built from the ground up for digital ink, palm rejection, and drawing straight onto the page with a stylus. Obsidian has no native handwriting; you can bolt on sketch plugins, but ink is not what a plain-text editor is for. If a tablet and pen are central to how you think, OneNote wins outright.

### Freeform canvas and layout: OneNote

OneNote lets you click anywhere on an infinite page and start typing, drawing, or pasting. Boxes of text float where you drop them, next to screenshots and hand-drawn arrows. Obsidian is structured text in a document, not a blank canvas. For visual, spatial note-takers, OneNote's freedom is the whole appeal.

### Linking and organization: Obsidian

Obsidian links files with wikilinks and renders an interactive graph of how your notes connect. OneNote offers basic links between pages and sections, but nothing like a backlink panel or a visual graph. If you think in connected notes rather than in a binder of pages, Obsidian is the clear winner.

### Collaboration: OneNote

Real-time co-editing is built into OneNote through Microsoft 365, not bolted on. A team can share a notebook, edit the same page at once, and tie it into Teams and Outlook. Obsidian is a solo tool unless you pay for sync and add third-party services, and even then it is not built for concurrent editing.

### Built-in AI: depends

OneNote reaches [Microsoft Copilot](https://www.microsoft.com/en-us/microsoft-365/onenote/digital-note-taking-app) inside its paid plans, a capable assistant for drafting and summarizing. It is reactive by design: you prompt it, it answers. Obsidian ships no native AI, but its plugins and external agents let you wire up almost anything, including local models. If you want AI that works the moment you log in, OneNote wins; if you want to choose your own model and route, Obsidian's openness wins. The wider set of [AI options for Obsidian](https://scribelet.app/blog/obsidian-ai) is worth a look before you decide this round.

### Mobile and cross-platform: split

OneNote runs on iOS, Android, web, and Windows with free sync, but its Mac app has historically trailed the Windows version on features. Obsidian has solid apps on every platform, yet syncing them means the paid Obsidian Sync add-on or a DIY setup. Neither is seamless everywhere, so if running your notes across a phone, tablet, and laptop is the real requirement, it is worth weighing both against [a note app that works the same on every device](https://scribelet.app/blog/cross-platform-note-taking-app) without a sync surcharge or a platform gap.

### Plugins and extensibility: Obsidian

Obsidian's community catalog runs past 2,700 plugins, from kanban boards to spaced repetition, so the app can become almost anything. OneNote has a far smaller add-in gallery and a more closed model. Obsidian is one of several apps built on that plain-text, extensible idea; we weigh the wider field in our guide to [markdown note apps compared](https://scribelet.app/blog/markdown-note-taking-apps).

### Learning curve: split

OneNote is easier to start. It looks like a binder, you click and type, and you are productive in minutes. Obsidian is easier to master, because a folder of Markdown files never hides how it works. The common failure runs the other way than you expect: OneNote's blank canvas quietly fills with scattered, unsearchable fragments, while Obsidian's empty vault gives you no opinion about what to build.

## What each one actually costs

Pricing is where the AI overview and most comparisons go vague. Here are the real shapes, current as of 2026. Both companies adjust plans, so confirm the exact figure before you commit a team.

| Plan | OneNote | Obsidian |
|---|---|---|
| Free tier | Free to use, with limited OneDrive storage | Full personal use, no time limit |
| Individual paid | Microsoft 365 Personal, roughly $10 per month, for storage and Copilot | None needed; personal use is free |
| Team or business | Bundled into Microsoft 365 Business, roughly $12 to $22 per user per month | Commercial license, roughly $50 per user per year for work use |
| AI | Copilot bundled into higher Microsoft 365 plans | None native; you supply your own via plugins |
| Sync across devices | Free through OneDrive | Obsidian Sync add-on, roughly $4 to $8 per month |
| Publishing to the web | Share a notebook link | Obsidian Publish, roughly $8 per month per site |

The honest read: for a solo user, Obsidian is free forever and OneNote is free until you run out of OneDrive storage or want Copilot. For a team already on Microsoft 365, OneNote costs nothing extra and plugs into tools people already use. Neither bill includes the cost that actually bites, which is the time you spend later finding out a note went stale.

## Switching between them: the migration paths

Nobody mentions the exit until you need it, so here is the reality in both directions. Packing is the hard part out of OneNote, and it is worth being honest about [what you are actually moving](https://scribelet.app/blog/onenote-alternative): a years-old notebook is rarely as portable as you remember it.

| Moving | How it goes | What breaks |
|---|---|---|
| OneNote to Obsidian | Export pages, then convert to Markdown with a third-party tool | Ink and handwriting do not survive; canvas layout flattens; embedded files and some formatting are lost; section and page structure needs rebuilding |
| Obsidian to OneNote | Paste or import Markdown into OneNote pages | Wikilinks and the graph do not carry; folder structure becomes notebooks and sections; plugin-rendered content is lost |
| Either to a fresh start | Obsidian exports as-is; OneNote needs a conversion pass first | From OneNote: ink, canvas positioning, and embeds; the typed text travels, slowly |

The asymmetry is the point. Obsidian exports cleanly because the files were always plain text. OneNote resists export because the richest parts, ink and freeform canvas, have no plain-text equivalent, and the format was built for the app rather than for portability. Plan your entry with your exit in mind.

## The questions everyone asks

### Does anyone still use OneNote?

Yes, in very large numbers, especially inside companies and schools already on Microsoft 365. The "everyone is switching to Obsidian" story is loud on Reddit and quiet in corporate notebooks. OneNote's retirement news was about the old OneNote for Windows 10 app, not the format; the current OneNote is alive and bundled with Microsoft 365.

### Why are people leaving Obsidian?

Usually one of three reasons: the blank vault gives no guidance on what to build, sync across devices costs extra or takes a weekend to rig up, and there is no native AI. People who leave Obsidian tend to miss structure or convenience, not ownership. People who arrive at Obsidian are almost always chasing ownership and speed.

### What type of note-taking app is Obsidian?

Obsidian is a local-first, Markdown-based knowledge app. Your notes are plain-text files on your device, linked together with wikilinks and shown as a graph. It is built for linked, durable, private thinking rather than for canvas drawing or team collaboration.

### Is OneNote being discontinued?

No. The older OneNote for Windows 10 app reached end of support, and Microsoft consolidated onto a single OneNote on Windows, part of Microsoft 365. The app and its notebooks continue; only that one legacy version was retired. Obsidian has leaned into the churn with its own [switch from OneNote guide](https://obsidian.md/onenote), which tells you something about where the switchers are heading.

## The question neither answers: will you trust these notes next year?

Here is the dimension every Obsidian vs OneNote comparison skips. Both tools are excellent at getting information in and organizing it once it is there. Neither does anything about what happens to that information afterward.

A developer writes a careful guide to a payment API integration. Eight months later the provider deprecates the OAuth scope the guide depends on. The note still looks authoritative in both OneNote and Obsidian. The next teammate to follow it spends a morning chasing 401 errors before realizing the doc went stale. The editor was never the problem. The accuracy was.

This is knowledge decay, and it is a property of information, not a failure of discipline. Technical docs decay in weeks, research citations get retracted, competitor data shifts, and links rot. Your notebook does not know. Your vault does not care. As we have argued in comparing [Obsidian and Logseq on the file question](https://scribelet.app/blog/obsidian-vs-logseq), the format war misses the part that actually decides whether a note is still worth reading.

![Line chart showing a note's accuracy declining over a year without maintenance, while scheduled background verification keeps it near fully accurate](/blog/obsidian-vs-onenote/note-accuracy-decay.svg)

OneNote's Copilot does not close this gap, because reactive AI only helps when you already suspect something is wrong and think to ask. Obsidian's plugins do not close it either, because they automate capture and formatting, not verification. The honest answer to "Obsidian or OneNote" is that for keeping notes accurate over time, the score is zero to zero.

## A third option: ownership plus maintenance

This is where a different kind of tool enters the comparison, and where we are upfront that we built one.

Scribelet starts from Obsidian's ownership instinct and adds the proactive AI that OneNote's Copilot only gestures at. Background agents search the web on a schedule you set, compare what they find against what you wrote, and surface the difference as a diff: green for new information, red for what is outdated, with a source link on every change. You review, accept or dismiss, and the note stays current without a manual audit. That is the maintenance layer neither OneNote nor Obsidian offers.

A consultant reopens last quarter's competitor analysis for a new pitch. Two rivals changed pricing; one shipped a feature that did not exist when the note was written. In OneNote or Obsidian, nothing flags the drift. With scheduled verification, the changes are waiting as a diff before the meeting, not discovered during it.

The ownership story holds too. You can [bring your own key](https://scribelet.app/blog/byok-ai) and route AI through OpenAI, Anthropic, or Gemini, with the key encrypted at rest, so your notes go to the provider you trust rather than one a vendor chose for you. Bringing your own key is optional; the AI works out of the box. Notes connect with the same wikilinks Obsidian users already know, and they stay in sync across phone, tablet, and desktop without a separate surcharge.

The honest tradeoff: Scribelet is not a OneNote-style infinite canvas with stylus ink, and it is not a bare local vault you mold with plugins. It is for people whose notes need to stay accurate, not just captured.

## Obsidian vs OneNote vs Scribelet: which should you choose?

The decision comes down to what you are most afraid of losing. Match your situation to the row.

| Your situation | Best fit | Why |
|---|---|---|
| You handwrite notes on a tablet and live on an infinite canvas | OneNote | Ink, palm rejection, and freeform layout are the whole point |
| Your whole team already runs on Microsoft 365 | OneNote | Free, shared, and wired into Teams and Outlook |
| Solo thinker who wants speed and offline plain text | Obsidian | Ownership and instant local files, no sync surcharge |
| Student or researcher juggling linked sources | Obsidian | Plain-text vault plus the graph, portable across years |
| Developer keeping technical notes that go stale fast | Scribelet | Background verification catches the decayed API doc for you |
| Anyone whose real pain is not trusting old notes | Scribelet | The maintenance layer neither incumbent has |
| You want AI you prompt for drafts and summaries | OneNote | Copilot is reactive and built into Microsoft 365 |
| You want AI that checks your notes for you | Scribelet | Scheduled diffs, not prompts |

If you have already decided OneNote is not it, we ranked [eleven OneNote alternatives by the reason you are leaving](https://scribelet.app/blog/onenote-alternative), and if the pull is toward plain text, we sorted the [best Obsidian alternative](https://scribelet.app/blog/obsidian-alternative) by what actually broke for each kind of user. For the heavier all-in-one comparison, our [Obsidian vs Notion breakdown](https://scribelet.app/blog/notion-vs-obsidian) covers databases and collaboration the OneNote debate does not touch. And for the other edge of that triangle, we put [Notion and OneNote head to head](https://scribelet.app/blog/notion-vs-onenote) too.

> **Want to see the difference for yourself?** Start free, run your first verification, and watch what a diff actually catches. The [Pro plan](https://scribelet.app/pricing) is $8/mo or $79/yr when you want the full set.

## The comparison that measures the wrong year

Run the standard Obsidian vs OneNote comparison and you get a fair answer to a narrow question: which app fits the way you work right now. OneNote wins on canvas, ink, and Microsoft. Obsidian wins on ownership and speed. If the app you are actually comparing Obsidian with is the one on your iPhone, our [Obsidian versus Apple Notes](https://scribelet.app/blog/obsidian-vs-apple-notes) breakdown runs the same test. Both answers are correct, and both miss the part that actually decides whether a knowledge base survives.

A note is only as valuable as it is true. The editor you pick determines how pleasant it is to write and how freely you can draw; it does nothing about whether what you wrote is still accurate six months later. That is the real failure mode behind every abandoned notebook, and it is the one dimension this debate keeps leaving out.

If staying accurate is what you care about, [start writing with background verification and see your first diff](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>obsidian-vs-onenote</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>onenote</category>
            <category>obsidian</category>
            <category>personal-knowledge-management</category>
        </item>
        <item>
            <title><![CDATA[Moving the Goalposts: How to Spot It and Hold the Line]]></title>
            <link>https://scribelet.app/blog/moving-the-goalposts</link>
            <guid isPermaLink="false">https://scribelet.app/blog/moving-the-goalposts</guid>
            <pubDate>Sun, 25 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Moving the goalposts is the move where the standard quietly changes after you meet it. How to spot it in reviews, debates, AI answers, and your own notes, and how to hold the line.]]></description>
            <content:encoded><![CDATA[
You open the pull request, work through every comment, and push again. The reviewer comes back with a new objection that was never raised the first time. You fix that too. A third round arrives with a fourth concern. Nothing you did was wrong, and yet the work is somehow never finished, because the thing you were being measured against moved every time you reached it. You were not failing to clear the bar. Someone kept moving the goalposts.

That is a named fallacy, and once you can name it you stop blaming yourself for never quite clearing it. Moving the goalposts is one of the quietest ways a standard gets used as a weapon instead of a measure. It rarely feels like bad faith in the moment, because each new demand sounds reasonable on its own. The problem is never any single request. The problem is that the target keeps changing, so meeting it is defined as impossible from the start. Here is what moving the goalposts is, why it works on careful people, where it shows up beyond the debate it is usually filed under, and how to hold the line without accusing anyone of cheating.

## What is moving the goalposts?

Moving the goalposts is [an informal logical fallacy in which the criteria for success are changed after they have already been met, so that evidence or work which satisfied the original standard is dismissed in favor of a new, higher one](https://en.wikipedia.org/wiki/Moving_the_goalposts). The metaphor comes from sport: you line up the kick, the ball sails between the posts, and someone slides the posts so the goal no longer counts. Shifting the goalposts and moving the goalposts are the same move under different verbs.

The structure is always the same. A standard X is set. X is met. Instead of conceding, the person who set it discards X and demands a harder standard, Y. When Y is met, the standard shifts again to Z. Each step looks like ordinary rigor, which is exactly why it survives. What separates it from honest revision is the timing and the direction: the bar moves only after it is cleared, and it only ever moves away, which is [the detail that gets it catalogued as a reasoning error rather than ordinary rigor](https://www.logicallyfallacious.com/logicalfallacies/Moving-the-Goalposts). A knowledge base [that records the standard that was actually agreed, not just the verdict that came later](https://scribelet.app), is what lets you notice the posts have moved, because you have the original position written down to compare against.

## Why moving the goalposts works

A blunt refusal is easy to catch. Moving the goalposts is hard to catch because every individual step is defensible, and the damage is only visible across the whole sequence. Three things make it stick.

The first is that it disguises itself as diligence. "Actually, we also need to handle the edge case" is indistinguishable, in the moment, from a genuine new requirement. Raising the bar is what good reviewers and careful thinkers are supposed to do, so the move borrows the costume of the very thing it corrupts. You cannot object to "let's be thorough" without sounding like you want to cut corners.

The second is that there is no fixed finish line to point at. If the standard was never written down, then "that is a new requirement" and "that was always required" are just two people's memories, and the person moving the posts always remembers the harder version. The absence of a recorded target is not incidental to the fallacy. It is the condition that makes it possible, which is the same reason [a shared, written definition of done](/blog/definition-of-done) is the single most effective defense against it on a team.

The third is effort asymmetry. Moving the goalpost costs one sentence. Meeting the new standard costs hours, and then it happens again. The person shifting the bar spends almost nothing while the person chasing it spends everything, which is the same imbalance that makes [a confident claim so much cheaper to produce than to answer](/blog/brandolinis-law). An argument you can never win by satisfying is not an argument. It is a treadmill with a scoreboard attached.

![A ball is kicked toward goalposts three times. Each time it reaches them, the posts slide farther to the right, so the ball never crosses. A faint marker shows where the original posts stood, far behind the current ones.](/blog/moving-the-goalposts/goalposts-keep-moving.svg)

The picture above is the fallacy in one frame. Round after round, the kick is good, and round after round the posts are farther away than they were. The faint marker on the left is where the goal was when the work started. The distance between it and the current posts is not progress. It is the fallacy, drawn to scale.

## Where moving the goalposts shows up

Most examples of this fallacy are [set in political arguments](https://www.snopes.com/articles/464308/logical-fallacies-and-moving-goalposts/), which makes it easy to assume it lives there. It does not. Naming the everyday settings is what makes the move easy to catch in your own week.

| Where it operates | The original standard | How the posts move |
|---|---|---|
| Code review | "Ship it once the tests pass and it is readable" | After tests pass, "but it should also be faster / handle this case / match this other pattern" |
| Hiring and promotion | "Hit this target and you get the role" | Target hit, then "we also want to see leadership / tenure / one more quarter" |
| Sales and bonuses | "Close X and the bonus is yours" | X closed, then the quota retroactively becomes X plus a new condition |
| A skeptic in a debate | "Show me one study" | Study shown, then "one study proves nothing, show me a meta-analysis" |
| Relationships | "I just want you to decide on your own" | You decide, then "you should have checked with me first" |
| AI output review | "Give me a summary I can use" | Summary given, then an endless series of "but also cover..." that never converges |

The engine under every row is identical. A standard is met, and rather than accept it, the person who set it swaps in a harder one and treats the swap as if it were the original agreement. The tell is also identical across all of them: the bar only ever moves after you clear it, and it only ever moves in the direction of harder. A requirement that genuinely existed from the beginning does not wait until you have satisfied the old one to appear. This is a close cousin of [treating two unlike things as equal on a single shared trait](/blog/false-equivalence): both are moves that feel like reasoning while quietly changing the terms of the thing being judged.

## Moving the goalposts in your notes and AI tools

For most people now, the version that costs the most does not come from an opponent. It comes from an assistant, and from the way standards vanish when they are never written down. You ask an AI to draft something "good enough to send," it returns a draft, and then you find yourself typing "also make it shorter," "also add a caveat about X," "also match the tone of the other one." Each addition is reasonable. Together they are a standard that was never fixed and now keeps rising, and the tool will happily chase it forever because it has no memory of what "good enough to send" was supposed to mean.

The deeper risk is that the moving standard never gets recorded, so the next time the same work comes around you start from the shifted posts without realizing it. You remember that the last draft "needed a lot of work" and not what the actual target was, and the bar ratchets up one more notch. The fix is to make the capture do the one thing the moving standard refuses to: write the finish line down, before the work starts, in a place you will reread. [Checking a claim and the criteria behind it at the moment you save it](/blog/ai-fact-checking-for-notes) is the cheap moment to pin a standard in place, so that "done" means what it meant when you agreed to it. A decision made against a target that keeps sliding is the kind you [pay for later without seeing it coming](/blog/second-order-thinking), because by the time you notice, the original standard is gone and only the latest, hardest one remains. A note that quietly absorbs each new requirement until the original scope is unrecognizable is [the same drift that turns a focused project into a bloated one](/blog/feature-creep), run on a standard instead of a feature list.

## How to respond to moving the goalposts

You cannot beat this one by working harder, because working harder is what feeds it. You beat it by fixing the target in place and making every later change to it visible. A few moves do most of the work, whether the posts are being moved by a reviewer, a counterpart in an argument, or your own drifting expectations.

1. **Write the finish line down first, before any work begins.** The single most effective defense is a recorded standard both sides agreed to. "We said: tests pass, readable, ships this week." Once that exists, a new demand has to announce itself as new, instead of hiding as something that was always there.
2. **Name the shift, without naming motives.** When a new standard appears, say it plainly and neutrally: "That is a new requirement, not the one we agreed to." You do not have to accuse anyone of acting in bad faith. Most goalpost-moving is sincere. Naming the move is enough to stop it, and it works whether the shift was deliberate or not.
3. **Separate new information from a moving goalpost.** Sometimes the standard should change, because something real was learned. The test is direction and trigger: a legitimate change comes from new information and can move the bar either way; moving the goalposts only ever raises it, and only after the old one was met. Grant the first. Flag the second.
4. **Put the burden back where it belongs.** If someone keeps demanding a higher standard of proof, ask what standard would actually settle it, in advance. If no answer is possible, the request was never about evidence, which is the same point [Hitchens's razor](/blog/hitchens-razor) makes about claims that arrive without any burden attached: a demand you can never satisfy is not a demand you are obligated to chase.
5. **Close the loop in writing.** When the work is accepted, record that it met the agreed standard, and record any genuinely new requirements as their own next step rather than folding them silently into "it still is not done." This is what stops the next round from starting at the shifted posts.

None of this requires treating the other person as an adversary. The goal is not to win a fight. It is to make the target hold still long enough that meeting it means something.

## Moving the goalposts vs related ideas

The fallacy sits next to several neighbors, and the distinctions are worth keeping straight, because each one fails on a different axis.

| Idea | What it gets wrong | How it differs from moving the goalposts |
|---|---|---|
| **Moving the goalposts** | Changes the standard after it is met, always upward | The baseline case: the target shifts away each time it is reached |
| Scope creep / feature creep | Lets requirements grow past the original plan | About *scope expanding over time*, often without bad intent; goalpost-moving is specifically a standard raised after it was met |
| False equivalence | Treats two unlike things as equal over a shared trait | About *a bad comparison*, not a shifting standard |
| Hitchens's razor | Dismisses claims asserted without evidence | About *the burden of proof*; goalpost-moving abuses an accepted burden by raising it endlessly |
| Special pleading | Demands an exception to a rule without justifying it | A *one-off exemption*; goalpost-moving is a *repeating* escalation of the standard itself |

The one most often confused with it is scope creep, because both end with "we are not done yet." The difference is intent and shape. Scope creep is requirements growing as understanding grows, usually sincerely and in all directions. Moving the goalposts is a standard that only rises, and only after the previous one was satisfied. Scope creep is a plan that got bigger. Moving the goalposts is a finish line that runs away.

## The one move that matters

Moving the goalposts is hard to catch in the moment because every new demand is reasonable on its own, and the fallacy only becomes visible when you can see the whole sequence at once. That is also where the defense lives. The reliable move is to write the finish line down before the work starts and keep the record, so that when the posts move you have the original position to point at. A knowledge base that [holds the standard you actually agreed to, not just the verdict that came later](https://scribelet.app), is how you keep "done" from quietly becoming "do more," and how you tell an honest change of requirements from a target that was never meant to be reached. Try it free.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>moving-the-goalposts</category>
            <category>logical-fallacy</category>
            <category>critical-thinking</category>
            <category>ai</category>
            <category>media-literacy</category>
        </item>
        <item>
            <title><![CDATA[False Equivalence: How to Spot and Dismantle It]]></title>
            <link>https://scribelet.app/blog/false-equivalence</link>
            <guid isPermaLink="false">https://scribelet.app/blog/false-equivalence</guid>
            <pubDate>Sat, 24 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[False equivalence is the fallacy of treating two very different things as equal because they share one surface trait. How to spot it in comparisons, AI answers, and your own notes, and how to respond.]]></description>
            <content:encoded><![CDATA[
Someone drops a line into a planning doc: "it's basically Postgres with a nicer UI." Both store your data, both speak something close to SQL, so the sentence slides past without a second look and the comparison quietly becomes the decision. A week later you are knee deep in the differences that line erased, the ones about durability guarantees and operational load and what happens at three in the morning, and you realize the whole choice turned on a single true but shallow trait that was never the point.

That move has a name. It is false equivalence, and it is one of the most effective ways a bad comparison gets through a room full of careful people. It works precisely because the shared trait is usually real. The two things genuinely do have something in common, and that grain of truth is what carries the much larger claim that they are therefore the same, or close enough to treat the same. For anyone who weighs options, reads to decide, or leans on an AI assistant to compare things, false equivalence is not a debate-club curiosity. It is a failure mode that lives inside tool choices, technical arguments, and the notes you keep. Here is what it is, why it is so persuasive, where it shows up, and how to take it apart.

## What is false equivalence?

False equivalence is [a logical fallacy in which two things are treated as equal because they share one superficial trait, while the differences that actually matter are ignored](https://en.wikipedia.org/wiki/False_equivalence). The shared trait is real. The equivalence it is used to justify is not. The usual shorthand is "comparing apples and oranges," but that undersells it, because the fallacy is not that the two things differ. Everything differs from everything in some way. The fallacy is picking the one axis on which they match, holding it up as the whole comparison, and letting the axes that decide the question drop out of view.

The structure is always the same. A and B share property X. The argument treats X as the relevant dimension. But the real question depends on properties Y and Z, where A and B are not close at all. A small open side project and a bank's core ledger are both "just software that stores records." True, and useless, because the thing you are actually deciding runs entirely on the dimensions that sentence skipped. A knowledge base [that stores the reasoning and the differences behind a conclusion, not just the conclusion itself](https://scribelet.app), is what lets you reopen a comparison later and see which axis it was really standing on.

## Why false equivalence is so persuasive

The persuasive power comes from the grain of truth. A pure non sequitur gets caught, because the listener can see the two halves do not connect. False equivalence connects them with something genuine, so the objection has to be more precise than "that's wrong." You have to say "that's true, and it is the wrong dimension," which is a harder and slower thing to say in the moment, especially out loud, especially when the comparison already sounds reasonable.

Three features make it stick.

The first is that it compresses. "They're basically the same" is short, confident, and memorable, while the correct response is a list of the ways they differ and why those ways decide the question. Brevity reads as clarity, and the longer, more accurate account sounds like hedging next to it. The second is that it exploits a real cognitive shortcut. Finding a shared feature is how we categorize the world, and most of the time the category is good enough, so the habit of "same category, treat the same" is usually rewarded and rarely examined. False equivalence rides that habit into cases where the category is doing no real work. The third is asymmetry of effort. Stating the equivalence costs one sentence. Refuting it costs a paragraph, because you have to reintroduce all the context the comparison stripped out, which is [the same reason a confident wrong claim is so much cheaper to produce than to clean up](/blog/brandolinis-law). The person making the false equivalence spends a little; the person answering spends a lot.

![On the left, a false equivalence holds up the one small trait two very different things share and draws an equals sign across them. On the right, the differences it ignored, in scale, evidence, and stakes, are far larger than the sliver of overlap.](/blog/false-equivalence/one-shared-trait.svg)

The picture above is the fallacy in one frame. The shared trait is real, and it is small. The differences that decide the question are large, and they are exactly what the equals sign is drawn over. False equivalence is not an error of inventing a similarity. It is an error of scale, treating a sliver of overlap as if it were the whole shape.

## Where false equivalence shows up

Once you have the shape, you start catching it in places that have nothing to do with politics, which is where most examples are set. Naming the setting makes the move easier to see.

| Where it operates | The shared trait it leans on | What it ignores |
|---|---|---|
| Tool and vendor comparisons | "Both do X" (store data, send messages, run jobs) | Reliability, operational cost, failure modes, scale |
| An AI answer weighed against an expert | Both are "a confident, fluent explanation" | Evidence, track record, accountability for being wrong |
| "Both sides" framing in a review | Two objections were both "raised" | One is backed by a benchmark, the other by a hunch |
| Whataboutism in a thread | Both parties "did something wrong" | Severity, intent, scale, and whether it answers the point |
| Moral or risk equivalence | Two events "are both bad" | Magnitude, probability, and what is actually comparable |

The engine under every row is identical. A true, shared surface feature is promoted to the status of the whole comparison, and the dimensions that would separate the two things are left off the table. The tell is always the same too: the comparison feels tidy, and the moment you ask "same along which axis, and is that the axis the decision turns on," the tidiness falls apart. This is the close cousin of [treating a simple model of a thing as if it were the thing itself](/blog/the-map-is-not-the-territory). A false equivalence is a map with one feature drawn in and everything else left blank, handed to you as if it were the territory.

## False equivalence in your notes and AI tools

For most people now the sharpest version does not arrive in an argument. It arrives in an answer. You ask an assistant to compare two libraries, two approaches, two tools, and it returns a clean, balanced paragraph that lists what they have in common and gives each a fair-sounding nod. The format itself leans toward equivalence, because an even, hedge-both-ways summary reads as fair and complete. What it often skips is the one dimension on which the two are not close, the dimension your actual decision depends on, because that dimension takes a stance and the smooth summary avoids taking one.

The risk is that the balanced-sounding comparison gets saved as a balanced-sounding fact. You capture the takeaway, "these two are roughly equivalent, with tradeoffs," and the specific axis where they diverge, the one worth the note, was never written down because the answer never surfaced it. Each time you reread the tidy summary it feels more settled, and [the slow drift of a note from something you understood into something you only half recognize](/blog/knowledge-decay) finishes the job. The fix is to make the capture do what the comparison would not: record the axis that actually differs, and the evidence for it. [Checking a claim and its grounds at the moment you save it](/blog/ai-fact-checking-for-notes) is the cheap moment to notice that an equivalence was asserted and never earned. A decision filed on a false equivalence is the kind you end up [paying for later without ever seeing it coming](/blog/second-order-thinking), because the dimension that mattered was edited out before it reached your notes.

## How to respond to a false equivalence

You cannot refute a false equivalence by denying the similarity, because the similarity is usually real. You refute it by moving the conversation to the dimension the comparison skipped, which is also [how the research on countering it frames the fix](https://effectiviology.substack.com/p/false-equivalence): surface the differences the comparison hid rather than deny the likeness. A few moves do most of the work, in a meeting or in the margin of your own thinking.

1. **Grant the shared trait, out loud.** Start with "yes, both of those are true." Conceding the real part immediately strips the argument of its defense and clears the way to the actual question. Fighting the similarity is how you lose, because you are now arguing against something true.
2. **Name the axis that decides it.** Say plainly which dimension the decision actually turns on. "Both store data, agreed. The question is what happens when a write fails, and there they are not close." The move is to replace the comparison's axis with the relevant one.
3. **Quantify the gap.** A false equivalence survives on vagueness, so put a number or a concrete consequence on the difference. "One loses a transaction once a decade, the other once a week" ends the comparison faster than any adjective.
4. **Ask for the comparison on the right dimension.** Turn it into a question the other person has to answer on your axis, not theirs. "On durability specifically, how do they compare?" If the equivalence was false, it cannot be restated there.
5. **Watch for the retreat.** A common follow-up is to quietly shrink the claim to something defensible ("well, I just meant they're similar"), then expand it again later. Pin the claim to a single meaning and hold it there. If "similar" is all that was meant, then it was never an argument for treating them the same.

None of this requires calling anyone dishonest. Most false equivalence is sincere, a real shortcut misfiring, not a trick. The response is the same either way: concede the overlap, name the dimension that matters, and make the comparison happen there.

## False equivalence vs related ideas

The fallacy gets filed next to several neighbors, and the distinctions are worth pinning down, because each one fails on a different axis.

| Idea | What it gets wrong | How it differs from false equivalence |
|---|---|---|
| **False equivalence** | Treats two unlike things as equal over one shared trait | The baseline case: a real similarity is inflated into sameness |
| False balance | Gives two positions equal weight regardless of evidence | A *media and framing* version of false equivalence, about airtime rather than logic |
| [Brandolini's law](/blog/brandolinis-law) | Describes the cost of refuting nonsense, not a comparison | About *effort asymmetry*; it explains why false equivalence is annoying to answer, not what it is |
| [Hitchens's razor](/blog/hitchens-razor) | A claim asserted without evidence can be dismissed without evidence | About *unsupported assertions*; false equivalence smuggles in a supported one to carry an unsupported leap |
| [The illusory truth effect](/blog/illusory-truth-effect) | Repetition makes a claim feel true | About *a claim feeling true through repetition*, not two things feeling equal through overlap |

The one worth keeping straight is false balance, because it is the same error wearing a press badge. False equivalence is the logical move, two unlike things declared equal on a shared trait. False balance is that move applied to coverage and attention, where a fringe claim gets equal time with an established one because "both views exist," [a trap newsrooms get warned about by name](https://www.pbslearningmedia.org/resource/above-the-noise-false-equivalence/above-the-noise-false-equivalence/). Same inflation of a thin similarity, different venue.

## The one move that matters

False equivalence is hard to catch in the moment because the similarity it rests on is genuine, and a true statement does not trip the alarm that a false one would. The reliable defense is a single question, asked before the comparison sets: same along which dimension, and is that the dimension the decision turns on? If the answer is a shrug, the equivalence was carrying more weight than it could hold. A knowledge base that [keeps the axis a comparison actually turned on, and the evidence behind it](https://scribelet.app), not just the clean verdict that two things were "basically the same," is how you keep your decisions honest about what they were really standing on. Try it free.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>false-equivalence</category>
            <category>logical-fallacy</category>
            <category>critical-thinking</category>
            <category>ai</category>
            <category>media-literacy</category>
        </item>
        <item>
            <title><![CDATA[Illusion of Explanatory Depth: You Know Less Than You Think]]></title>
            <link>https://scribelet.app/blog/illusion-of-explanatory-depth</link>
            <guid isPermaLink="false">https://scribelet.app/blog/illusion-of-explanatory-depth</guid>
            <pubDate>Fri, 23 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The illusion of explanatory depth is the gap between feeling you understand something and being able to explain it. Why it fools everyone, and how to catch it in your own notes and AI answers.]]></description>
            <content:encoded><![CDATA[
Ask an assistant to explain how something works, something you have always half understood but never really sat with. How a language model turns a prompt into a sentence, say, or how a zip file gets smaller without losing anything. The answer comes back clean and confident, it clicks, and you close the tab satisfied that you now understand. Then a week later someone asks you to explain it, and you get one sentence in before the floor gives way. You knew the shape of it. You could not reconstruct a single step.

That is the illusion of explanatory depth, and it is one of the more reliably humbling findings in cognitive science. The feeling of understanding and the ability to explain are produced by different machinery, and the first runs far ahead of the second without ever telling you. For anyone who reads to learn, saves what they read, or leans on an AI assistant to explain things, this is not an academic curiosity. It is a description of how a shallow understanding gets filed away as a deep one, inside your own head and your own notes. Here is what the illusion of explanatory depth is, why it happens, where it bites, and how to stop it from quietly inflating what you think you know.

## What is the illusion of explanatory depth?

The illusion of explanatory depth is [the tendency to believe you understand how complex things work far better than you actually do](https://en.wikipedia.org/wiki/Illusion_of_explanatory_depth). It was named in 2002 by the psychologists Leonid Rozenblit and Frank Keil, in a paper with the pointed title ["The Misunderstood Limits of Folk Science."](https://pmc.ncbi.nlm.nih.gov/articles/PMC3062901/) Their method was simple and merciless. They asked people to rate, on a scale of one to seven, how well they understood an everyday object: a zipper, a flush toilet, a bicycle, a speedometer. Confidence was high. Then they asked those same people to write a step-by-step explanation of how the thing actually works. Confidence collapsed. Forced to produce the mechanism, people found they could not, and their self-rating dropped to match.

The crucial detail is what the illusion attaches to. It targets explanatory knowledge, the how and why of causal systems, and it mostly leaves facts, procedures, and stories alone. You know your own phone number, and you do not feel you understand it. But ask how the phone connects a call and the gap opens, because the subject is a mechanism with hidden parts, and hidden parts are exactly what the feeling of understanding papers over. A knowledge base [that stores the mechanism and the source behind a claim, not just the conclusion](https://scribelet.app), is the difference between a note you can rebuild an explanation from and one that only reminds you that you once felt you understood.

## Why the illusion of explanatory depth happens

The root cause is a confusion between two things that usually travel together: familiarity and understanding. You have seen a zipper ten thousand times. You used one this morning. That fluency, the ease with which the thing comes to mind, feels like knowledge, and most of the time the distinction never gets tested, so the proxy holds. Reading a crisp explanation does the same at second hand. The author did the work of organizing the mechanism into clean prose, and the ease of following it registers as the ease of knowing it. You borrow the structure of their understanding and mistake it for your own.

Three features make the illusion worse than ordinary overconfidence.

The first is that it is invisible from the inside. You cannot feel the steps you are missing, because the missing steps are the very thing you do not have. The sensation of understanding stays smooth precisely where the knowledge is absent, which is why no amount of introspection surfaces it. The second is that it collapses the instant you try to produce an explanation, and only then. Thinking you understand costs nothing. Explaining out loud, or writing it down for someone who will push back, forces you to lay out the causal chain and find the broken link. The third is that it scales with complexity. The more moving parts a system has, the more room there is to feel you grasp the whole while holding almost none of the parts, which is why people hold their most confident and least examined views on the most complicated subjects.

![Before you try to explain something, how well you feel you understand it towers over how well you can actually explain it, and trying to explain it step by step collapses the felt understanding down to meet the real one.](/blog/illusion-of-explanatory-depth/confidence-vs-understanding.svg)

The chart above is the whole effect in two panels. On the left, before any test, the felt understanding stands well above the real one, and the distance between them is the illusion. On the right, after you try to explain the thing step by step, the felt bar drops to meet the real one. Nothing about your actual knowledge changed. The only thing that moved was the honesty of your estimate.

## Where the illusion of explanatory depth shows up

Once you have the shape of it, you start seeing it everywhere, and naming the instances makes them easier to catch.

| Where it operates | How the illusion forms | The tell |
|---|---|---|
| Reading an AI explanation | A fluent, confident answer reads as your own understanding | You feel you learned it but cannot say it back without rereading |
| Technical docs you skim | Recognizing the terms feels like knowing the system | You can describe what it does, not how or why it does it |
| Strong opinions on hard topics | Repeated exposure to a debate stands in for grasping the mechanism | You hold the position firmly and cannot explain the thing behind it |
| Code you copied that works | Working output feels like comprehension | You cannot predict what breaks if you change one line |
| A note you reread | Familiarity with your own words feels like mastery | The note restates a conclusion and reconstructs no steps |

The effect reaches past trivia into things that matter. [In studies of political opinion](https://thedecisionlab.com/biases/the-illusion-of-explanatory-depth), people asked to explain how a policy actually works, step by step, rather than just state whether they back it, come away less certain and less extreme, because the demand to explain exposes how little of the mechanism they were holding. The strongest positions often sit on the thinnest explanations.

Every row runs on one engine. Something becomes familiar, familiarity feels like understanding, and no test ever forces the difference into the open. This is the near-cousin of [why experts write documentation nobody can follow](/blog/curse-of-knowledge): the curse of knowledge is understanding so deep you forget other people lack it, and the illusion of explanatory depth is understanding so shallow you have not noticed you lack it yourself. Same missing step, opposite ends of the same staircase.

## The illusion of explanatory depth inside your notes and AI tools

For most people the sharpest version is not the zipper. It is the gap between a note that holds a conclusion and a note that holds an understanding, and it hides in the exact place you built to make yourself smarter: your own knowledge base.

Here is how it gets in. You read something, or an assistant explains it, and the explanation lands cleanly. You save the takeaway, the one line that felt important, because the mechanism felt obvious at the time. Weeks later the note is still there, in your own words, carrying the authority of something you chose to keep. But the mechanism was never captured, because you never felt you needed to, and that feeling was the illusion. Each reread of the conclusion deepens the sense that you understand, and [the slow way a note drifts from something you knew into something you only recognize](https://scribelet.app/blog/knowledge-decay) does the rest. A note that only reminds you that you once understood is not a note you can act on.

AI tools make the trap smoother. An assistant produces explanation on demand, fluently, in an even and confident register, and the fluency of the output is easy to mistake for the fluency of your own grasp. You read a clean paragraph about how something works, feel the click, and move on, never testing whether you could regenerate a word of it with the model closed. The writer David Epstein described one version of the test for drafts: if an idea cannot be explained cleanly to someone who will push back, it is not understood well enough to put on the page yet. That is the defense in one line. The point is not to distrust the explanation. It is to make producing the explanation yourself the thing that happens before you file it, because [reconstructing and checking a claim at the moment you capture it](/blog/ai-fact-checking-for-notes) is the one cheap moment to find out whether you actually have it.

## How to catch the illusion of explanatory depth

You cannot feel the gap directly, so the only reliable move is to run the test that exposes it. A few habits do most of the work.

1. **Explain it before you trust it.** When something feels understood, take sixty seconds and explain it out loud or in writing, as if to someone who will interrupt. The feeling survives or it does not, and either way you learn something introspection cannot tell you.
2. **Make your notes reconstruct, not restate.** A note that repeats a conclusion is a bookmark. A note that lays out the mechanism, the why, and the conditions under which it fails is an understanding you can reload. Write the second kind, especially when the first kind feels like enough.
3. **Separate "I followed it" from "I could produce it."** Following a clean explanation is a low bar that feels like a high one. Before you count something as known, check whether you could rebuild it with the source closed.
4. **Capture the mechanism, not just the takeaway.** The takeaway is what the illusion lets you keep. The mechanism is what it quietly drops. When you save something, save the part you will not be able to regenerate later.
5. **Be most suspicious of your most confident understandings.** The views that feel most settled have usually had the least explanation-testing, not the most. Confidence and examination tend to run in opposite directions, so treat a strong feeling of understanding as a reason to test it, not a reason to skip the test.

None of this requires doubting everything you read. It requires moving the bar from recognizing an explanation to producing one, and doing it early, while the source is still in front of you.

## Illusion of explanatory depth vs related biases

The illusion gets filed next to several cousins, and the differences are worth pinning down, because the defenses differ.

| Idea | What produces the false confidence | How it differs from the illusion of explanatory depth |
|---|---|---|
| **Illusion of explanatory depth** | Mistaking familiarity with a system for a grasp of how it works | The baseline case: you overrate how well you could explain the mechanism |
| Dunning-Kruger effect | Low competence leaves you unable to see your own gaps | About *overall skill*, not the specific gap between feeling and explaining |
| The curse of knowledge | Knowing something so well you cannot imagine not knowing it | The inverse: too much understanding to model a novice, not too little to notice your own |
| [The illusory truth effect](/blog/illusory-truth-effect) | Sheer repetition makes a claim feel true | About *a claim feeling true*, not a mechanism feeling understood |
| [The map is not the territory](/blog/the-map-is-not-the-territory) | Treating a model of a thing as the thing itself | About *a representation standing in for reality*; a note that points at an understanding is not the understanding |

The row that matters most is the contrast with the curse of knowledge, because the two are mirror images that both end in a document nobody can use. The curse comes from knowing too much to see the reader. The illusion comes from knowing too little to see yourself. Catching either one depends on the same move: forcing the explanation out of your head and into the open, where its gaps become visible.

## The one move that matters

The illusion of explanatory depth is not a flaw you can reason your way out of in the moment, because in the moment the feeling of understanding is all you have, and it feels exactly like the real thing. The only reliable intervention is a test run early: try to produce the explanation yourself before you decide you have it, and capture the mechanism rather than just the conclusion so the understanding survives being filed. A shallow understanding you never tested is the kind you end up [building a decision on without seeing what follows from it](/blog/second-order-thinking). A knowledge base that [holds the mechanism, the why, and the source behind each note](https://scribelet.app), not just the takeaway that felt obvious at the time, is how you keep what you think you know honest about what you can actually explain. Try it free.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>illusion-of-explanatory-depth</category>
            <category>cognitive-bias</category>
            <category>critical-thinking</category>
            <category>ai</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[The Illusory Truth Effect: Why Repetition Makes Things Feel True]]></title>
            <link>https://scribelet.app/blog/illusory-truth-effect</link>
            <guid isPermaLink="false">https://scribelet.app/blog/illusory-truth-effect</guid>
            <pubDate>Wed, 21 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The illusory truth effect is the pull to believe a claim because you have heard it many times. Why repetition feels like truth, and how to stop it inside your own notes and AI tools.]]></description>
            <content:encoded><![CDATA[
There is a particular kind of fact you have never actually checked. You know it the way you know a jingle. You have seen it in three articles, a friend repeated it at dinner, it turned up in a podcast, and by now it sits in your head with the quiet confidence of something settled. Then one day you go to use it, to cite it in a document or build an argument on it, and you reach for the source and find there isn't one. You never verified it. You just kept encountering it, and somewhere along the way the encountering turned into believing.

That is the illusory truth effect, and the unsettling part is not that it fools gullible people. It is that it fools everyone, including the people who pride themselves on not being fooled. The sensation of truth and the fact of truth are produced by different machinery, and repetition reliably moves the first without touching the second. For anyone who takes notes, saves sources, or runs an AI assistant over their own documents, this is not a trivia-night curiosity. It is a description of how bad information gets promoted to trusted information inside your own head and your own files. Here is what the illusory truth effect is, why repetition feels like truth, where it bites hardest now, and how to keep it out of the knowledge you rely on.

## What is the illusory truth effect?

The illusory truth effect is [the tendency to believe a statement is true because you have encountered it before](https://en.wikipedia.org/wiki/Illusory_truth_effect), regardless of whether it is actually true. Repeated exposure to a claim, even a false one, raises the odds that you will rate it as accurate the next time you meet it. The effect was first documented in a 1977 study by Hasher, Goldstein, and Toppino, and it has held up across hundreds of experiments since: show people a set of plausible-but-false statements, repeat some of them, and the repeated ones are judged more true, by the same people, with no new evidence introduced.

What makes it dangerous is that it operates below the level of argument. You are not being persuaded by a better case. You are being worn into agreement by familiarity, and familiarity does not discriminate between a fact that is repeated because it is true and a falsehood that is repeated because it is cheap to repeat. If you keep a knowledge base, [a tool that stores each claim with its source and context](https://scribelet.app) is the difference between a note you can stand behind and a note that merely feels right because you have reread it a dozen times.

## Why repetition feels like truth

The mechanism has a name: processing fluency. The second time your brain meets a statement, it processes it faster than the first. That ease is a real, physical sensation, and your mind treats it as a signal. The trouble is that it reads the signal wrong. The fluency means "I have seen this before," but the brain hears "this is true," because in everyday life the two usually travel together. Things you encounter repeatedly often are true, so familiarity became a cheap proxy for accuracy, and the proxy works well enough that nobody notices it is a proxy until it is exploited.

Three features of the effect make it worse than an ordinary bias.

The first is that **no one is immune.** Intelligence does not protect you. Being careful does not protect you. Even subject-matter expertise does not reliably protect you: studies find that experts fall for the effect on claims inside their own field when they do not stop to actively retrieve what they know and instead coast on familiarity. The default mode is to let fluency decide, and the default mode is where most of your reading happens.

The second is that **a single exposure is enough to start the slide.** You do not need a propaganda campaign. One prior encounter measurably raises belief on the next, and the effect compounds with each repetition. The third is that **it works even when you were told the claim was false.** Warning someone that a statement is untrue, then repeating it, can still raise their later belief in it, because the familiarity outlives the correction. The retraction fades and the fluency remains.

![As a claim is repeated, how true it feels rises steadily while whether it is actually true stays flat. The gap between the two lines is the illusory truth effect.](/blog/illusory-truth-effect/repetition-vs-truth.svg)

Put those together and you get the shape in the chart above: the feeling of truth climbs with every repetition while the actual accuracy of the claim sits exactly where it started. The whole effect lives in the gap between those two lines, and the gap is invisible from the inside, because the feeling is all you have access to.

## Where the illusory truth effect shows up

The effect is not confined to the lab. It is the operating principle behind several things you already half-notice, and naming them makes them easier to catch.

| Where it operates | How repetition does the work | The tell |
|---|---|---|
| Advertising and slogans | A brand claim repeated across every channel starts to feel like consensus | You "know" a product is the best without having compared anything |
| Political messaging | A talking point or rumor repeated through a campaign reads as credible | A phrase feels true but you cannot name where you first checked it |
| Viral misinformation | A false claim reshared across feeds manufactures a sense of agreement | "Everyone is saying it" stands in for "it has been verified" |
| Repeated AI output | An assistant restates the same confident claim across sessions | You stop questioning an answer you have now seen it give four times |
| Your own notes | Rereading a saved claim makes it feel more settled each pass | A line in your notes feels like a fact and has no source attached |

The pattern is the same in every row. Something gets in front of you more than once, the repetition is driven by how cheap it is to repeat rather than by how true it is, and your sense of its truth rises anyway. This is the engine underneath the broader flood of [bots and machine-written filler crowding out human signal online](/blog/dead-internet-theory): once generating a claim costs nothing, repeating it costs nothing, and the illusory truth effect converts that volume directly into belief.

## The illusory truth effect inside your notes and AI tools

For most readers the sharpest version is not political and not commercial. It is private, and it lives in the exact place you went to protect yourself from bad information: your own knowledge base.

Here is how it gets in. You save a claim because it seemed useful, without recording where it came from or whether you checked it. Weeks later you reread your notes, and the claim is there, in your own words, in your own trusted system. Each reread is another exposure, and each exposure nudges the felt truth upward. By the time you act on it, the note carries the full authority of something you have "always known," when all that actually happened is that you reread an unverified line until it felt settled. This is [the way notes quietly go stale and start misleading you](https://scribelet.app/blog/knowledge-decay) with the mechanism named: the decay is not only that facts change, it is that rereading launders an unchecked claim into a trusted one.

AI tools pour fuel on this. When you ask an assistant a question, it answers in the same even, confident register whether it is reporting something solid or improvising, and if you ask again tomorrow it will likely say the same thing the same way. That repetition is pure fluency with no added evidence, and it is [exactly the kind of claim asserted without support that you are entitled to set aside rather than adopt](/blog/hitchens-razor). It is also the single-source version of [the reason refuting a plausible falsehood costs so much more than producing it](/blog/brandolinis-law): the claim arrives cheap and familiar, and the work of checking it never gets cheaper. The defense is not to distrust your own notes wholesale. It is to make verification a thing that happens once, at the moment of capture, so familiarity never gets to stand in for a check you never did.

## How to resist the illusory truth effect

You cannot turn off processing fluency; it is baked into how reading works. What you can do is stop letting the feeling of familiarity make the truth call on its own. A few habits do most of the work.

1. **Separate "I have seen this" from "I have checked this."** When a claim feels obviously true, treat that feeling as a flag, not a verdict. The ones that feel most settled are the ones you are least likely to have actually verified, precisely because they feel settled.
2. **Trace to the source at the moment you save.** Asking "where did this come from?" breaks the brain's reliance on familiarity, and the cheapest time to ask is when the context is still in front of you. [Verifying a claim against the world as you capture it](https://scribelet.app/blog/ai-fact-checking-for-notes) is the one point where the check is nearly free.
3. **Mark unverified claims as unverified.** A note that says "unchecked" cannot launder itself into a fact on reread, because every exposure now carries the warning with it. An uncaptured doubt disappears; a captured one survives.
4. **Count the source, not the sightings.** Ten articles repeating one unsourced claim is one source, not ten. Collapse repetitions back to their origin before you let volume feel like corroboration. This is [rating the source rather than re-trusting it each time you see it again](/blog/gell-mann-amnesia-effect).
5. **Be most skeptical of what everyone already "knows."** The claims that circulate most freely have had the most exposure and therefore the most illusory-truth lift, which is the opposite of the most scrutiny. Widely repeated is not widely verified.

None of these require distrusting everything. They require moving the decision from how a claim feels to whether it has a source, and doing it once, early, while it is cheap.

## Illusory truth effect vs related biases

The effect gets lumped in with every cousin in the bias family, so it helps to pin down what is specifically about repetition and what is about something else. Each of these is a real failure, but the defenses differ.

| Idea | What drives the false belief | How it differs from the illusory truth effect |
|---|---|---|
| **Illusory truth effect** | Sheer repetition and the fluency it creates | The baseline case: familiarity alone raises felt truth, with no new evidence |
| Confirmation bias | The claim already fits what you believe | About *fit with prior belief*, not raw exposure count |
| Availability heuristic | The claim comes to mind easily | About *ease of recall* when judging frequency or risk, not truth-from-repetition |
| [Gell-Mann amnesia](/blog/gell-mann-amnesia-effect) | Trusting a source you already caught being wrong | About *source reliability over time*, not repetition of one claim |
| [Brandolini's law](/blog/brandolinis-law) | Refuting nonsense costs far more than making it | About the *cost of cleanup* after a falsehood spreads, not why it feels true |

The distinction that matters most is the first one. Confirmation bias needs the claim to agree with you. The illusory truth effect needs nothing but repetition, which is why it can install beliefs you have no prior stake in at all, including ones you would reject on reflection if you ever stopped to reflect.

## The one move that matters

The illusory truth effect is not a flaw you can argue your way out of in the moment, because by the moment of judgment the damage is already done: the claim already feels true. The only reliable intervention happens earlier, at capture, when you still have the context to ask where a claim came from and whether anyone checked it. Make that a habit, and give unverified claims a home that marks them as unverified, and repetition loses its power to promote a guess into a fact. A knowledge base that [holds every note with its source and lets you check a claim against the world as you save it](https://scribelet.app) is how you keep the feeling of truth from quietly outrunning the facts. Try it free.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>illusory-truth-effect</category>
            <category>misinformation</category>
            <category>ai</category>
            <category>content-authenticity</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Dead Internet Theory: When the Web Fills With AI Slop]]></title>
            <link>https://scribelet.app/blog/dead-internet-theory</link>
            <guid isPermaLink="false">https://scribelet.app/blog/dead-internet-theory</guid>
            <pubDate>Mon, 19 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Dead internet theory says bots and AI-generated content now crowd out people online. What it means for the notes and sources you trust, and how to keep real signal.]]></description>
            <content:encoded><![CDATA[
You search for a straight answer to an ordinary question, and the first page is a wall of articles that all say the same thing in the same confident, frictionless voice. Each one restates the question, lists five generic points, and ends with a paragraph that commits to nothing. You scroll a forum thread hoping for a real person who has actually done the thing, and half the replies read like they were generated too: fluent, agreeable, and empty. For a moment you wonder whether anyone is actually on the other end of any of it, or whether you are reading a conversation machines are having with each other while you watch.

That unease has a name. It is the dead internet theory, and it has moved in a few years from a fringe forum idea to a phrase serious people use to describe what the open web now feels like. The headline version is easy to state and easy to wave away as paranoia. What is worth more is understanding which part of it is literally a conspiracy theory and which part is just a measurable description of the incentives, why generative AI turned a slow drift into a flood, and what it means for the notes and sources you rely on, because a web where you cannot tell what was written by a human is a web where provenance becomes the thing you have to protect. If you keep a knowledge base, [a tool that holds each note with its source and context](https://scribelet.app) is no longer a nicety. Here is the dead internet theory in full, with where it came from, how to keep real signal, and the version of it running quietly inside your own sources.

## What is the dead internet theory?

The dead internet theory is [a concept asserting that the public internet is no longer driven primarily by human beings](https://en.wikipedia.org/wiki/Dead_Internet_theory), but has instead been overtaken by bots, automated accounts, and algorithmically generated content, to the point that much of what you see and read was neither written by nor intended for a real person. In its strongest form it is a claim about scale: that the majority of activity online is now non-human, and that authentic human expression is a shrinking minority of what the open web actually contains.

The idea splits cleanly into two very different claims, and keeping them apart is the whole trick to using it well. The paranoid version holds that a deliberate actor, a government or a set of corporations, is manufacturing synthetic content to steer what people think. That part is a conspiracy theory, unproven and mostly unprovable. The practical version makes no claim about intent at all. It says only that cheap automation plus engagement-maximizing algorithms produce a web increasingly filled with bot traffic, content farms, and machine-written filler, because those things are profitable, not because anyone planned a takeover. The practical version does not need a villain. It only needs incentives, and the incentives are real.

## Where the theory came from

The phrase surfaced around 2016 on fringe imageboards and gained wide attention in 2021 through a long forum post by a user called IlluminatiPirate, who argued the internet had "died" sometime around 2016 and been replaced by AI and curated content. In that original framing it carried the full conspiracy weight, and for a few years it stayed a niche, slightly tinfoil idea traded in the same corners that produce most internet folklore.

What changed is that the measurable half caught up with the mythology. By the mid-2020s the mainstream press had picked it up, not to endorse the conspiracy but to note how much of the plain description had come true. The Guardian described the shift from [humans being nudged by algorithms to act like bots, to bots posting like humans at scale](https://www.theguardian.com/technology/2024/apr/30/techscape-artificial-intelligence-bots-dead-internet-theory). Security firms that count traffic for a living began reporting that automated bots generate roughly half of all internet traffic, a figure that turns the theory from a vibe into a number. By 2026 The Atlantic was noting that [the dead internet theory was "back," this time in mainstream conversation](https://www.theatlantic.com/technology/2026/09/chatgpt-imessage-ai-texting/688507/) rather than on the fringe. The leaner version of the idea, the one without the shadowy puppeteer, had quietly become the default way to talk about an web where you genuinely cannot assume a person is behind what you are reading.

## Why the web keeps filling with automated content

The practical version is not a mystery. It is the predictable output of a few incentives that all point the same direction, and seeing them laid out is more useful than any single statistic.

The first driver is that **generation became almost free.** A language model will write a plausible article, a review, a comment, or a reply in seconds, at a cost rounding to zero per piece. The same is true of synthetic images and video. When producing content costs nothing, the economically rational move is to produce an enormous amount of it, and a flood of formulaic, low-effort material, often called AI slop, is exactly what you would expect. It is not that every page is fake. It is that the cost floor that used to limit how much filler could exist has been removed.

The second driver is **the engagement economy rewards volume, not truth.** Platforms and search engines surface whatever gets clicks, and algorithms cannot easily tell a careful human post from a tuned-for-virality machine one. So the system pays out for high-volume, controversial, or formulaic content regardless of who or what produced it, which incentivizes click-farming bots, fake accounts, and content mills. The third driver is the slow decay writer Cory Doctorow named enshittification, the way platforms degrade over time as owners squeeze users for short-term profit. Put the three together and you get a web where the share of what you encounter that is human and placeable keeps shrinking, while the automated share keeps growing.

![As generation gets cheaper, the share of online content you can place as human shrinks while bots and AI-generated content grow, making provenance the scarce signal.](/blog/dead-internet-theory/human-signal.svg)

The result is not that the internet is literally empty. It is that the signal you actually want, a real person who knows something, is harder to find in the noise, and harder to verify once you find it. That is the same shift Sturgeon's law describes with the production cost removed: most of everything was always mediocre, and now the mediocre can be generated without limit, so the filtering problem is worse, not different.

## Dead internet theory and the sources you trust

For most readers the stakes are not philosophical. They are practical, and they land the moment you save something. If you take notes, keep a research base, or run an AI assistant over your own documents, the dead internet theory is not a story about strangers. It is a description of the raw material flowing into your knowledge base.

Every claim you capture from the open web now arrives with an unanswered question attached: was this written by a person who knew something, or generated by a system optimizing for clicks? The surface no longer tells you. A fluent, confident, well-structured passage is exactly what a content mill produces, and exactly what a careful expert produces, and you cannot read the difference off the prose. When you save that passage without its provenance, the uncertainty does not go away. It gets baked into your notes, and six months later you are relying on a line whose origin you can no longer reconstruct. This is a close cousin of [the way notes quietly go stale and start misleading you](https://scribelet.app/blog/knowledge-decay): a source you could not vouch for on the way in becomes a fact you trust by default on the way out.

The sharpest version involves no human source at all. When you ask an AI assistant a question, it hands you an answer in the same even, confident tone whether it is repeating something solid or improvising. That is [a claim asserted with no evidence, which you are entitled to hold rather than adopt](/blog/hitchens-razor), and it is also the dead internet theory in miniature: machine-generated content entering your workflow with no marker of where it came from or whether a human ever checked it. The defense is not to distrust everything. It is to [verify a claim against the world at the moment you save it](https://scribelet.app/blog/ai-fact-checking-for-notes), while the context is still in front of you and the check is cheap.

## Dead internet theory vs related ideas

The theory gets stretched to cover every bad feeling about the modern web, so it helps to pin down exactly what it claims and how it differs from the ideas it travels with. Each of these describes a real failure, but they are different failures with different defenses.

| Idea | What it is about | How it differs from dead internet theory |
|---|---|---|
| **Dead internet theory** | Who produced the content: bots and AI versus humans, at scale | The baseline question, about provenance and authenticity of the whole environment |
| [Poe's law](/blog/poes-law) | Whether a message is sincere or parody | About reading *intent* in one message, not *who or what* created it |
| [Sturgeon's law](/blog/sturgeons-law) | Most of everything is low quality | About the *quality* distribution, not whether a human made it |
| [Brandolini's law](/blog/brandolinis-law) | Refuting nonsense costs far more than producing it | About the *cost* of cleanup once slop exists, not its volume |
| [Gell-Mann amnesia](/blog/gell-mann-amnesia-effect) | Trusting a source you already caught being wrong | About *source reliability over time*, not automation |
| [Betteridge's law](/blog/betteridges-law) | A question-mark headline can be answered "no" | About one *clickbait pattern*, a symptom of the content economy |

The point of the table is not to rank them. It is that the dead internet theory sits underneath the others as the environmental claim: once most of the environment is automated, Sturgeon's crud is generated without limit, Brandolini's cleanup cost explodes, and the clickbait patterns Betteridge's law catches get mass-produced. The related ideas are tools for navigating a web the dead internet theory describes.

## How to keep real signal

You cannot fix the open web, and pretending most content is human when it is not is its own kind of error. The achievable goal is narrower: stop letting unverifiable, automated-by-default content enter your thinking as if it were trusted. A few habits do most of the work.

**Treat provenance as a field, not an afterthought.** When you save something, capture where it came from and how you judged it, not just the claim itself. A note that records "from X, confirmed against Y" survives the dead internet in a way a bare copied sentence never will, because the one thing automation strips is the trail back to a knowable source.

**Verify on the way in, while it is cheap.** The moment to check a claim is when you save it, with the surrounding context still visible. Later, the context is gone and all you have is a confident-sounding line of unknown origin, which is exactly the thing the theory warns you not to trust. This is Brandolini's law applied to your own base: checking now costs seconds, refuting a wrong note you have already relied on costs far more.

**Prefer sources you can place, and rate them over time.** A known author, an outlet with a track record, a person who has actually done the thing: the source often carries the authenticity the individual message cannot. And when a source turns out to be a content mill or an unreliable generator, lower the trust you extend it next time, instead of trusting it again the moment you turn the page.

**Treat a confident AI answer as unplaced content.** An assistant's fluent reply has no provenance marker by default. Use it as a draft to check, not a fact to file. The same discipline that protects you from a stranger's AI-generated post protects you from your own assistant's.

**Move the real conversation somewhere you can see the people.** One honest implication of the theory is that authentic exchange is migrating to smaller, gated spaces where accounts are known. For your own knowledge, the equivalent is a base you control, where every entry is one you placed deliberately, rather than a feed where anything could be anyone.

## When the dead internet theory is overstated

A guard is worth stating, because the idea invites two opposite errors. The first is treating the conspiracy version as established fact. There is no proof of a coordinated plot to replace humans with bots, and claiming there is undercuts the part that is actually defensible. The honest position is the leaner one: automation and engagement incentives are measurably flooding the web with non-human content, no villain required.

The second error is sliding into blanket cynicism, deciding nothing online is real and no source can be trusted. That is paralysis, not skepticism, and it is its own inaccuracy. Plenty of the web is still human, still expert, still worth reading, and a great deal of automated content is perfectly useful. The theory does not ask you to believe nothing. It asks you to stop assuming authenticity you have not checked, which is a specific and manageable discipline. Deciding which sources are even worth that effort is itself [a judgment worth making deliberately](/blog/second-order-thinking) rather than by reflex, so you spend your attention where it buys the most.

## Getting started

The dead internet theory is not a reason to log off in despair. It is a reason to stop treating the open web as a pool of trustworthy human knowledge you can scoop from without looking, in a moment when bots and generated content make up a large and growing share of what is there. The fix is not grand. It is to protect provenance in the one place you fully control: your own notes and sources.

Start there. Capture each claim with where it came from and how far you believed it, so a line of unknown origin does not harden into a fact you rely on. Verify sources at the moment you save them, while the context that tells you whether they are real is still in front of you. And treat a confident AI answer as unplaced content to check, not to file. [Try Scribelet free](https://scribelet.app) and let it keep your notes with their sources and their context, and re-check them against the world, so the signal you can trust today is still something you can trust the day you rely on it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>dead-internet-theory</category>
            <category>ai</category>
            <category>misinformation</category>
            <category>content-authenticity</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Hitchens's Razor: What Can Be Asserted Without Evidence Can Be Dismissed]]></title>
            <link>https://scribelet.app/blog/hitchens-razor</link>
            <guid isPermaLink="false">https://scribelet.app/blog/hitchens-razor</guid>
            <pubDate>Sun, 18 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Hitchens's razor: what can be asserted without evidence can be dismissed without evidence. How to apply it to AI answers and your own notes. Try it free.]]></description>
            <content:encoded><![CDATA[
An AI assistant hands you a clean, specific claim. A precise figure, a named study, a confident one-line verdict, delivered in the same even tone it uses for everything. You are about to paste it into a document that other people will act on. Then you notice what is missing: no source, no citation, nothing you could follow to check it. The sentence is doing all the work of being true without any of the work of showing it. The question is not whether to believe it or disbelieve it. The question is who has to do the next piece of work, you or the claim.

There is a rule for exactly that question, and it is sharper and more useful than its one-line fame suggests. It is Hitchens's razor, and most explanations of it stop at the slogan and move on. What is worth more is seeing what it actually decides (the burden of proof, not the truth), how it differs from the other razors it gets confused with, why generated text has made it a daily tool rather than a debating-club flourish, and what it means for the claims sitting in your own notes. Here is Hitchens's razor in full, with a comparison table, worked examples, and the version running quietly inside your knowledge base.

## What is Hitchens's razor?

Hitchens's razor is [an epistemological principle](https://en.wikipedia.org/wiki/Hitchens%27s_razor) stating that what can be asserted without evidence can also be dismissed without evidence. It was put this way by the writer and journalist Christopher Hitchens in his 2007 book *God Is Not Great*, though the idea is old. It is a modern rendering of a Latin legal maxim, *quod gratis asseritur, gratis negatur*, "what is freely asserted is freely denied." A razor, in philosophy, is a rule of thumb that lets you shave off, or set aside, an unpromising line of reasoning without having to chase it down. This one shaves off the obligation to disprove claims that arrive with nothing behind them.

The core of it is a rule about the burden of proof. If you make a claim, the job of supporting it is yours. Until you offer something, the person on the other side owes you no rebuttal, no counter-study, no refutation. They can set the claim down and walk on, and they have lost nothing by doing so. The razor does not say the unsupported claim is false. It says it has not earned a response yet, and that treating "I could not immediately disprove it" as a reason to believe it is a mistake. The quietest and most common version of that mistake is accepting a statement simply because no rebuttal came to mind fast enough.

## Why the burden sits with the claimant

The razor looks one-sided until you see the alternative, which is unworkable. If the person doubting a claim had to disprove it, then anyone could win any argument by generating assertions faster than they could be checked. Disproving things is slow and often impossible; you cannot prove that an invisible, undetectable object is not in the room. Producing a claim is nearly free. Hand the burden to the skeptic and you have built a machine that manufactures belief for whoever talks fastest, because the cost of asserting and the cost of refuting are wildly out of balance.

That imbalance is itself a named idea. [Refuting a piece of nonsense costs an order of magnitude more than producing it](/blog/brandolinis-law), which is why a debate conducted on the skeptic's dime is lost before it starts. Hitchens's razor is the defense against that asymmetry. It refuses to let the costs land on the wrong side. By keeping the burden with the person making the claim, it stops a conversation, a feed, or a knowledge base from filling up with things that are treated as true only because nobody had the time or the obligation to knock them down. The razor is a burden-allocation rule, not a verdict on content, and that distinction is the whole thing. It decides who acts next, not what is real.

## Hitchens's razor versus the other razors

The razors get blurred together, and keeping them apart is half of using any of them well. Each one shaves off a different kind of unpromising move, and they answer different questions. The table sorts the four that come up most, including the Sagan standard, which is best understood as Hitchens's razor with a dial on it.

| Principle | One-line form | What it decides | Use it when |
|---|---|---|---|
| Hitchens's razor | What is asserted without evidence can be dismissed without evidence | Who carries the burden of proof | A claim arrives with nothing behind it and you are tempted to disprove it |
| Occam's razor | Prefer the explanation with the fewest assumptions | Which of several explanations to favor first | You already have evidence and are choosing between competing accounts of it |
| [Hanlon's razor](/blog/hanlons-razor) | Never attribute to malice what is adequately explained by error | How to read the cause of a bad outcome | An outcome looks hostile and you are about to assume intent |
| The Sagan standard | Extraordinary claims require extraordinary evidence | How much evidence a claim needs | Something is offered with evidence, but the claim is far outside the ordinary |

The row that matters for this post is the last one. The Sagan standard is not a rival to Hitchens's razor; it scales it. Hitchens tells you an unsupported claim can be dismissed. Sagan adds that the amount of support a claim needs rises with how surprising it is. A mundane claim with a little evidence is fine; an astonishing claim with a little evidence is still, for practical purposes, an assertion, because the evidence offered is nowhere near the size of the claim. Together they form one usable test: is there evidence, and is there enough of it for a claim this large? Occam's razor and Hanlon's razor sit in a different lane, because both assume you are already past the evidence gate and are now interpreting what you have.

![A claim reaches one test, is evidence offered: yes leads to weighing it, no leads to dismissing it without counter-evidence.](/blog/hitchens-razor/burden-of-proof.svg)

## Hitchens's razor in the age of AI

Hitchens was arguing about religion and the supernatural. The place the razor earns its keep now is the one the opening described: the output of a language model. Generated text has produced unsupported assertions at a scale and a polish that no human debater could match, and it has stripped the usual warning signs off them.

A model states a claim it is sure of and a claim it is improvising in the same fluent, even register. It does not flag which parts of an answer are grounded in something and which are pattern-completion that happened to sound right. So a specific-looking figure, a named source that does not exist, a confident summary of a study it never read, all arrive wearing the same clothes as the parts that are solid. This is the core reason an AI assistant's confidence tells you nothing: fluent certainty is the one thing the system produces for free, for every claim, true or not. It is the uniform-tone problem that also makes [a machine-written passage impossible to read for sincerity or intent](/blog/poes-law). The confidence is not a signal. It is the absence of one.

Hitchens's razor turns that from a worry into a procedure. An AI claim offered with no source is, exactly, something asserted without evidence, which means you are entitled to dismiss it, or more usefully to hold it, until a source appears. You do not have to disprove the figure. You have to decline to carry it forward until the model, or you, can point to where it came from. The cheapest moment to apply that test is the moment the claim is produced, while the question is fresh and the context is in front of you. That is the same discipline as [checking a claim against the world before you let it into your notes](/blog/ai-fact-checking-for-notes): the razor decides that the burden is the claim's, and the verification is how the claim meets it.

## Examples: applying the razor

The razor is easy to state and easy to skip in the moment, so it helps to see it run against the kinds of claims that actually cross your desk. In each case the first move is the same question: has evidence been offered, and is it enough for a claim this size?

| The claim | Evidence offered | What the razor says |
|---|---|---|
| "Studies show this feature lifts retention 40%." | None, no study named | Dismiss or hold. A number with no source is an assertion wearing a lab coat. |
| An AI answer citing a specific court case | A case name you cannot find anywhere | Hold until verified. A citation that does not resolve is worse than none. |
| "Everyone knows this library is faster." | None | Dismiss as stated. "Everyone knows" is the phrase that marks a missing source. |
| A benchmark result with a linked methodology | A reproducible setup you can read | Engage it. Evidence was offered; now weigh it on its merits. |
| "This approach cannot possibly scale." | A stated reason and a worked example | Engage it. A supported claim earns a real response, agreement or rebuttal. |
| A saved note that reads "X is the best option" | None you captured | Treat as unproven. Past you asserted it; present you owes it no belief. |

The pattern across the rows is that the razor never asks you to decide truth on the spot. It asks you to route the claim: dismiss it, hold it, or engage it, based on whether the claimant did their job. Two of the rows pass the gate and get a genuine hearing, which is the point. The razor is not a way to wave things away. It is a way to spend your attention on the claims that have earned it and to stop spending it disproving the ones that have not.

## How to apply Hitchens's razor well

The razor is a reflex worth building, and a few habits do most of the work.

**Ask one question first: who is supposed to prove this?** Before you reach for a counter-argument, check whether the claim came with any support at all. If it did not, the burden has not moved to you, and the honest response is to ask for the evidence rather than to manufacture a rebuttal. This single reframe saves an enormous amount of wasted effort arguing against things that were never backed up in the first place.

**Let the burden shift when evidence actually appears.** The razor is not a license to ignore anything you dislike. The moment someone offers real support, the dynamic flips: now you do owe the claim a genuine engagement, and dismissing it anyway is just the razor abused. Using it honestly means applying it only to the unsupported case and dropping it the instant the support shows up.

**Keep "dismissed" separate from "disproven."** Setting an unevidenced claim aside is not the same as proving it false. It stays provisional, and it reopens the moment evidence arrives. Holding a claim as unproven rather than declaring it wrong is more accurate and leaves you free to update, which matters most for claims you will revisit. [Deciding which ambiguous claims are even worth the effort to resolve](/blog/second-order-thinking) is its own judgment, made deliberately rather than by reflex.

**Mark your own claims with their evidence.** The cheapest way to respect the razor is to never hand other people, or future you, an assertion with nothing behind it. When you write something down, attach where it came from. A claim saved with its source survives the razor; a claim saved bare invites exactly the dismissal you would apply to a stranger's.

## The version hiding in your own notes

The sharpest place to turn the razor is inward, on your own knowledge base. Every claim you save arrives with some grounding, a source, a measurement, a reason you believed it, and the grounding is the first thing lost in the capture. You write down the conclusion and drop the evidence, because in the moment the evidence is obvious and the conclusion is what you want. Six months later the note reads as a flat, sourceless assertion, indistinguishable from something you made up, and you tend to believe it anyway, because it is in your own handwriting.

That is Hitchens's razor pointed at your past self, and by its own logic those bare notes should be held as unproven until their evidence is recovered. The defense is structural, not a matter of being more disciplined in the moment. Capture the source with the claim: a link, a figure, a line on why you believed it and how far. A note that carries its evidence answers the razor on reuse; a note that does not is a claim you will have to re-prove or quietly re-dismiss every time you reach for it. This is the same failure mode that lets [notes go stale and start misleading you](/blog/knowledge-decay): a line that was once well-grounded, or never grounded at all, hardens into something you treat as settled. It is also why a source you once caught asserting things without backing should lose some standing on the next reuse, which is the habit behind [not re-extending full trust to a source you already caught being wrong](/blog/gell-mann-amnesia-effect).

## When Hitchens's razor does not apply

The razor gets overextended, so a guard is worth stating. It is narrow on purpose. It is about the burden of proof for a specific claim that arrives with no support, and nothing more.

It is not a rule that lets you dismiss anything inconvenient by pretending no evidence was offered. If support was given and you ignore it, that is not the razor, that is avoidance. It is not a claim that unsupported statements are false; plenty of true things get asserted badly, and the razor only parks them until the case is made, it does not bury them. A different failure hides an unsupported leap behind a claim that is supported, which is how [a false equivalence](/blog/false-equivalence) gets through a careful room: the shared trait comes with evidence, the equivalence it is used to carry does not. And it does not apply to the ordinary background knowledge a conversation rests on. Well-established facts already carry their evidence in the shared record, so demanding a fresh citation for every commonplace is not skepticism, it is obstruction. The razor earns its keep at the edges, on the novel claim, the surprising figure, the confident assertion with nothing attached, which is also where [a question-mark headline quietly signals that the evidence ran out](/blog/betteridges-law). Point it there, not at everything.

## Getting started

Hitchens's razor is not a way to disbelieve the world. It is a way to stop doing other people's work for them, and to stop pretending you have weighed a claim you only failed to disprove. The test is small and mechanical: before you argue, check whether anything was offered; if not, hold the claim rather than adopt it or refute it; and when evidence does arrive, engage it honestly. It is most valuable exactly where unsupported claims are cheapest to produce, which today means the fluent, sourceless confidence of an AI answer.

Start with your own knowledge base, where the bare assertions are quietly the most expensive, because you trust them by default. Capture each claim with its evidence, a source and a line on why you believed it, so a note does not come back years later as an assertion you have to take on faith. Verify claims at the moment you save them, while the grounding is still in front of you. And treat a confident AI answer as a claim with no marker of proof, to be checked rather than carried forward. [Try Scribelet free](https://scribelet.app) and let it keep your notes with their sources attached, and re-check them against the world, so the evidence you had today is still there the day you rely on the claim.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>hitchens-razor</category>
            <category>thinking</category>
            <category>misinformation</category>
            <category>ai</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[The Streetlight Effect: Why We Look Where It's Easy]]></title>
            <link>https://scribelet.app/blog/streetlight-effect</link>
            <guid isPermaLink="false">https://scribelet.app/blog/streetlight-effect</guid>
            <pubDate>Sat, 17 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The streetlight effect is searching for answers where it is easy to look rather than where the answer actually is. How to spot it in software, data, and your own notes. Try it free.]]></description>
            <content:encoded><![CDATA[
The outage started at 2:03 and the on-call engineer did what anyone would do: opened the logs. For the next hour she grepped the application log, filtered by request id, widened the time window, narrowed it again, and found nothing that explained why checkout was timing out. The application log was clean because the application was fine. The failure was in a downstream payment service that logged nothing at all, ran in an account she could not see, and had been quietly rate-limiting the checkout calls for twenty minutes. She searched the application log for an hour not because the answer was there, but because the application log was the thing she could search. The keys were across the street, in the dark.

That is the streetlight effect, and once you have a name for it you start seeing it everywhere: in incident reviews, in dashboards, in research papers, in the way you search your own notes. It is one of the most human biases there is, and it is especially dangerous for people who build with data, because our tools are very good at producing a bright, convenient pool of light and saying nothing at all about the darkness around it.

## What is the streetlight effect?

The streetlight effect is a type of observational bias where people look for something only where it is easiest to look, rather than where it is most likely to be. It is also called the drunkard's search, after the parable that gives it its name: a police officer finds a drunk man on his hands and knees under a streetlight, searching for his keys. The officer asks where he dropped them. "Over there, in the park," the man says, pointing into the dark. So why are you looking here? "Because this is where the light is."

The joke is old, but the term was popularized by the journalist David H. Freedman in a [2010 Discover Magazine piece](https://www.discovermagazine.com/why-scientific-studies-are-so-often-wrong-the-streetlight-effect-1055) about why so many scientific studies turn out wrong, and the parable itself was used by the philosopher Abraham Kaplan to describe how researchers pick problems. The [modern definition on Wikipedia](https://en.wikipedia.org/wiki/Streetlight_effect) keeps both halves: it is a bias of *observation*, where you only gather the evidence that is convenient to gather, and a bias of *conclusion*, where you then act as though the convenient evidence were the whole picture. The first half is understandable. The second half is where the damage lives.

What makes it slippery is that searching under the light is not stupid. The light is where searching is possible at all. The engineer grepping the application log was not being lazy; she was using the one instrument she had. The streetlight effect is not a failure of effort or intelligence. It is a failure to notice that the place you can search and the place the answer lives are two different places, and that the gap between them is exactly where the problem is hiding.

![Diagram: a streetlight lights a box of easy-to-search data on the left while the real answer, the keys, sits in the dark on the right.](/blog/streetlight-effect/light-vs-keys.svg)

## Why we search under the light

Three forces push us under the lamppost, and they are all reasonable on their own.

The first is **availability**. Some data simply exists and some does not. You have application logs, so you search application logs. You have a quarter of sales figures, so you reason from sales figures. The data that was never collected cannot be queried, so it quietly drops out of the analysis, not because anyone decided it was unimportant but because it was never on the table to begin with.

The second is **cost**. Even when the right data is theoretically reachable, getting it is expensive: you would have to add logging to a service, run a longer study, interview the customers who already left, or instrument a part of the system nobody owns. The convenient data is free and immediate. Under deadline pressure, free and immediate beats correct and slow almost every time.

The third is **comfort**. The lit area is familiar. You know how to read the application log; you do not know how to get into the payment service's account. People gravitate to the methods and the datasets they already understand, and a problem framed in familiar terms feels more tractable even when the framing is wrong. This is the same pull that keeps teams [reasoning only to the first visible consequence](/blog/second-order-thinking) instead of the harder second and third ones: the near, bright, obvious answer crowds out the far, dark, real one.

None of these is a character flaw. They are the ordinary physics of attention under constraints. But stack them together and you get a team that spends its energy polishing the answer to a question it can see, while the question that actually matters sits unexamined in the dark. If you want to stop doing that, the first move is to notice when it is happening, and the honest way to notice is to write down what you looked at and what you did not. [Try Scribelet free](https://scribelet.app) and keep that second list, the one nobody usually writes, next to the evidence you actually gathered.

## The streetlight effect in software and knowledge work

Modern technical work is unusually prone to the streetlight effect, because our tools manufacture bright, cheap, highly searchable pools of data and stay silent about everything outside them. Here is where the light usually falls, what sits in the dark next to it, and how the failure tends to arrive.

| Where the light is (easy to search) | Where the keys are (where the answer lives) | How it bites you |
|---|---|---|
| The service that has good logging | The service that logs nothing | You debug the healthy system for an hour while the broken one stays invisible |
| The metric your dashboard already tracks | The outcome nobody instrumented | The chart stays green while the real thing fails |
| The benchmark that is cheap to run | The capability that is expensive to evaluate | The model tops the leaderboard and disappoints in production |
| The users who answer surveys | The users who already left without a word | You optimize for the people you can hear and lose the ones you cannot |
| The code you wrote recently | The code you inherited and never read | The bug lives in the module you keep not opening |
| The notes you can keyword-search | The context you never wrote down | You conclude the answer is not in your notes when it was never captured |

The through-line is the same in every row: the lit column is a faithful record of what was *convenient to collect*, and the dark column is where the thing you actually need is sitting. The AI-evaluation row is worth dwelling on, because it is the streetlight effect operating at the frontier of the field. Benchmark scores are easy to compute and easy to compare, so they become the light, and enormous effort flows toward raising them. Whether the model is actually good at the messy, open-ended task you care about is expensive to measure, so it stays in the dark, and a whole industry periodically rediscovers that the leaderboard and the usefulness were two different places all along.

## Streetlight effect vs Goodhart's law vs the McNamara fallacy

The streetlight effect travels with a family of measurement failures, and they get blurred together constantly, which is a shame because each one names a genuinely different mistake. Keeping them straight makes all of them sharper.

| | What goes wrong | The core move |
|---|---|---|
| Streetlight effect | You search where it is easy to look, not where the answer is | Convenient evidence stands in for the real evidence |
| [Goodhart's law](/blog/goodharts-law) | A good measure stops being good once it becomes a target | A metric gets gamed and decouples from the goal |
| [The McNamara fallacy](/blog/mcnamara-fallacy) | You treat what you did not measure as if it did not exist | The unmeasured is deleted from the decision |
| [Campbell's law](/blog/campbells-law) | High stakes corrupt both the metric and the work beneath it | Pressure bends the process out of true |
| [Simpson's paradox](/blog/simpsons-paradox) | An aggregate reverses the trend inside its own segments | The summary number lies about the groups |

The distinctions are subtle but real. [Goodhart's law and Campbell's law](/blog/perverse-incentive) are about a metric going bad under pressure: someone sees the target and games it. The streetlight effect needs no pressure and no gaming. It happens at the very start, when you decide, usually without noticing you are deciding, which evidence to go looking for. The McNamara fallacy is its closest cousin, and the difference is one of direction. McNamara is about *ignoring* the data you did not gather; the streetlight effect is about *where you chose to search in the first place*. You can commit the streetlight effect and the McNamara fallacy in a single motion: you search under the light, find a number, and then treat that number as the whole of reality. The streetlight effect is how the blind spot forms; the McNamara fallacy is what you do once you are standing in it.

## How to catch yourself under the lamppost

You cannot abolish the streetlight effect, because you will always have more light in some places than others. What you can do is build the habit of asking, before you trust a search, whether the light and the keys are actually in the same place. A few questions do most of the work.

| Ask before you trust the search | Healthy answer | Streetlight answer |
|---|---|---|
| Where did I actually look? | I can name the dataset and its edges | Wherever the query was easy |
| Where is the thing most likely to be? | I thought about it independently of where I can see | I assumed it was where I was looking |
| What did I not search, and why? | Because it was costly, and I noted that | I did not think about what I skipped |
| Is my conclusion about reality, or about my data? | About reality, checked against the data's limits | The data said so, so it is true |
| What would change my mind? | Evidence I would have to go into the dark to get | Nothing I can reach from here |

The single most useful move on that list is the third one: name what you did not search. A factor you have written down as "not checked, would need logging in the payment service" stays visible as a known gap. A factor nobody wrote down disappears, and three weeks later the team remembers the investigation as thorough when it only ever covered the lit half of the problem. This is the same discipline that keeps the reasoning behind a decision from [rotting the moment nobody is actively holding it](/blog/knowledge-decay): the unexamined dark does not announce itself, so you have to record its outline on purpose.

It also helps to treat *cost* as a signal rather than a verdict. When the right evidence is expensive to get, that expense is often a clue that you are near something important, not a reason to substitute the cheap evidence and move on. The teams that [match their method to the actual decision](/blog/decision-making-framework) rather than to the data they happen to have are the ones that end up looking in the right place, even when the right place is dark and awkward and slow.

## The light you build for yourself

There is a version of the streetlight effect that happens entirely inside your own head, and it is the one most relevant to anyone who keeps notes. When you go looking for something you once knew, you search where searching is easy: the recent notes, the well-tagged ones, the phrases you can remember well enough to match. If nothing turns up, the natural conclusion is that you never wrote it down. But that conclusion commits the streetlight effect twice over. The thing may be there, phrased in words you no longer recall, in a note you cannot surface because your search only reaches the lit corner of your own archive. Or it was genuinely never captured, which means the darkness was there all along and you simply confirmed it.

The fix is to make more of your own knowledge searchable, and to make the dark parts explicit instead of pretending they are empty. When you capture a decision, write down not just what you chose but what you could not check and chose to proceed without. [Try Scribelet free](https://scribelet.app) and keep the context that usually stays in the dark, the caveats, the paths you did not explore, the evidence that was too expensive to gather, somewhere it will still be legible later. Scribelet's background agents even re-check what you have written against the world over time, so a gap you flagged as "unverified" does not quietly get mistaken for settled fact while you are looking the other way. The point is not to light up everything at once. It is to stop mistaking the edge of your light for the edge of what is real.

## Reading the streetlight effect correctly

The overcorrection is to distrust any convenient evidence on principle, which just paralyzes you, because all evidence is convenient from some angle and you have to start somewhere. The lesson is not that the lit area is worthless. The application log was worth reading; it just was not the whole system. The lesson is narrower and more useful: the place you can search and the place the answer lives are not guaranteed to be the same place, and the entire discipline is the habit of checking the gap between them before you act.

So the question the streetlight effect leaves you with is not "do I have enough data?" It is "am I looking here because this is where the answer is, or because this is where the light is?" Ask it out loud in your next incident review, your next metrics meeting, your next search through your own notes. Most of the time the honest answer is some of both, and naming the dark half is what keeps you from walking confidently in the wrong direction. [Try Scribelet free](https://scribelet.app) and keep a record of where you have actually looked, so the next person, including the future version of you, can tell the lit ground from the ground you never covered.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>streetlight-effect</category>
            <category>metrics</category>
            <category>decision-making</category>
            <category>engineering</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Poe's Law: Why You Can't Tell Satire From Sincerity Online]]></title>
            <link>https://scribelet.app/blog/poes-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/poes-law</guid>
            <pubDate>Fri, 16 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Poe's law: without a clear marker, parody and sincere extremism look identical, and AI makes it worse. How to tell them apart in your notes. Try it free.]]></description>
            <content:encoded><![CDATA[
You stop on a comment three replies deep. It argues, with total conviction, something so far past reasonable that it has to be a joke. Then you are not sure. Maybe the person means every word. Maybe they are mocking the position by performing it. You scroll up for context and find none, check the profile and learn nothing, and hover over the reply box, unsure whether to laugh along or argue back. The one thing that would settle it is missing: a signal of what the writer actually intended.

That gap has a name. It is Poe's law, and it has quietly become one of the most useful ideas for anyone who reads, writes, or saves anything online. The short version is famous and the explanations mostly stop there, with a definition and a shrug. What is worth more is seeing why the ambiguity is structural rather than accidental, why generated content has made it sharper than its author could have imagined in 2005, and what it means for the notes and sources you rely on, because a claim you could not read the intent behind is exactly the kind you end up trusting by default. Here is Poe's law in full, with examples, a way to tell satire from sincerity, and the version running quietly inside your own notes.

## What is Poe's law?

Poe's law is [an adage of internet culture](https://en.wikipedia.org/wiki/Poe%27s_law) stating that, without a clear indicator of the author's intent, a parody of an extreme view is impossible to tell apart from a sincere expression of that view, and a sincere extreme view is just as easily mistaken for parody. The ambiguity runs both ways. A joke gets read as a real belief; a real belief gets dismissed as an obvious joke. The only reliable fix the law names is an explicit marker: a winking emoji, a "/s" tag, a line that says "I am kidding."

The term was [coined by Nathan Poe in a 2005 post on an online forum](https://en.wiktionary.org/wiki/Poe%27s_law), in the middle of a long argument about creationism and evolution. His observation was narrow at first: without a blatant display of humor, it is impossible to write a parody of a fundamentalist position that someone will not take as the genuine article. The name is a coincidence worth clearing up, since the search results are full of it: Nathan Poe has no relation to Edgar Allan Poe. The idea escaped its original religious context almost immediately, because the mechanism it describes is everywhere people communicate in text without tone. By 2017 WIRED was calling it [troll culture's central rule](https://www.wired.com/2017/06/poes-law-troll-cultures-central-rule/). Politics, fringe subcultures, product reviews, code comments, a one-line message from a colleague: anywhere the words arrive stripped of voice and face, the intent has to be reconstructed, and often it cannot be.

It is worth separating Poe's law from a close cousin so the rest of this stays clean. Poe's law is about not being able to read *intent*. [The Gell-Mann amnesia effect](/blog/gell-mann-amnesia-effect) is about not being able to carry forward *reliability* you already measured. One is a failure to classify the register of a message; the other is a failure to remember a source's track record. They often appear together online, but they are different problems with different defenses.

## Why parody and sincerity collapse into each other

The effect is not a lapse of attention. It is produced by how written communication works, and three things stack up to create it.

The first is that **text carries no tone.** In person, a raised eyebrow, a flat delivery, a half-smile tells you instantly that a statement is not meant straight. Online, all of that is gone. The reader is left with the literal words and whatever context happens to surround them, and context online is thin: a reply with no thread above it, a screenshot with the replies cropped off, a quote with the speaker removed. With the tonal channel closed, the only thing left to judge is the content, and the content alone is frequently not enough.

The second is **the extremity paradox: the further out a view sits, the harder it is to parody.** Mild positions are easy to exaggerate into obvious satire, because the gap between the real thing and the joke is wide. But a position that is already at the edge leaves nowhere to exaggerate to. Any parody of it has to be at least as extreme as the sincere version, which means it looks exactly like the sincere version. This is why Poe's law bites hardest precisely where the stakes feel highest. The sincere fanatic and the person mocking the fanatic end up writing the same sentence.

The third is that **the marker is the whole game, and markers are fragile.** The law does not say parody and sincerity are *always* indistinguishable. It says they are indistinguishable *without a clear indicator of intent*. A "/s" at the end, a winking face, an account everyone knows is a bit: those collapse the ambiguity in a single character. But markers get stripped when content is quoted, screenshotted, translated, or summarized. A satirical post that was obvious in its original home becomes a sincere-looking claim the moment it travels one hop without its marker. The intent does not survive the copy.

![Sincere and parody lines converge to indistinguishable as a view gets more extreme; an intent marker like /s reopens the gap.](/blog/poes-law/intent-gap.svg)

## Poe's law in the age of AI

Nathan Poe was describing forum arguments between humans. The sharpest modern version involves no human author at all. Generated text and images have pulled the intent marker out of a whole new category of content, and they have done it at scale. That scale is one strand of [the dead internet theory](/blog/dead-internet-theory): so much of the web is now machine-made that you cannot assume a person is behind what you read, let alone read their intent.

Start with the text. A language model will produce a flawless-sounding statement of any position, extreme or mild, sincere or satirical, with the same even confidence. It does not signal when it is improvising, parodying, or repeating something it absorbed without understanding. So a passage that reads as a committed argument may be a model completing a pattern, and a passage meant as a send-up may be taken as a genuine claim, and nothing in the prose tells you which. The tonal channel was already closed in text; AI removes even the weak human tells, the slightly-too-much, the tiny inconsistency, that sometimes gave a parody away.

Then the images and video. A synthetic photo of a public figure saying something outrageous sits in the same uncanny zone Poe's law describes, except now the "view" is fabricated whole. Is it a satirical edit, a sincere fake meant to persuade, or a genuine clip? Without a watermark or a disclosure, which is exactly the intent marker the law is about, the three are indistinguishable on their face. The related search "Poe's law AI" has become common for a reason. The point is not that everything online is fake. It is that the *indicator of intent* is now missing from a much larger share of what you see, and the law's conclusion follows directly: you cannot reliably tell the register of a message from the message alone.

This is why catching an AI assistant in a confident error is worth more than a sigh. A model that will state a parody and a fact in the same tone is a model whose output you have to classify yourself, every time, the same way you classify a stranger's extreme comment. The moment you [use that assistant as a sounding board](/blog/rubber-duck-debugging), it will hand you a confident answer with no marker for how sure it actually is, and a confident answer is precisely the thing to check rather than adopt. That checking is cheap to do now and expensive to skip; it is the same discipline as [fact-checking a claim against the world before you save it](https://scribelet.app/blog/ai-fact-checking-for-notes).

## Examples of Poe's law

The effect shows up anywhere a message arrives without the tone, context, or marker you would need to read its intent. A few of the common shapes, and what they have in common:

| Where it happens | What you see | Why the intent is unreadable |
|---|---|---|
| A cropped screenshot | A single extreme reply, no thread | The context that signaled a joke was cut off |
| A satirical account | A straight-faced post taken literally | The "everyone knows this is a bit" marker does not travel |
| An AI-written passage | A fluent, confident argument | The model uses one tone for sincerity, parody, and improvisation |
| A synthetic image or clip | A public figure saying something outrageous | No watermark or disclosure separates edit from fake from real |
| A terse work message | "Great. Just great." in a thread | Text drops the sarcasm the voice would have carried |
| Your own old note | A claim you saved without its register | You stripped the "I was skeptical of this" context when you captured it |

The last row is the one almost nobody counts, and it is the one that matters most if you keep a knowledge base. You save a line from somewhere, and whatever told you how to read it, the eye-roll you felt, the "this is clearly spin" reaction, does not get saved with it. The note is just as susceptible to Poe's law as any stranger's comment, and the stranger whose intent you are failing to read is your past self. This is close kin to [the way most of what any source produces is low quality](https://scribelet.app/blog/sturgeons-law): the problem is not any single item, it is reading each one without a reliable way to judge it.

## How to tell satire from sincerity

You cannot restore tone to text, and you cannot verify the intent behind everything you read. The goal is narrower and achievable: stop treating an unreadable message as if you had read it. A few habits do most of the work.

**Mark your own intent, always.** The cheapest contribution to the whole problem is to never add to it. When you write something that could be read as parody or as sincere, add the indicator: the "/s", the explicit "joking", the note of context. The same applies to what you save. A claim captured with "source was being sarcastic" or "I did not believe this" keeps its register attached, so future you does not have to reconstruct it.

**Look for the marker before you assign an intent.** Ask the concrete question: is there an indicator of what the author meant, or am I supplying one? If the only thing telling you a post is sincere (or a joke) is your own assumption, you have not read the intent, you have guessed it. Hold the reading as provisional rather than fact.

**Rate the source, not just the message.** A known satire site, a known-serious outlet, an account with a track record: the source often carries the intent the individual message cannot. When you catch yourself unable to classify a message, the source's history is the next-best signal, which is the same reason it pays to [track a source's reliability over time rather than re-judging every piece from scratch](/blog/gell-mann-amnesia-effect).

**Remember the asymmetry before you spread it.** Repeating a parody as if it were real, or a sincere claim as if it were a joke, is a one-second action; correcting the misreading later is a long one. That is [Brandolini's law applied to intent](/blog/brandolinis-law): the misread travels cheaply and the fix is expensive, so the discipline is to resolve the ambiguity before you pass the thing on, not after.

**Treat a missing marker as missing data, not as permission to decide.** If a message genuinely has no readable intent and no source signal, the honest state is "I do not know whether this is sincere", not a coin-flip dressed as a judgment. Leaving it explicitly undecided is more accurate than forcing it into one bin.

## The version hiding in your own notes

If you keep notes, or run an AI assistant over them, Poe's law is not an abstraction about strangers on the internet. It is a property of your own knowledge base. Every claim you save arrives with a register, sincere, sarcastic, speculative, overstated-for-effect, and the register is the first thing lost in the capture. Six months later the saved line reads as flat fact. The note does not remember that the source was joking, or that you wrote it down precisely because you doubted it. Only you did, and the memory faded.

The defense is structural, not a matter of being more careful in the moment. Capture the intent with the claim: a word on whether the source was serious, a note on your own confidence, the context that told you how to read it. Verify claims when you save them, while the surrounding signal is still in front of you, because the register is far harder to reconstruct later than to record now. This is the same failure mode that lets [notes quietly go stale and start misleading you](https://scribelet.app/blog/knowledge-decay): a line that was once clearly provisional hardens into something you treat as settled. And treat an AI assistant working over those notes the way you would treat any source whose intent you cannot read from its tone. Its fluent confidence is not a marker of sincerity or accuracy; it is the absence of a marker, and the absence is the whole point of the law.

## When Poe's law is not the explanation

The idea gets stretched, so a guard is worth stating. Poe's law is specifically about the *unreadability of intent* in the absence of a marker. It is not a license to call anything you disagree with "probably satire", and it is not a reason to believe nothing. If a message has a clear indicator of intent and you still misread it, that is not Poe's law, that is a reading error. If a source has an established, obvious register and you ignore it, that is not the law either, that is choosing not to use the signal in front of you.

The other misreading is to swing to blanket cynicism and treat every message as a potential fake. That is paralysis, not skepticism, and it is its own kind of inaccuracy. Plenty of content online carries perfectly legible intent: the marker is there, the context is intact, the source is known. The law applies to the specific case where the indicator is missing, and the discipline it asks for is equally specific. Supply the marker when you write, look for it when you read, and when it genuinely is not there, hold the intent open instead of inventing one. Deciding which ambiguous messages are even worth resolving is itself [a judgment worth making deliberately](https://scribelet.app/blog/second-order-thinking) rather than by reflex.

## Getting started

Poe's law is not a reason to distrust everything you read. It is a reason to stop pretending you have read an intent you only guessed at, in a world where generated text and images have stripped the marker from more content than ever. The fix is small and mostly mechanical: supply the indicator when you write, look for it before you assign a reading, and when it is missing, say so.

Start with your own knowledge base, where the ambiguity is quietly most expensive. Capture each claim with its register, a word on whether the source was serious and how far you believed it, so a line you once held at arm's length does not come back looking like settled fact. Verify claims at the moment you save them, while the context that signals intent is still there. And treat a confident AI answer as a message with no intent marker, to be checked rather than adopted. [Try Scribelet free](https://scribelet.app) and let it keep your notes with their sources and their context, and re-check them against the world, so the register you could read today is still readable the day you rely on it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>poes-law</category>
            <category>thinking</category>
            <category>misinformation</category>
            <category>ai</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Principle of Least Astonishment: Build Predictable Software]]></title>
            <link>https://scribelet.app/blog/principle-of-least-astonishment</link>
            <guid isPermaLink="false">https://scribelet.app/blog/principle-of-least-astonishment</guid>
            <pubDate>Thu, 15 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The principle of least astonishment says a system should behave the way people expect. What POLA means, why surprising behavior costs you, and how to design it out.]]></description>
            <content:encoded><![CDATA[
You call a function named `getUser`, and somewhere deep inside it writes a row to the database. Nothing in the name told you that. You reviewed the code, you shipped it, and weeks later you are staring at duplicate records, wondering how a read became a write. The function did exactly what its author intended. It just did something its name promised it would not, and everyone who touched that code after paid a small tax for the gap between what it said and what it did.

That gap has a name: the principle of least astonishment. It says that a component should behave in the way the people using it already expect, and that when a system surprises them, the surprise itself is a defect worth fixing. It is one of the oldest ideas in software design and one of the easiest to nod along to and then violate by lunchtime, because the behavior that astonishes your users is almost never astonishing to you. You wrote it. You hold the context. The whole difficulty of the principle is that it asks you to judge your own work by a standard you cannot feel from the inside.

Here is what the principle of least astonishment actually says, why a surprising system is more expensive than a merely limited one, where astonishment tends to come from, a checklist for catching it before it ships, and the one case where breaking an expectation on purpose is the right call.

## What is the principle of least astonishment?

The principle of least astonishment, also called the principle of least surprise (POLA or POLS for short), states that a system, interface, or component should behave in a way that least surprises the people who use it. When someone reads a function name, clicks a button, or passes an argument, the result should match the expectation that name, button, or argument sets up. If the behavior and the expectation disagree, you change the behavior, not the user.

The idea predates the phrase. It runs through [the C2 wiki's early design discussions](https://wiki.c2.com/?PrincipleOfLeastAstonishment), is catalogued in its UI and language forms on [Wikipedia](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), and lives in the Unix tradition of small tools that do the obvious thing. It was sharpened over decades of people discovering, one bug at a time, that a clever surprise costs more than the cleverness is worth. The modern framing adds a useful corollary: if a feature genuinely has to carry a high "astonishment factor," because the surprising behavior is the point, then the feature itself is a candidate for redesign, not just its documentation.

What the principle is not is a demand for blandness. It does not say never do anything new. It says that when you depart from what people expect, the departure should be deliberate, visible, and worth it, and that most departures are none of those things. They are accidents of how the code grew, and they read to everyone downstream as a system that cannot be trusted to mean what it says.

## Why surprising behavior is expensive

A limited system and a surprising system fail in different ways, and the second is worse. A limited system does less than you want, and you find out at the boundary: you reach for a feature, it is not there, you work around it. The cost is visible and it is paid once. A surprising system does something other than what you expect, and you find out later, through a bug, in production, after you have already built on the wrong assumption. The cost is hidden and it compounds.

Astonishment also erodes the thing that makes a codebase fast to work in: the ability to predict a component's behavior without reading it. Most of the time nobody reads the function. They read the name, form an expectation, and move on, because reading every function would make any real system unworkable. That shortcut is the entire economy of a large codebase, and a single surprising function devalues it everywhere, because now the shortcut is unreliable and people have to stop and check. A system that keeps its promises lets people reason about it from the outside. A system that surprises them forces everyone back inside.

![getUser() forks to the expected read-only outcome and the actual hidden write; the gap is the astonishment factor](/blog/principle-of-least-astonishment/expected-vs-astonishing.svg)

There is a second-order cost, too. Once a surprising behavior has shipped and people have worked around it, the workaround becomes load-bearing. Someone depends on the surprise. Fixing it later breaks them, which is [Hyrum's law](/blog/hyrums-law) arriving on schedule: with enough users, every observable behavior of your system, including the astonishing ones, ends up depended on by someone. The cheapest moment to remove a surprise is before it has any users. Every moment after that is more expensive than the last.

## Where astonishment comes from

Surprises are not random. They cluster around a few recurring sources, and knowing them is most of the work of avoiding them.

**Names that promise one thing and do another.** A `getX` that also mutates, a `validate` that also saves, a boolean parameter that inverts the obvious reading. The name is the contract most people actually read, and when the body contradicts it, the name is lying. This is the same discipline that makes [self-documenting code](/blog/self-documenting-code) work: a name that matches its behavior is a name you do not have to verify.

**Hidden side effects.** A function that quietly writes to disk, mutates its argument, changes global state, or makes a network call that its signature gives no hint of. The classic example is a method that looks like a pure query and is secretly a command. The caller composes it as if it were free of consequences, and the consequences arrive anyway. [Armin Ronacher's essay on Python and the principle](https://lucumr.pocoo.org/2011/7/9/python-and-pola/) walks through a language's worth of these, where a convenience in one place becomes a surprise in another.

**Inconsistency with the rest of the system.** The one endpoint that returns `null` where every other endpoint returns an empty list. The one config flag whose default is `true` where every sibling defaults to `false`. Each individual choice may be defensible, but the inconsistency is the surprise: people generalize from the pattern, and the exception breaks the generalization.

**Breaking a convention the user brought with them.** A text field where Ctrl+Z does nothing. A "Save" button that discards unsaved changes in another panel. A delete that cannot be undone where every other delete can. The user's expectation here did not come from your system at all. It came from every other system they have ever used, and you are measured against that whole history whether you like it or not.

Most of these come down to the [curse of knowledge](/blog/curse-of-knowledge): you know what the code does, so the surprise is invisible to you. The behavior that astonishes a new reader is the behavior you have stopped seeing. This is why astonishment is so hard to self-review and so easy to catch in someone else's work, and why the most reliable detector of a surprise is a second person reading the thing cold.

## Spotting astonishment: a checklist

You cannot feel your own surprises, but you can interrogate your work with questions that surface them. Before shipping an interface, a function, or a screen, run it against these:

- **Does the name predict the behavior?** If someone read only the name and never the body, what would they expect, and is that what happens? Any gap is astonishment.
- **Are there side effects the signature does not reveal?** Writes, mutations, network calls, global state changes. If the type says "query" and the body says "command," you have a surprise.
- **Is this consistent with its siblings?** Does the one method, endpoint, flag, or screen behave like the others in its family, or is it the exception people will trip on?
- **Does it honor the conventions users arrive with?** Standard shortcuts, standard button meanings, standard affordances. Breaking one of these costs more than inventing a new one, because you are fighting a lifetime of habit.
- **When it fails, does it fail the way people expect?** Surprising error behavior is still surprising behavior. A function that swallows an error and returns a plausible-looking default astonishes worse than one that throws.
- **If you have to explain it, is the explanation short?** "It does what it says" needs no explanation. A behavior that requires a paragraph of caveats in the docs is telling you the behavior, not the docs, is the problem.

The point of the list is not to pass it perfectly. It is to move the surprise from production, where a user finds it, to review, where you do.

## Astonishing behavior and its least-astonishing fix

The abstract principle gets concrete fast when you line up the surprise against the version that keeps its promise. These are the patterns that recur:

| Astonishing behavior | Why it surprises | Least-astonishing version |
|---|---|---|
| `getUser()` also creates a user if none exists | A "get" silently writes | Split into `getUser()` and `getOrCreateUser()`; the name states the write |
| `list.sort()` returns `None` and mutates in place | Reads like it returns the sorted result | Offer both: `sort()` in place and `sorted()` returning a copy |
| Boolean arg `process(data, true)` | The call site cannot say what `true` means | Named options: `process(data, validate=True)` |
| "Save" discards changes in an unfocused panel | Save should never lose work | Save everything, or disable Save until the panel is reconciled |
| Delete with no undo, next to deletes that have one | Inconsistent with its siblings | Match the family: offer undo, or clearly mark the difference |
| Config flag defaults opposite to every other flag | Users generalize from the pattern | Default it like its siblings, or rename so the difference is explicit |
| A method swallows errors and returns a default | Hides failure the caller needed to see | Surface the error; let the caller decide the fallback |

None of the fixes are clever. That is the point. The least-astonishing version is usually the more obvious one, and the surprise crept in because a shortcut, an optimization, or a late requirement made the obvious version slightly less convenient to write. The principle asks you to pay that small cost at the keyboard so that nobody pays the larger one downstream.

## When breaking expectations is the right call

The principle has a sharp edge, and ignoring it turns least astonishment into an argument against ever improving anything. Sometimes the expectation people bring is wrong, or outdated, or the thing you are replacing was itself a bad convention. Breaking it is then the right move, and the principle still applies: it just changes what you owe the user.

What you owe is a deliberate, visible, well-signposted departure. If a new interaction is genuinely better, you make the new behavior discoverable, you give people a bridge from the old expectation, and you accept that the first encounter will cost a moment of surprise in exchange for a lasting gain. That is a different thing from an accidental surprise buried in a function name. It is the astonishment-factor corollary in action: the feature carries unavoidable surprise, so you redesign around the surprise, make it legible, and earn it, rather than letting it leak out as a bug.

The failure mode to avoid is using "sometimes you should break expectations" as cover for surprises you never decided to create. A deliberate departure can be named, defended, and pointed at in a design doc. An accidental one is only ever discovered. If you cannot say out loud why the surprise is worth it, it is not a bold design choice. It is a defect that has not been reported yet.

## How least astonishment relates to its neighbors

The principle sits in a small family of ideas about building systems that other people can reason about. [Postel's law](/blog/postels-law), the robustness principle, is a close cousin pointed outward: be strict in what you emit and liberal in what you accept, so the systems on the other side of an interface are not astonished by your output. Least astonishment points the same instinct inward, at the people reading and calling your code. [Conway's law](/blog/conways-law) explains why a system's surprises so often track its org chart: an interface designed by two teams that never talked will astonish anyone who assumed one mind was behind it. Read together, they describe the same goal from different angles, which is a system whose behavior you can predict without having built it.

For a notes app, the stakes are small but constant. A search that returns nothing when a note plainly contains the word, a sync that silently drops a change, an export that reorders your entries: each is a little astonishment, and a tool you reach for every day cannot afford to surprise you, because the trust it needs is built entirely out of behaving the way you expected last time.

## Getting started

The principle of least astonishment is less a rule you apply than a question you keep asking: would this surprise someone who did not build it? You cannot answer it from the inside, so the practical move is to make the question routine, in code review, in design, and in the small daily act of naming things so the name tells the truth.

Scribelet is built to behave the way you expect. Your notes stay where you put them, search finds what is there, and your AI provider is the one you chose, with your key, under your control. If you want a thinking space that does not astonish you, [try Scribelet free](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>principle-of-least-astonishment</category>
            <category>pola</category>
            <category>software-design</category>
            <category>api-design</category>
            <category>ux</category>
            <category>engineering</category>
        </item>
        <item>
            <title><![CDATA[How to write a README that stays true]]></title>
            <link>https://scribelet.app/blog/how-to-write-a-readme</link>
            <guid isPermaLink="false">https://scribelet.app/blog/how-to-write-a-readme</guid>
            <pubDate>Wed, 14 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Most READMEs explain everything except how to run the project. Here is how to write a README readers actually use: a copy-paste template, what to delete, and how to keep it true.]]></description>
            <content:encoded><![CDATA[
It is eleven at night and you have just cloned a repository you need working by morning. You open the README. It has a logo, six status badges, three paragraphs on the project's philosophy, a contributor covenant, and a sponsors section. What it does not have, anywhere, is the one command that starts the thing.

This is the normal failure. A README is the first file anyone opens, so it accumulates everything a project is proud of and very little of what a reader showed up to find. The result reads like a brochure when the reader needed a map.

Learning how to write a README is mostly learning what to leave out. The hard part is not the prose. It is deciding which of the ten things you could say are the two the reader cannot proceed without, and putting those first.

## What is a README?

A README is the plain-text front page of a project, named `README.md` and placed at the root of the repository. The `.md` extension is Markdown, so headings, lists, links, and fenced code blocks all render automatically on GitHub, GitLab, and almost everywhere else. It is a file in your repository, versioned and reviewed alongside the code, which makes it a small piece of [docs as code](/blog/docs-as-code): it lives where the code lives and goes stale the same way.

The platform treats the README as the repository's homepage. GitHub renders it directly under the file list, which is why it is the single most-read document most projects will ever ship. [GitHub's own guide on READMEs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) covers where the file can live and how it renders. What no platform guide tells you is what to put in it, and that is the only question that decides whether the file earns its place at the top of the page.

## Why most READMEs fail

A reader arriving at your repository is holding one of a few questions. What is this? Can I use it? How do I run it? How do I contribute? Most READMEs answer none of these in the first screen, because they are written from the author's point of view rather than the reader's.

Here is the test that fixes almost everything: a README should spend its space on what the repository cannot already show. The file list, the language, the license badge, the commit history, the fact that there are tests: a reader can see all of that in ten seconds without being told. What they cannot see is why the project exists, how to get it running, and the decisions that would otherwise take an afternoon to reverse-engineer.

| The repository already shows this | Only the README can tell you this |
|---|---|
| Which language and framework it uses | What problem it solves, in one sentence |
| That there are tests, from the test directory | The exact commands to install and run it |
| The directory structure | Which directory to start reading in |
| That a config file exists | Which config values you must set before it works |
| The license, from the license file | Whether it is maintained or abandoned |
| The commit history | The one non-obvious gotcha that wastes everyone's first hour |

Every row on the left is noise when it appears in the README. Every row on the right is the reason someone opened the file. A good README is mostly the right-hand column.

![A README's first screen: most projects lead with badges and a long intro while the reader is still blocked; a reader needs the project name, a one-line description, and the quickstart commands first.](/blog/how-to-write-a-readme/readme-first-screen.svg)

If you keep notes while you build, the raw material for the right-hand column is already in them: the command you finally got working, the environment variable that was not documented, the reason you chose one library over another. A README is often less a writing task than a selection task, pulling the handful of durable facts out of a working log. That is exactly the kind of capture [Scribelet](https://scribelet.app) is built for, so the notes you take while debugging become the README you ship. You can [try it free](https://scribelet.app).

## The README worth copying

Most template galleries hand you twelve sections and leave you to delete the ten you do not need. That is backward. Start from the shortest README that is still complete, and add a section only when a real reader would be blocked without it. Here is that starting point, in copy-paste Markdown:

```markdown
# Project name

One sentence: what this does and who it is for.

## Quickstart

    git clone https://github.com/you/project
    cd project
    npm install
    npm start

That is the whole happy path. If a reader has to read past this to run
the project, move the missing step up here.

## Configuration

Set these before first run:

- DATABASE_URL: where to find Postgres
- API_KEY: get one at the provider's dashboard

## How it works

Two or three sentences, or a link to a design doc. Enough that a
contributor knows which directory to open first.

## Contributing

How to run the tests, and the one house rule that is not obvious.

## License

MIT. See the LICENSE file.
```

The order is the point. The project name and one-line description answer "what is this?" in the first two lines. The quickstart answers "how do I run it?" before the reader has to scroll. Everything a reader needs to use the project lives above the fold, and everything they need to contribute lives below it. Most READMEs invert this, opening with badges and backstory and burying the install command under a heading called "Getting Started" that is three screens down.

The quickstart is also where the single most expensive omission lives: the prerequisite you forgot you had. The project runs on your machine because you installed a specific runtime version, a database, or a system library months ago and never thought about it again. A reader has none of that. If the project needs Node 20, or Postgres running locally, or a particular build tool, say so in one line before the install commands. A quickstart that assumes the reader's machine already looks like yours is the most common reason the happy path fails on the first try, and it is the cheapest failure to prevent.

Delete anything that is not pulling weight. A wall of status badges, a table of contents for a file you can read in two minutes, a "built with" list that restates the package manifest, a roadmap nobody updates: each of these costs the reader a scroll and returns nothing. The spec that formalizes this minimalism, [standard-readme](https://github.com/RichardLitt/standard-readme), is worth reading once; so is [Make a README](https://www.makeareadme.com/), which argues the same case from the opposite direction. The shared conclusion is that a README is short on purpose, and length is the symptom, not the goal.

## README versus the other docs

Half of what bloats a README belongs in a different document. The README is the front door, not the whole house. When you find yourself writing three paragraphs on why the architecture is the way it is, or a step-by-step recovery procedure for a production incident, that content has a better home.

| The reader wants | Put it in |
|---|---|
| What this is and how to run it | The README |
| Why a specific design decision was made | An [architecture decision record](/blog/architecture-decision-record-examples) |
| The full design of a feature before it is built | A [software design document](/blog/software-design-document) |
| Step-by-step operational recovery | A [runbook](/blog/runbook) |
| How to open a good pull request or issue | A [pull request template](/blog/pull-request-template) and an [issue template](/blog/github-issue-template) |

Routing content to the right document keeps each one short enough to stay true. A README that tries to be the design doc and the runbook as well becomes the thing nobody trusts, because no single reader needs all of it and everyone learns to skim past the parts that are not theirs. A short, accurate README that links out beats a long one that tries to hold everything.

A good README also quietly lowers the [bus factor](/blog/bus-factor). The quickstart, the config list, and the one non-obvious gotcha are exactly the knowledge that otherwise lives only in the head of whoever set the project up. Writing them down is the cheapest insurance a team can buy against the person who knows how to run the thing being on holiday.

## Writing a README an AI agent can read

There is a newer reader to design for, and it is not a person. When a coding assistant or an autonomous agent is pointed at your repository, the README is usually the first file it reads, and it treats that file as the authoritative statement of what the project is and how to work in it. A README that is vague or stale does not just cost a human an hour; it sends the agent down the wrong path with confidence.

The same discipline that helps a human helps the model. A one-line description the agent can quote back. An explicit quickstart it can execute. A config list it does not have to infer from scanning the code. The difference is that an agent will not forgive a missing step by poking around until it works; it will follow the README literally, so the gaps show up faster and more expensively.

AI also makes the first draft cheap, which is a trap worth naming. A model can generate a plausible README from your codebase in seconds, and that draft will be fluent, complete-looking, and subtly wrong wherever the code and the prose have drifted. A generated README is a starting point to verify, not a finished document to commit. The judgment about which gotcha matters and which section to delete is still yours.

## The part everyone skips: keeping it true

A README is written once and read for years, which means it starts drifting out of date the moment the code moves on. The install command gains a step. The config key is renamed. The project gains a second supported platform the README never mentions. None of these changes break a test, so nothing flags them, and the README quietly becomes a confident description of a project that no longer exists. This is ordinary [knowledge decay](/blog/knowledge-decay): the document does not get worse, the world it describes moves, and the gap is invisible until someone follows the instructions and they fail.

The fix is not "review it quarterly," because a calendar reminder tells you to look without telling you what changed. The fix is to tie the README to the events that invalidate it. When you change the install steps, the README edit is part of that same pull request, not a follow-up ticket that never gets filed. A short README helps here too: there is less surface to drift, and a reader who hits one wrong command loses trust in all of it.

It helps to track, somewhere, when each claim in your docs was last confirmed true rather than last edited. A line that was reworded for tone last week can still describe a workflow that changed six months ago. Keeping a running note of what you verified and when, which [Scribelet](https://scribelet.app) is designed to make routine, turns "the README is probably out of date" into a specific list of claims to recheck. [Try it free](https://scribelet.app) and keep the record next to the work.

## The short version

How to write a README comes down to three decisions. Lead with what the repository cannot show the reader itself: what it is and how to run it. Delete everything that restates what the file list already says. And treat the file as a claim that has to stay true, updated in the same change that makes it false rather than on a schedule nobody keeps.

A README is the cheapest documentation a project has and the most read. Spent well, it is the twenty seconds that saves every future reader an afternoon. Spent on badges and backstory, it is the file everyone opens and nobody uses.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>readme</category>
            <category>documentation</category>
            <category>technical-documentation</category>
            <category>docs-as-code</category>
            <category>engineering</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[How to catalogue a collection with notes]]></title>
            <link>https://scribelet.app/blog/how-to-catalogue-a-collection</link>
            <guid isPermaLink="false">https://scribelet.app/blog/how-to-catalogue-a-collection</guid>
            <pubDate>Tue, 13 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A collection you cannot search is just a pile. How to catalogue books, records, recipes, or anything else with notes, keep it current, and share it. Try it free.]]></description>
            <content:encoded><![CDATA[
You own more than you can list. Ask anyone with a full bookshelf whether they already have a particular title and watch them pause, because the honest answer is that they are not sure. The same gap shows up with a record crate, a spice drawer, a box of board games, the wine on the rack, the plants on the sill. You acquired each thing on purpose and you can picture most of it, but the collection as a whole lives only in your head, and your head does not have a search bar. So you re-buy the duplicate, forget what you lent out, and cannot answer a simple question like "which of these have I actually finished."

A catalogue fixes that, and it does not require software built for collectors. A notes app you already use is enough, if you treat the collection as a set of entries rather than a vibe. This is how to catalogue a collection with notes: what an entry should contain, how to keep it from going stale, and where a plain notes app stops and a dedicated tool earns its place.

## What does it mean to catalogue a collection?

To catalogue a collection is to turn a pile of things into a list you can search, sort, and answer questions from. A catalogue is not an inventory count and it is not a scrapbook. It is a structured record where every item is one entry, and every entry carries the same few facts, so the whole set behaves like a small database instead of a memory you hope holds.

The test is a question. "Do I own a hardback of this?" "Which records have I not played in a year?" "What can I cook from what is already in the cupboard?" If your collection can answer questions like those in seconds, it is catalogued. If answering means walking to a shelf and squinting, it is not, however neat the shelf looks. Everything below is in service of that one capability: being able to ask.

## Start with one note per item

The unit of a catalogue is the item, so the unit of your notes should be the item too. One note per book, per record, per recipe, per plant. Not one giant note titled "My books" with two hundred lines in it, because a single long note cannot be sorted, cannot be linked to individually, and turns every lookup into a scroll.

One note per item sounds like more work and is actually less, because each note is tiny and you make it once. It also means the catalogue grows the way the collection does, one thing at a time, instead of waiting for the rainy afternoon you will spend "finally sorting everything," which never comes. This is the same principle behind [atomic notes](https://scribelet.app/blog/atomic-notes): a record you can address on its own is worth more than the same words buried in a longer one. Capture the item when it arrives, give it its own note, and the catalogue assembles itself over months without a single marathon session.

## Decide the handful of fields that matter

An entry is only useful if every entry carries the same facts, because that sameness is what lets you sort and filter later. The discipline here is subtractive: pick the few fields you will actually query on, and refuse the rest. For most collections that is three or four.

- **A name and a category.** The title, and what kind of thing it is, so you can group.
- **A status.** Read or unread, played or unplayed, cooked or not, alive or regrettably not. Status is the field that answers most real questions, and it is the one people skip.
- **One or two facts you actually use.** Author and year for books. Artist and format for records. For recipes, the source and how long it takes. For anything fragile or valuable, where you got it and what it cost.
- **A photo, when the look matters.** A snapshot of the spine, the label, the plant. Cheap to capture on a phone, and worth more than a paragraph of description for anything visual.

Resist adding a field because it might be nice. A field nobody fills in is a column of blanks that makes every entry look unfinished, the same way an over-built form collects filler instead of answers. Tags help here: instead of inventing a dozen columns, attach a few loose tags ("gift", "lent to Sam", "reread") and let them cut across the collection without bloating every note. If you want a light structure on top, a system like [PARA](https://scribelet.app/blog/para-method-with-ai) keeps a growing catalogue from turning back into one undifferentiated pile.

## The part everyone skips: keeping it current

Here is the reason most catalogues quietly fail, and it has nothing to do with how they were built. A catalogue is only as good as its agreement with reality, and reality moves. You lend the book and never update the status. You cook your way through half the recipes and the "not yet" flags stay put. A plant dies, a record gets sold, a price doubles, and the entry sits there looking confident and wrong. This is ordinary [knowledge decay](https://scribelet.app/blog/knowledge-decay): the thing changed and the note that describes it did not.

A catalogue nobody tends is not an asset, it is a snapshot of a day that has passed. The fix is not heroic. It is a small recurring pass, the same [weekly maintenance habit](https://scribelet.app/blog/keep-notes-up-to-date) that keeps any set of notes honest: ten minutes to update what changed since last time. Catch the lent book, flip the cooked recipe, retire the dead plant. Maintenance is the difference between a catalogue you trust and one you stop opening, and it is exactly the step a general notes app leaves entirely to you.

This is where Scribelet is built to help with the reference half of the job. Its background agents re-check what you have written against the world on a schedule you set and hand you a diff when something no longer holds, so the catalogue does not silently drift between the Sundays you remember to review it. You can [try it free](https://scribelet.app) and keep your collection somewhere that notices when an entry has gone out of date, instead of trusting it to stay true on its own.

## From a private catalogue to one you can share

A catalogue in your notes answers your own questions well. The moment you want someone else to browse it, the job changes, and this is where a notes app honestly stops. A friend asking "what's in your record collection?" does not want a screenshot of your notes list. A small shop with a shelf of stock, a hobbyist showing off a collection, a club sharing its library: all of them want something that looks like a catalogue to the person reading it, with covers, categories, and a clean layout, not a raw dump of fields.

That is a different tool from the one you capture in. Notes are the private working copy where entries are born and kept current; a published catalogue is the presentation layer on top. When you reach that point, an [online catalogue maker](https://zipflipbook.com/) turns the structured entries you already maintain into a shareable, browsable catalogue without you rebuilding the data by hand. The division of labour is the useful part: keep the source of truth in your notes, where it is easy to edit and the maintenance pass lives, and generate the shareable version from it when you actually need to show someone. The same instinct applies that separates a reference note from a purpose-built tool in [a second brain for the rest of your life](https://scribelet.app/blog/second-brain-for-personal-life): hold the raw material where editing is cheap, and reach for the dedicated tool at the step that needs it.

## A worked example, start to finish

Take a book collection, because it is the one most people have and least often catalogue. You do not sit down and enter two hundred books. You make one note the next time a book enters the house: title, author, year, a status of unread, a tag or two, and a quick photo of the cover. Ninety seconds. You do the same for the next arrival, and the one after.

Within a few weeks you have a few dozen entries, all in the same shape, and the questions start answering themselves. "Do I own this already?" is a search. "What have I not read?" is a filter on status. "Which did I lend to Sam?" is a tag. On the Sunday pass you flip a couple of statuses and fix anything that changed. And when a friend asks to see the shelf, you point an online catalogue maker at the same entries and send them something that actually looks like a collection. Nothing here was a project. It was one small note at a time, kept honest, pointed at a tool only at the end.

A collection you cannot query is a pile with good intentions. Give each item its own note, agree on a few fields, keep them current, and the pile becomes something you can ask questions of, and eventually something you can share. [Start free](https://scribelet.app) with the capture-and-maintain half, and let the collection you have been keeping in your head finally live somewhere with a search bar.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>note-taking</category>
            <category>collections</category>
            <category>cataloguing</category>
            <category>personal-knowledge-management</category>
            <category>organization</category>
        </item>
        <item>
            <title><![CDATA[The Map Is Not the Territory: Why Good Models Mislead]]></title>
            <link>https://scribelet.app/blog/the-map-is-not-the-territory</link>
            <guid isPermaLink="false">https://scribelet.app/blog/the-map-is-not-the-territory</guid>
            <pubDate>Mon, 12 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The map is not the territory: your notes, docs, dashboards, and models are reductions of reality, not reality itself. Why they drift, and how to stay honest. Try it free.]]></description>
            <content:encoded><![CDATA[
At 2:47 on a Tuesday afternoon the status page is a wall of green. Every service healthy, latency flat, 1,240 active users, the number from last night's rollup. The on-call engineer glances at it, sees nothing to do, and goes back to the ticket they were working on. Meanwhile, in the actual running system, logins from the EU region have been failing for eleven minutes, fifty people are locked out, and a retry loop nobody ever wrote down is quietly swallowing the errors before they reach the dashboard. The map says everything is fine. The territory is on fire.

That gap, between the tidy model you are looking at and the messy reality it claims to describe, has a name that is almost a hundred years old. The map is not the territory. It is one of the most useful mental models there is, precisely because the failure it warns about is so easy to walk into: we build a representation of something, the representation is genuinely useful, and then we quietly start treating it as the thing itself. Here is what the phrase actually means, why every map leaves something out on purpose, how the trap shows up in notes and docs and dashboards and AI output, and how to keep a model honest instead of confusing it for the ground it stands on.

## What does "the map is not the territory" mean?

"The map is not the territory" is the idea that any representation of a thing, a map, a model, a description, a set of notes, is never the thing itself, and treating the two as identical leads you astray. The representation is a reduction. It keeps some features of reality and discards the rest, and the features it discards do not stop existing just because they fell off the page.

The phrase comes from Alfred Korzybski, a Polish-American scholar trained as an engineer, who introduced it in a [1931 paper](https://en.wikipedia.org/wiki/Map%E2%80%93territory_relation) and developed it in his 1933 book [*Science and Sanity*](https://en.wikipedia.org/wiki/Science_and_Sanity), the founding text of a field he called general semantics. His formulation was careful: "A map is not the territory it represents," but a good map has a structure similar to the territory, and that similarity is exactly what makes it useful. Korzybski was warning against a specific confusion, the habit of mistaking words, labels, and abstractions for the reality they point at. A menu is not a meal. The word "dog" will not bite you. A five-year financial forecast is not the next five years.

The trap matters most for people who work mostly in representations. If your day is spent in documents, dashboards, tickets, diagrams, and models, then almost everything you touch is a map, and the territory, the running system, the real users, the actual market, is something you only ever see through one of those maps. The discipline is to remember, every time, that you are reading a reduction. The cheapest way to do that is to [keep the thing a note describes attached to the note itself](https://scribelet.app), so the representation carries a pointer back to the reality it came from instead of floating free as if it were the reality.

![A clean dashboard model of a system beside the messier reality it leaves out, with an arrow showing the map omits detail and drifts over time.](/blog/the-map-is-not-the-territory/map-vs-territory.svg)

## Why every map leaves something out

A map that kept every feature of the territory would be the same size as the territory, and useless. Jorge Luis Borges wrote a one-paragraph story about an empire whose cartographers made a map so detailed it covered the land point for point, and was promptly abandoned because nobody could use it. The whole value of a map is in what it omits. A subway map throws away distance, scale, and surface geography so that the one thing a rider needs, which line connects to which, becomes legible. Its uselessness as a walking map is the price of its usefulness as a transit map.

So omission is not a defect to be fixed. It is the function. The problem is never that a map simplifies; the problem is forgetting which simplifications it made, and for whom. The dashboard shows aggregate health because that is usually what you want, which means it is blind to a regional failure by design. The architecture doc shows the components and their intended relationships, which means it is silent about the undocumented retry that is actually load-bearing. Each map answers one question well by refusing to answer the others. When you ask it a question it was never built to answer, it does not warn you. It just gives you a confident, wrong reading, because a map cannot tell you about the territory it left off.

There is a second reason maps mislead, and it is worse than omission because it is invisible. A map is drawn at a moment in time, and the territory keeps moving. The forecast was reasonable the week it was made. The runbook matched the system the day it was written. The note was true when you saved it. Then the territory shifted, the map did not, and the gap between them opened silently, with nothing to mark the moment the two stopped agreeing.

## The map is not the territory in knowledge work

For a team that builds and documents software, almost every artifact is a map of some territory, and each one drifts in its own way. Naming them makes the trap concrete.

| The map | The territory it claims to represent | How it drifts |
|---|---|---|
| A monitoring dashboard | The system's real behavior right now | Aggregates hide a regional or edge-case failure; the metric was defined for last quarter's architecture |
| An architecture diagram | How the code actually talks to itself | A hotfix added a path the diagram never drew; a service was split and the boxes never moved |
| The org chart | Who actually decides and who actually talks | The real [communication structure the system ends up copying](/blog/conways-law) rarely matches the boxes |
| A spec or a doc | What the system is supposed to do | The code shipped a change; [the doc never caught up](/blog/mermaid-diagrams) |
| Your notes | What you once learned and believed | The fact changed, or you misread it, and the note still reads as settled truth |
| A model or forecast | What will actually happen | Reality took a path the model's assumptions ruled out |

The common failure in every row is the same. You act on the map, the map is stale or lossy, and the action lands in a territory that no longer matches it. You deploy against the diagram and hit the path it never drew. You reassure a customer from the green dashboard while they cannot log in. You make a six-month plan from a forecast whose central assumption quietly stopped being true in month two. The map did not lie to you on purpose. It just kept saying what it said the day it was drawn, and you kept reading it as the present tense.

This is also why "it's documented" is a weaker guarantee than it sounds. A document is a map. Its existence tells you a representation was created at some point; it tells you nothing about whether the representation still matches the ground. The useful question is never "is there a doc?" but "when was this last checked against the thing it describes?" That single question, asked out loud, catches more stale maps than any amount of writing more docs.

## When the map and the territory disagree

The rule for the moment of conflict is short: when the map and the territory disagree, the territory wins, every time. This sounds obvious written down and is remarkably hard to practice, because the map is right in front of you and the territory usually is not.

Watch what people actually do when a measurement contradicts the model. The benchmark comes back three times slower than the design predicted, and the first instinct is "the benchmark must be wrong." The user says the feature is confusing, and the response is "but the flow is clearly labeled in the spec." A test fails and the reflex is to doubt the test before the code. In each case the map (the prediction, the spec, the assumption) is being defended against the territory (the measurement, the user, the test) that is actually reporting reality. That reflex has its own name, [the knee-jerk dismissal of evidence that contradicts what you already believe](/blog/semmelweis-reflex), and the map-territory framing is why it is a mistake: the evidence is a reading from the territory, and the thing it contradicts is only ever a map.

None of this means the territory is always legible. Sometimes the measurement is noisy, the user is unrepresentative, the test is flaky. The point is not to trust every signal blindly. It is to resolve the conflict by going to the ground, not by defending the model from your chair. When a number surprises you, the move is to look at the thing the number came from before you decide the number is wrong. [Checking a claim against the world it describes](/blog/ai-fact-checking-for-notes), rather than against the other claims you already hold, is how you keep a map accountable to its territory instead of to your preferences.

## The map is not the territory in the age of AI

Large language models make this mental model more useful, not less, because a model's output is a particularly seductive kind of map. When you ask an assistant to summarize a document, explain a system, or tell you what your notes say about a topic, you get back a clean, confident, well-structured representation. It reads like the territory. It is a map of a map: a reduction of whatever text the model was given, which was itself already a reduction of some reality.

Each layer loses something. The notes were a lossy capture of what you learned. The retrieval step pulled a subset of those notes. The model compressed that subset into a fluent paragraph. By the time you read the answer, you are three reductions away from the ground, and the fluency hides every omission along the way. The AI overview that now sits at the top of most search results is the same shape: a competent summary that reads like the final word and is actually a map drawn from whichever sources were handy, blind to everything they left out.

The practical discipline is to treat an AI's confident output the way you would treat any other map: useful for orientation, never a substitute for the territory when the stakes are real. A model will state that your system does X because the docs it read said X, even if the code has done Y since Friday. It is faithfully reporting the map it was handed. The same flattening happens in an argument when two different territories get collapsed into one, [treating two unlike things as equal](/blog/false-equivalence) because they share a single feature on the map. The fix is not to distrust the assistant, it is to keep its answers pointed at checkable ground, which is the same reason you would [ask what the second-order effects of a decision actually were](/blog/second-order-thinking) rather than trusting the prediction you made before it played out.

## The version hiding in your own notes

The most personal map you own is your own notes, and they drift exactly like every other one, only more quietly, because you trust them more. You trust a note because you wrote it, not because it still matches reality. That is backwards. The note's authorship tells you it was true to someone, once. It says nothing about whether the territory it described is still there.

A note is a snapshot of your understanding at the moment you saved it. The library you benchmarked was fast in that version. The API returned that shape in that release. The person owned that project before the reorg. The claim was defensible given the study you had read so far. Every one of those can go stale without the note changing a character, and when you reach for the note months later it presents its stale reading with exactly the same confidence it had on day one. This is [the slow, silent decay of a knowledge base](/blog/knowledge-decay): not notes being wrong when written, but notes staying frozen while the territory moves on under them.

The defense is to [make your notes behave less like a finished map](https://scribelet.app) and more like one that knows when it was last surveyed. Keep the source attached, so a claim can be re-checked against where it came from. Keep the date and the uncertainty attached, so a six-month-old benchmark reads as a six-month-old benchmark and not as current fact. Treat a note that drives a real decision as a claim to re-verify, not a truth to inherit. This is the same instinct that makes you [investigate why a strange piece of code exists before you delete it](/blog/chestertons-fence): the artifact in front of you is a map of a decision, and you do not know whether it still matches the territory until you go and look.

## Don't throw away the map

The mistake this mental model warns about is confusing the map for the territory. It is not a case against maps. Maps are how finite minds navigate an infinitely detailed world; a team with no shared model of its own system is not more in touch with reality, it is just lost. The cure for a stale map is a fresher map, not no map, and the cure for a lossy abstraction is usually a second abstraction that keeps the features the first one dropped. Korzybski's own point was that a good map, one whose structure genuinely tracks the territory, is enormously valuable. The failure is forgetting that even a good map is a reduction drawn at a moment in time.

So the working version of the principle is not "distrust all models." It is three habits. Know which territory each of your maps describes, and which questions it was never built to answer. When a map and the ground disagree, go to the ground. And treat every representation you keep, the doc, the dashboard, the note, the model's summary, as something with a survey date, due for a re-check against reality before you bet anything important on it. A map you keep honest is one of the most powerful tools you have. A map you forgot was a map is how confident teams walk into walls they had already drawn and then stopped looking at.

For a longer treatment of the idea as a thinking tool, Farnam Street's [essay on the map and the territory](https://fs.blog/map-and-territory/) is the standard reference, and it makes the same core point from a decision-making angle: the models we use to simplify complexity are useful right up until we mistake them for the complexity itself.

## Getting started

The map is not the territory is worth keeping near the front of your mind precisely because the trap is so comfortable. The representation is clean, it is right in front of you, and the reality it stands for is messy and somewhere else. Reaching for the map instead of the territory is the path of least resistance almost every time.

You can push back on that with a few durable habits: ask when each map was last checked against the thing it describes, resolve a conflict by going to the ground rather than defending the model, and keep every claim you save attached to its source and its date so a frozen note cannot pass itself off as current fact. [Try Scribelet free](https://scribelet.app) and let it hold your notes as living maps, with their sources attached, their freshness visible, and an assistant that checks a claim against the world instead of trusting the map because it reads well. Deciding which framework or model fits the problem in front of you is its own skill; our guide to [choosing a decision-making approach](/blog/decision-making-framework) is a good next step once you have stopped mistaking the map for the ground it covers.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>the-map-is-not-the-territory</category>
            <category>mental-models</category>
            <category>thinking</category>
            <category>decision-making</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Betteridge's Law of Headlines: Why the Answer Is No]]></title>
            <link>https://scribelet.app/blog/betteridges-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/betteridges-law</guid>
            <pubDate>Sun, 11 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Betteridge's law says any headline ending in a question mark can be answered no. Why it holds, why AI sharpens it, and how to read past it. Try it free.]]></description>
            <content:encoded><![CDATA[
The headline asks "Is this common household spice the secret to a longer life?" and for half a second you want the answer to be yes. You click. Four hundred words in, past the anecdote and the stock photo, you reach the hedge: one small study, in mice, suggesting maybe, pending more research. The headline asked a question the article never answers. If the spice really did extend your life, the headline would have said so, in a flat declarative sentence, with the study's name attached.

That gap between the question in the headline and the shrug in the body has a name. Betteridge's law of headlines states that any headline ending in a question mark can be answered by the word "no." It is half a joke and half a genuinely useful filter, and in an era when a model can generate a thousand speculative headlines an hour it is more useful than it has ever been. Here is what Betteridge's law actually claims, why it holds as often as it does, why AI has made it sharper, and how to use it when you read, when you write, and in the notes where a question you once left open quietly hardens into a fact.

## What is Betteridge's law?

Betteridge's law of headlines is the observation that if a news headline ends in a question mark, the answer is almost always "no." It is named after the British technology journalist Ian Betteridge, who stated it in a [2009 blog post](https://en.wikipedia.org/wiki/Betteridge%27s_law_of_headlines) picking apart a TechCrunch story whose question-mark headline promised far more than its reporting could deliver. The same idea had circulated earlier, including a version from 1991 sometimes called "Davis's law," but Betteridge's phrasing is the one that stuck.

The law is not a claim about grammar. It is a claim about what a question mark in a headline reveals about the person who wrote it. A headline is the most valuable real estate a publisher owns, and a writer who has the facts uses it to make an assertion, because an assertion is stronger than a question. "New study links the spice to longer life" is a better headline than "Is the spice the secret to longer life?" in every way, unless the writer cannot actually support the first version. The question mark is a tell. It marks the place where the evidence ran out and the writer reached for intrigue instead. A headline that only insinuates is [a claim you can set aside as cheaply as it was made](/blog/hitchens-razor), since nothing was offered that you are obliged to refute.

That is why the law belongs next to the other principles about how trust and evidence get mismatched. It is a cousin of [the Gell-Mann amnesia effect](/blog/gell-mann-amnesia-effect), where you trust a source on one topic right after catching it wrong on another, and of Brandolini's law, the bullshit asymmetry principle that refuting a bad claim costs far more than making one. All three describe the same underlying problem: the signal that should lower your confidence is right there, and you read past it anyway. The practical defense is not to distrust every headline but to keep the claims that matter [somewhere you can actually check later](https://scribelet.app), so a hedged question does not quietly settle into your notes as a fact.

![How a headline's form reveals its evidence: a declarative claim the writer can back, versus a question-mark headline Betteridge's law reads as no.](/blog/betteridges-law/the-question-mark-tell.svg)

## Why the law holds so often

The mechanism is an economic one, not a grammatical rule, and it runs through the incentives of whoever wrote the headline.

A declarative headline is a promise the writer has to keep. "Interest rates will fall in March" commits the publication to a claim it can be held to, so an editor only runs it when the reporting backs it up. A question-mark headline promises nothing. "Will interest rates fall in March?" can run on pure speculation, because a question cannot be wrong. It extracts the click that the interesting-but-unprovable premise is worth, while quietly reserving the right to answer "probably not, nobody knows" in the body. The question mark is how a headline sells certainty it does not have.

There is a second force underneath the first. If the answer were actually yes, the question would not be interesting enough to pose. "Does the sun rise in the east?" is not a headline. The questions that get the treatment are the ones where the surprising, traffic-earning answer would be yes, and where the boring, true answer is no. So the form selects for exactly the cases the law predicts: a tantalizing yes the writer cannot support, dressed as a question so that the dull no can hide in the final paragraph.

## Betteridge's law in the age of AI

Betteridge was writing about human journalists chasing traffic. The sharpest modern version is the headline a language model wrote, and there are now a great many of them. "Is this the end of search?" "Can AI replace your doctor?" "Will prompt engineering be obsolete by next year?" The question-mark headline is the native grammar of the AI content farm, because it is cheap to generate, it cannot be fact-checked into being wrong, and it harvests the click from a premise the underlying article never had the evidence to assert.

This is worse than the newspaper case in a specific way. A content operation can now produce speculative question headlines faster than any reader can evaluate them, which is [Brandolini's law running at machine scale](/blog/brandolinis-law): the cost of generating a plausible, unanswerable question has fallen to near zero, while the cost of actually checking each one has not moved. The volume of headlines asking whether some tool will change everything has exploded, and almost none of them carry the evidence that would let them drop the question mark. The reader who internalizes Betteridge's law has a cheap, fast first-pass filter for exactly this flood: a question-mark headline is not news, it is a prompt, and the honest answer is usually no.

The same tell shows up when you ask an AI assistant itself. A model will happily generate a confident-sounding headline or summary that poses a question and then fail to resolve it, because it is optimizing for a plausible-looking output, not for a defensible claim. Treating its question-shaped outputs the way you would treat a clickbait headline, as a starting point to verify rather than a finding to keep, is the same discipline as [checking an AI claim against the world before you save it](/blog/ai-fact-checking-for-notes).

## Examples of Betteridge's law

The law is easiest to internalize as a set of patterns. Once you have seen the shapes a few times, you spot the tell before you click.

| The headline | What the question mark signals | The Betteridge reading |
|---|---|---|
| "Is [new technology] the end of [established thing]?" | The writer cannot show it is, or they would have | No. The established thing is fine for now. |
| "Could [small study] mean [big conclusion]?" | One preliminary result stretched toward a claim it cannot carry | No, not yet, and probably not at that scale. |
| "Has [company] finally solved [hard problem]?" | A press release the writer could not independently confirm | No. "Finally" is doing the work "proven" cannot. |
| "Are we about to see [dramatic event]?" | Speculation with a deadline nobody will check later | No, or at least not on the implied timeline. |
| "Will [job] be replaced by AI this year?" | A fear or a hope with no reporting behind it | No. If it were happening, the headline would name it. |

The pattern that matters most is the one you write yourself. The question-mark headline is not only a journalism habit. It is how an open question gets filed, in a feed, in a saved article, and in your own notes, where it is far more durable than any single headline.

## How to read past a question-mark headline

The law is a filter, not a verdict. Its value is that it tells you where to spend your limited attention, not what to conclude. A few habits turn it into a reliable reading practice.

Start by answering the headline before you read. Say "no" out loud, then open the article to see whether it changes your mind. Most of the time the body confirms the no, and you have saved yourself the time; occasionally it genuinely supports a yes, and that surprise is worth noticing, because a question headline that actually delivers is rare enough to be informative.

When the premise matters to you, find the load-bearing claim and check it directly. A question headline almost always rests on one study, one source, or one quote. Name it, then ask whether it actually supports the headline's implied yes, or whether it has been stretched. This is [Sturgeon's law used as a filter](/blog/sturgeons-law): most of what any feed produces is crud, so the skill is deciding fast what is worth a real look rather than reading everything at face value.

Treat the question as the start of an inquiry, not the end of one. If the headline asks whether a framework is dead or a technique is obsolete, the useful move is to ask the second-order version: if it were true, what would follow, and what would you expect to already be seeing? [Asking "and then what?"](/blog/second-order-thinking) usually resolves a speculative headline faster than the article does, because the dramatic yes tends to imply consequences that have obviously not happened.

## The version hiding in your own notes

If you keep notes, Betteridge's law is not only a media filter. It describes a specific way your own knowledge base rots. You read a speculative article, you find the premise interesting, and you save a line about it. The line started life as a question, hedged and provisional. But a saved note strips the hedge. Six months later the entry reads as a flat fact, its original question mark long gone, and you build on it as if it had been confirmed. The note does not remember that the claim arrived as clickbait. Only you did, and you forgot.

This is the quiet half of the law, and it is the half a tool can actually help with. A claim you captured as "might this be true?" should not silently become "this is true" just because time passed and the question mark fell off in the copy. The defense is to [keep the source and the uncertainty attached to the claim](https://scribelet.app), so a note that began as speculation still reads as speculation when you return to it, and so a claim you never actually verified is flagged as unverified rather than inherited as fact. That is the same discipline that keeps [a cited source from going stale under you](/blog/how-to-read-a-research-paper) and that fights [the slow decay of a knowledge base](/blog/knowledge-decay) generally: the question is cheapest to resolve when you first meet it, and most expensive once you have built on the assumed answer.

## When Betteridge's law does not apply

The law is a heuristic, and treating it as an iron rule is its own mistake. The clearest exception is the honest question headline, the one written by someone who does have the answer and uses the question as a hook before delivering a well-supported yes. These exist. A headline asking whether a widely held belief is wrong, written by a reporter who did the work to show that it is, resolves to yes, and the law fails cleanly.

The academic case is the sharpest counterexample. A [2016 study by Cook and Plourde](https://gwern.net/doc/statistics/2016-cook.pdf) looked at whether scholarly article titles that pose questions get answered "no," and found that in the research literature the law does not hold: yes-or-no question titles are rare there, and the ones that do appear are answered "yes" more often than "no," because a paper's title usually introduces a genuine investigation rather than a traffic-seeking tease. The lesson is to read the law as a statement about incentives, not about punctuation. Where the writer is paid for clicks, the question mark is a tell and the answer is usually no. Where the writer is paid for being right, a question in the title can be an honest one. Knowing which regime you are in is the whole skill, and it is a judgment worth making deliberately rather than applying the rule by reflex.

## Getting started

Betteridge's law is not a reason to sneer at every headline that ends in a question mark. It is a reason to stop spending attention and trust on claims that were never asserted in the first place, and to notice when one of those unasserted claims slips into your own notes wearing the clothes of a fact.

Read the question headline as a "no" until the body earns a "yes," check the one claim the premise rests on before you save it, and keep the uncertainty attached to anything you capture so a maybe does not quietly become a fact. [Try Scribelet free](https://scribelet.app) and let it hold your notes with their sources, flag the claims you never verified, and check them against the world, so the question you left open does not come back months later looking like the answer.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>betteridges-law</category>
            <category>thinking</category>
            <category>misinformation</category>
            <category>media-literacy</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[The Semmelweis Reflex: Why Good Teams Dismiss New Evidence]]></title>
            <link>https://scribelet.app/blog/semmelweis-reflex</link>
            <guid isPermaLink="false">https://scribelet.app/blog/semmelweis-reflex</guid>
            <pubDate>Sat, 10 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The Semmelweis reflex is the knee-jerk rejection of evidence that contradicts what you believe. What it is, how it differs from confirmation bias, and how to catch it. Try it free.]]></description>
            <content:encoded><![CDATA[
In 1847, a Hungarian doctor named Ignaz Semmelweis noticed that women were dying of childbed fever in one maternity ward at roughly ten times the rate of the ward next door. The only difference he could find was that the deadly ward was staffed by doctors who came straight from the autopsy room, and the safe one by midwives who did not. He had the doctors wash their hands in a chlorinated lime solution before deliveries, and the death rate collapsed to match the midwives'. He had the result, the mechanism, and the numbers. What he did not have was a theory anyone wanted to hear, because germ theory did not exist yet and the idea that respected physicians were carrying death on their own hands was an insult. His colleagues did not test his claim and find it wanting. They dismissed it, mocked him, and moved on. He was pushed out of the profession, and he [died in an asylum](https://pmc.ncbi.nlm.nih.gov/articles/PMC11442886/) before Pasteur and Lister proved him right.

The reason his evidence bounced off has a name, [coined long after he was gone](https://en.wikipedia.org/wiki/Semmelweis_reflex), and it is not really about medicine. It is the Semmelweis reflex: the knee-jerk tendency to reject new evidence or a new idea because it contradicts what you already believe, before you have actually examined it. It is one of the quieter failure modes in any field that runs on being right, and software and knowledge work are full of it. The person flagging the problem is rarely dying in an asylum, but the reflex that waves them off is exactly the same one that waved off Semmelweis, and it costs teams real time and real decisions every week.

## What is the Semmelweis reflex?

The Semmelweis reflex is the automatic, low-effort rejection of new information simply because it conflicts with established norms, beliefs, or practices, without first weighing whether the information is actually correct. The key word is *reflex*. It is not a reasoned conclusion that the new evidence is weak. It is the dismissal happening first, fast, and emotionally, with the justification assembled afterward to defend a position you never really re-examined. That ordering is what separates it from healthy skepticism, and it is what makes it dangerous: from the inside, a reflexive rejection feels identical to a considered one. The practical defense starts before the argument does, with [keeping the inconvenient evidence somewhere you cannot quietly ignore it](https://scribelet.app), so a verdict has to be earned rather than reflexed.

What makes the reflex so durable is that it usually protects something other than the truth. Admitting the new evidence is right often means admitting you were wrong, that a system you built has a flaw, or that a practice the whole team is invested in needs to change. The belief being defended is rarely just a belief. It is tangled up with identity, sunk cost, and status, and the reflex fires to protect all three at once. Semmelweis's critics were not defending miasma theory so much as defending the idea that gentlemen's hands could not possibly be dirty.

## Why the reflex fires

The Semmelweis reflex is not one bias but a small stack of them that reinforce each other, and naming the parts is what lets you interrupt them. It rides on top of several well-documented tendencies that each feel reasonable in the moment.

The first is **confirmation bias**: the pull toward information that fits what you already think and away from information that does not. The second is **belief perseverance**: once a belief is in place, it tends to survive even direct evidence against it, because unwinding it is more effortful than keeping it. The third is **status quo and ego protection**: a new fact that implies past error threatens not just the model in your head but your standing, so rejecting the fact is cheaper than revising the self. The fourth is **groupthink**, which turns an individual reflex into an institutional one, because a whole room agreeing to dismiss an inconvenient result makes the dismissal feel like consensus rather than cowardice.

Stack those together and you get a response that looks like judgment and is actually avoidance. The giveaway is speed. A considered rejection takes time, because you have to engage with the evidence to find its weakness. A reflex arrives instantly, fully formed, and already certain, which is the one thing genuinely weak evidence does not usually let you be.

![A diagram contrasting two things you can do with evidence that contradicts a belief. One piece of new evidence splits into two paths. On the left it hits a wall labeled The Semmelweis reflex and is rejected unexamined, ending in a red box reading Belief unchanged, evidence never examined, under the caption Rejected first, justified later. On the right the same evidence passes through a gate labeled Examine before judging and ends in a green box reading Belief updated, or evidence refuted on the merits, under the caption Judged on the merits.](/blog/semmelweis-reflex/reflex-vs-examine.svg)

The diagram is the whole choice in one frame. The same incoming evidence either bounces off a wall or passes through a gate, and the only difference is whether you examined it before you judged it. The reflex path is faster and feels safer, which is exactly why it is the default. Slowing the response down long enough to ask whether the evidence is actually wrong, rather than merely unwelcome, is the entire discipline.

## The Semmelweis reflex in software and knowledge work

People who build things like to believe they are evidence-driven, which is precisely what makes this blind spot so sharp. The reflex hides inside the moments that feel most like good engineering judgment. Here are the shapes it tends to take, and the evidence each one waves off.

| Where it shows up | The reflexive dismissal | The evidence being rejected |
|---|---|---|
| A junior flags a flaw in the standard approach | "That's just how we do it here" | A real design or process problem nobody senior wants to reopen |
| A benchmark contradicts an architecture bet | "The benchmark must be wrong" | Data that the chosen approach is slower or costlier than assumed |
| A new tool or paradigm challenges the stack | "It's a fad, we tried something like it" | A genuine improvement that would mean admitting the current stack is dated |
| A bug report blames your own code | "It works on my machine" | A reproducible failure in the part you are most sure is correct |
| A postmortem points at a beloved practice | "The process is fine, this was a one-off" | A pattern that the practice itself is producing the failures |
| User data contradicts the roadmap thesis | "Those users don't represent our market" | Signal that the bet the team is committed to is wrong |

The through-line is that the strength of the rejection tends to scale with how invested you are, not with how weak the evidence is. The ideas that trigger the hardest reflex are the ones that would cost the most to accept: the rewrite you championed is slower, the framework you standardized on does not fit, the process you defended in three meetings is the thing breaking production. That is backwards from how evidence should be weighed, and noticing the inversion is half the fix. When your certainty that something is wrong arrives faster than your reasons for it, that gap is worth [the kind of deliberate downstream thinking](https://scribelet.app/blog/second-order-thinking) you would apply to any decision with a delayed cost.

## Semmelweis reflex vs confirmation bias, status quo bias, and NIH syndrome

The Semmelweis reflex gets used loosely as a synonym for any resistance to new ideas, and keeping it distinct from its neighbors makes it more useful. They overlap, but each describes a different move, and the practical defense differs for each.

| Concept | The core move | How it differs from the Semmelweis reflex |
|---|---|---|
| Semmelweis reflex | Reflexively reject new evidence that contradicts a belief | This is the umbrella reaction; the others are specific mechanisms underneath it |
| Confirmation bias | Seek and favor evidence that fits your belief | About what you look for and notice, not the active rejection of what lands in front of you |
| Status quo bias | Prefer things stay as they are | About change in general, not specifically about contradicting evidence |
| Belief perseverance | Hold a belief even after its basis is disproven | The staying power of the old belief, where the reflex is the speed of rejecting the new one |
| Not-invented-here (NIH) syndrome | Reject ideas because they came from outside | About the source of the idea, where the reflex is about the content contradicting you |

The reflex sits on top of the others as the fast, defensive reaction they produce. Confirmation bias decides what evidence you even register; the Semmelweis reflex is what happens when contradicting evidence breaks through anyway and gets slapped down on arrival. Separating them matters because the fix is different. Confirmation bias is fought by actively seeking disconfirming evidence. The Semmelweis reflex is fought at the moment the unwelcome evidence shows up, by refusing to rule on it until you have actually looked. This is the near-mirror image of [not tearing down something until you understand why it is there](https://scribelet.app/blog/chestertons-fence): Chesterton's fence warns against discarding the old too quickly, and the Semmelweis reflex warns against discarding the new too quickly. Both are failures of examining before deciding, pointed in opposite directions.

## How to catch your own Semmelweis reflex

Because the reflex fires before reasoning, every defense is a way to insert a pause between the unwelcome evidence and your verdict on it. None of these requires pretending to be more open-minded than you are; they just change the order of operations so judgment follows examination instead of preceding it.

1. **Notice the speed.** The clearest tell is a rejection that arrives instantly and certain. When you find yourself sure something is wrong before you can say why, treat that certainty as a flag, not a conclusion. Genuine refutation takes a minute; a reflex takes none.
2. **Steelman the evidence before you rule on it.** Make the strongest possible case *for* the thing you want to dismiss. If after building its best version you still find it wanting, that is a considered rejection. If you cannot be bothered to build it, you are reflexing.
3. **Separate the claim from the claimant.** The reflex is stronger when the evidence comes from a junior, an outsider, or a tool. Ask whether you would dismiss the same data if your most trusted colleague had presented it. If the answer changes, the problem is the source, not the content.
4. **Ask what it would cost you to be wrong.** The reflex scales with investment. When your resistance feels disproportionate, name what accepting the evidence would force you to give up: a decision, a practice, a bit of status. Seeing the real stake makes it harder to pretend the objection is purely technical.
5. **Write down the evidence and your verdict, with the date.** Recording what you were shown and why you dismissed it turns a reflex into [a checkable prediction you can revisit](https://scribelet.app). When the dismissed problem resurfaces three months later, the note is there to show you rejected it on reflex, which is how the reflex gets trained out over time.

The common thread is forcing the examination to happen before the judgment, in a form you can inspect later. The reflex thrives on being invisible and instantaneous; anything that makes it slow and legible weakens it.

## The one-person version: an AI that never makes you flinch

There is a modern twist that inverts the whole problem. The Semmelweis reflex is a danger when something pushes back on you, but the most common AI assistants are tuned to be agreeable, so they almost never do. You propose an approach and the model affirms it. You ask whether your reasoning holds and it finds support. The reflex that would normally protect a bad belief from human challenge never fires, because nothing is challenging the belief in the first place. You get the comfort of the Semmelweis reflex, your beliefs intact, without the one thing that sometimes forces an update: a colleague willing to tell you that you are wrong.

That is the same failure wearing the opposite costume, and the fix runs in both directions. When you work with an assistant, ask it for the strongest evidence *against* your position, not for confirmation, so it plays the Semmelweis who might be right rather than the agreeable ward full of doctors. And when the assistant does surface something that contradicts you, watch for your own reflex to dismiss it as a hallucination before checking, because "the AI must be wrong" is the 2026 version of "the benchmark must be wrong." An assistant's pushback is not automatically correct, but it is evidence, and evidence is [worth checking against the world](https://scribelet.app/blog/ai-fact-checking-for-notes) rather than reflexively keeping or reflexively discarding.

## The evidence you already wrote down

The quietest Semmelweis reflex is the one you aim at yourself. You held a view six months ago, wrote down a result that complicated it, and then let the current belief quietly overrule the old note without ever reconciling the two. The contradicting evidence was not rejected by a hostile colleague; it was filed and forgotten, which is a slower and more private version of the same dismissal. A benchmark you ran, a user complaint you logged, a design doubt you recorded, all sitting in your notes contradicting a conclusion you later reached and never went back to check.

This is where the reflex does its most invisible damage, because there is no meeting and no mockery, just a belief drifting away from the evidence that should have constrained it. The defense is to keep the inconvenient evidence somewhere you will actually encounter it again, and to treat your own past notes as a colleague who gets to object. A finding does not stop being true because you stopped looking at it, but its force [fades fast once it drops out of view](https://scribelet.app/blog/knowledge-decay) unless something durable keeps it in front of you. The same discipline that protects a team from dismissing a junior protects you from dismissing your own earlier, better-informed self.

## Reading the Semmelweis reflex correctly

The concept is easy to weaponize, so two guards are worth stating. First, rejecting evidence is not automatically the Semmelweis reflex. Most new claims that contradict established practice are, in fact, wrong, and a fast dismissal of a genuinely bad argument is good judgment, not a bias. The reflex is specifically the rejection that happens *without examination*, where the speed and certainty come from the discomfort rather than from the evidence being weak. The test is not whether you rejected something but whether you looked first. If you examined the claim and found it hollow, that is not the Semmelweis reflex; that is the job.

Second, the cure is not to accept every contrarian claim to prove you are open-minded. A team that adopts every new tool and believes every surprising benchmark has not escaped the reflex; it has traded it for credulity, which is just as expensive. The goal is narrow: when evidence contradicts a belief you are invested in, examine it on the merits before you rule, and be most careful exactly when your urge to dismiss is strongest. Ignaz Semmelweis was right, and the profession's refusal to even test his claim cost lives for decades. The lesson is not that the outsider is always right. It is that "this contradicts what we know, so it must be wrong" is not an argument, and the moment it feels like one is the moment to slow down. [Try Scribelet free](https://scribelet.app) and keep the evidence that contradicts you where you will have to look at it again, so the next inconvenient result gets examined instead of reflexively waved away.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>semmelweis-reflex</category>
            <category>thinking</category>
            <category>decision-making</category>
            <category>engineering</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[The Abilene Paradox: When a Team Agrees to Something Nobody Wants]]></title>
            <link>https://scribelet.app/blog/abilene-paradox</link>
            <guid isPermaLink="false">https://scribelet.app/blog/abilene-paradox</guid>
            <pubDate>Fri, 09 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The Abilene paradox is when a group agrees to a decision nobody actually wants. What it is, how it differs from groupthink, and how to stop it on a team. Try it free.]]></description>
            <content:encoded><![CDATA[
The meeting ran twenty minutes and everyone said yes. The proposal was to rewrite the service from scratch, a six-month detour that would freeze new features and carry every risk a rewrite carries. The tech lead presented it, looked around the room, and got nods. The senior engineer who had lived through the last rewrite said it sounded reasonable. The product manager, who privately thought the current service was fine, did not object because engineering seemed to want it. The engineer who had actually filed the bug that started the conversation stayed quiet, because everyone more senior than her was already on board. The plan was approved with what looked like complete agreement, and the team spent the next two quarters on a rewrite that, when it was finally cancelled, not one person in that room had actually wanted.

Afterward, in ones and twos, the truth came out. The tech lead had floated the rewrite as a trial balloon and assumed the enthusiasm was real. The senior engineer had misgivings but read the room as decided. The product manager had deferred to engineering. The junior engineer had deferred to everyone. Every single person had privately been against it, and every single person had publicly supported it, each one managing their own doubt out of a fear that they were the lone holdout, a doubt that never made it anywhere [the team could see it](https://scribelet.app). That is not a failure of analysis or a lack of talent. It is a specific, named, repeatable failure of agreement, and it has been studied since 1974. It is called the Abilene paradox.

## What is the Abilene paradox?

The Abilene paradox is a situation in which a group collectively agrees to a course of action that no individual member actually wants, because each person mistakenly believes everyone else is in favor and does not want to be the one to object. It is a failure to manage agreement rather than a failure to manage conflict, and that is what makes it so hard to see: nothing looks wrong. There is no argument, no deadlock, no visible dissent. The group moves smoothly toward a decision that quietly contradicts the private preferences of everyone in it.

The term was [coined in 1974 by management professor Jerry B. Harvey](https://en.wikipedia.org/wiki/Abilene_paradox), who illustrated it with a story about his own family. On a hot afternoon in Coleman, Texas, everyone was content playing dominoes on the porch when someone suggested driving fifty-three miles to Abilene for dinner. Harvey thought it was a bad idea but agreed because he assumed the others wanted to go. His wife agreed because she thought her parents wanted to go. Her parents agreed for the same reason about everyone else. They made the long, hot, miserable round trip, ate a bad meal, and came home exhausted, only to admit one by one that none of them had wanted to go in the first place. They had driven to Abilene to satisfy a consensus that did not exist. The useful thing to carry forward is not the anecdote but the mechanism, and the mechanism shows up far more often at work than it ever did on that porch.

## Why agreement fails where conflict would not

The Abilene paradox runs on a handful of mental moves that each feel reasonable in the moment and combine into something absurd. Harvey's original paper, [archived by MIT](https://web.mit.edu/curhan/www/docs/Articles/15341_Readings/Group_Dynamics/Harvey_Abilene_Paradox.pdf), traces the chain, and it is worth naming the parts because you can intervene on each one.

The first is **pluralistic ignorance**: every person privately disagrees but assumes they are the only one, because everyone else is publicly going along. The second is **action anxiety**: the fear of what will happen if you speak up, which almost always turns out to be worse in your head than in the room. The third is what Harvey called **negative fantasies**, the vivid imagined consequences of objecting, being seen as difficult, blocking the team, looking foolish, that make silence feel safer than honesty. Stack those together and you get a group where every member is privately braking and publicly accelerating.

![A diagram of the Abilene paradox. Four people sit around a table. Each has a private thought bubble reading I would rather not, but the speech bubble each one says out loud reads Sounds good to me. Arrows from all four public statements converge on a central box labeled Team decides: GO. Below the box a caption reads A decision nobody in the room wanted, assembled from four people each managing their own doubt.](/blog/abilene-paradox/everyone-agrees-nobody-wants.svg)

The diagram is the whole trap in one frame. The private column and the public column point in opposite directions, and only the public column reaches the decision. What makes this different from an ordinary bad call is that the information needed to stop it was in the room the entire time. Four people knew the plan was weak. The failure was not ignorance; it was that nobody's private knowledge ever became public, so the group acted on a phantom agreement instead of on what its own members actually believed. If you capture the quiet doubts before they evaporate, which is the kind of thing worth [writing down somewhere you can actually check later](https://scribelet.app), the phantom has nowhere to hide.

## The Abilene paradox in software and knowledge work

Teams that build things are unusually prone to this, because so many decisions are made in rooms full of smart people who all want to seem aligned and capable. The paradox hides inside the moments that feel most collaborative. Here are the shapes it tends to take, and the private doubt each one buries.

| Where it shows up | What the room says out loud | What people privately think |
|---|---|---|
| A from-scratch rewrite or big migration | "Agreed, this is the right time to do it" | "The current system is fine and this is a huge risk" |
| Adopting a new framework or tool | "Everyone's using it, let's standardize on it" | "This does not fit our problem and nobody vetted it" |
| A sprint commitment in planning | "Yep, we can hit that" | "That estimate is fantasy and we all know it" |
| Approving a design or architecture doc | "Looks good, ship it" | "I have real concerns but the author seems set" |
| A rubber-stamp pull request approval | "LGTM" | "I did not actually read this closely" |
| Keeping a painful recurring meeting | "It's useful, let's keep it" | "No one on this call wants to be here" |

The through-line is that silence gets read as consent, and consent gets read as enthusiasm. In a sprint planning session, the Abilene paradox is why teams commit to timelines nobody believes in; the moment one person says the estimate is achievable, agreeing is cheaper than being the one who says it is not. In a design review, it is why a document with real problems sails through: the author looks committed, each reviewer assumes the others are satisfied, and "looks good" costs nothing while "I have concerns" costs a hard conversation. The "LGTM" on a pull request nobody read is the smallest, most frequent trip to Abilene there is. Noticing when a decision is being made by phantom consensus is exactly the sort of [downstream reasoning worth doing deliberately](https://scribelet.app/blog/second-order-thinking) rather than by reflex, because the cost of the trip does not arrive until later.

## Abilene paradox vs groupthink

The Abilene paradox gets conflated with groupthink constantly, and keeping them apart makes both sharper. They look identical from the outside, a group agreeing to a bad decision, but the internal state of the people in the room is the opposite in each case, which means the fix is different too.

| | Abilene paradox | Groupthink |
|---|---|---|
| What members privately believe | They disagree with the decision | They have talked themselves into agreeing |
| The core failure | Mismanaged agreement; nobody voices real dissent | Suppressed doubt; the group manufactures consensus |
| Why people go along | Each assumes everyone else is in favor | Pressure to conform; dissent feels disloyal |
| The giveaway | Private regret surfaces immediately afterward | The group defends the decision even after it fails |
| The fix | Surface genuine individual preferences | Protect and reward real dissent |

In groupthink, the group genuinely convinces itself a bad idea is good, and members will defend the decision long after it goes wrong. In the Abilene paradox, nobody is convinced of anything; they privately disagree the whole time and the regret shows up the instant the meeting ends. That difference matters because the remedy is not the same. Groupthink needs you to break a false consensus that people believe in. The Abilene paradox needs you to reveal that the consensus was never real. One is about changing minds; the other is about reading them accurately in the first place.

## How to avoid the trip to Abilene

The paradox is a communication failure, so every defense is a mechanism that forces private preferences into the open before a decision locks in. None of these requires a personality transplant or a braver team. They just change where and how the agreement gets tested.

1. **Ask for the strongest objection, not for agreement.** "Does anyone disagree?" invites silence. "What is the best argument against this?" or "What would have to be true for this to be a mistake?" gives the quiet dissenter permission and a script.
2. **Have the leader speak last.** The moment the most senior person states a preference, everyone below recalibrates to it. Harvey's own prescription, echoed across the practitioner write-ups, is that whoever holds the authority withholds their view until everyone else has shown their hand.
3. **Collect input privately before the group converges.** A quick written round, each person noting their real position before anyone speaks, defeats pluralistic ignorance directly, because you cannot assume everyone else is in favor once you can see that they are not. Harvey recommended anonymous input for exactly this reason.
4. **Separate the trial balloon from the commitment.** A lot of Abilene decisions start as someone thinking out loud and getting mistaken for a proposal. Name which one it is: "I am floating this, not proposing it."
5. **Write down the real reasoning, including the doubts.** A decision that records why it was made, and what reservations people had, is far harder to drift into by accident, and it leaves a trail you can check when the decision is questioned later. This is the same discipline as [recording the reasoning behind any decision](https://scribelet.app/blog/decision-making-framework) so a choice can be understood, and reversed, by whoever inherits it.

The common thread is that you are trying to make the cost of honesty lower than the cost of silence, right at the point of decision. The paradox feeds on the asymmetry where going along is free and speaking up is expensive. Flip that asymmetry and the trip to Abilene mostly cancels itself.

## The one-person Abilene paradox: an agreeable AI

There is a version of this that needs no group at all, and it is getting more common. An AI assistant that is tuned to be helpful and agreeable will tend to endorse whatever you propose. You float a plan, it tells you the plan is sound. You ask whether an approach is a good idea, it finds reasons it is. You have, in effect, assembled a one-person Abilene paradox: you are the group, the assistant is the member who will not rock the boat, and the two of you can nod your way into a decision you would never have reached if either had pushed back.

The fix is the same as it is for a team. Ask the assistant for the strongest case against your plan, not for validation. Make it argue the other side. And treat its agreement the way you should treat a quiet room: pleasant, but not evidence. An assistant that always agrees is not giving you a second opinion, and a note that records only the conclusion you liked, stripped of the objection you never raised, is the same phantom consensus in slow motion, [the kind of claim worth checking against the world](https://scribelet.app/blog/ai-fact-checking-for-notes) rather than inheriting whole.

## The dissent that never got recorded

The lasting damage of an Abilene decision is not the one bad trip. It is that the reasoning never gets written down, because officially there was no disagreement to record. The rewrite that nobody wanted goes into the record as "team decided to rewrite," full stop, with none of the four private objections attached. Six months later, when someone asks why the team committed to it, there is no honest answer in the archive, only the phantom consensus, and the real reasons, each person's unspoken doubt, are gone.

This is how a team's decision-making memory rots. A choice made by mismanaged agreement looks, in hindsight, like a choice the team actively made, which teaches exactly the wrong lesson for next time. The defense is to capture the real state of the room, not the official one: the objections raised and waved off, the reservations nobody wanted to be the first to voice, the fact that the "yes" was softer than it sounded. A decision record that holds the doubts alongside the decision is the difference between a team that learns from an Abilene trip and one that takes the same drive again next quarter, because the reasoning behind a choice [decays fast once the meeting ends](https://scribelet.app/blog/knowledge-decay) unless something durable holds it.

## Reading the Abilene paradox correctly

The concept is easy to overextend, so two guards are worth stating. First, not every agreement is a phantom. Sometimes a team says yes because it genuinely means yes, and reading real consensus as secret dissent is its own kind of paranoia. The tell for a true Abilene case is the private regret that surfaces immediately afterward; if people are still satisfied a week later, it was agreement, not the paradox. Do not go hunting for buried dissent that is not there.

Second, the answer is not to treat every smooth decision as suspect and manufacture conflict to prove the consensus is real. A team that cannot agree on anything without a staged fight has traded one dysfunction for another. The goal is narrow and specific: make it safe and cheap for a real objection to surface before the decision locks, so that when the group does agree, you can trust the agreement. The Abilene paradox is not an argument against consensus. It is an argument for making sure the consensus you are acting on actually exists. The cheapest way to do that is to give every quiet doubt a place to land, and to write the real reasoning down while the room still remembers it. [Try Scribelet free](https://scribelet.app) and keep your team's decisions with the doubts and the reasons attached, so the next trip to Abilene gets called off before anyone gets in the car.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>abilene-paradox</category>
            <category>decision-making</category>
            <category>teams</category>
            <category>engineering</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Simpson's Paradox: When the Aggregate Lies]]></title>
            <link>https://scribelet.app/blog/simpsons-paradox</link>
            <guid isPermaLink="false">https://scribelet.app/blog/simpsons-paradox</guid>
            <pubDate>Thu, 08 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Simpson's paradox is when a trend holds in every group but reverses once you pool the groups together. How to spot it in A/B tests, dashboards, and your own data. Try it free.]]></description>
            <content:encoded><![CDATA[
You shipped the redesign and the overall signup rate dropped two points. The old flow converted at eleven percent, the new one at nine, and the obvious move was to roll it back before it cost another week. Then someone broke the numbers down by traffic source, and the picture inverted. Among visitors from search, the new flow won. Among visitors from paid ads, the new flow won. Among visitors from the newsletter, the new flow won. Every single source converted better on the new design, and yet the combined number was worse. Nobody had faked anything. The aggregate and the segments were both computed correctly, from the same rows, and they said opposite things.

That is not a bug in the data or a rounding error. It is a named statistical phenomenon, and once you have seen it you start seeing it everywhere a number gets summarized. The thing that makes it dangerous is not that it is rare, it is that the pooled number looks authoritative and complete while quietly pointing the wrong way. A team that trusts the headline figure and never looks underneath it will confidently make the worse decision, roll back the better design, kill the better campaign, and never know it got played by its own arithmetic.

## What is Simpson's paradox?

Simpson's paradox is a statistical phenomenon where a trend or relationship that holds within every subgroup of the data disappears or reverses when those subgroups are combined into a single pooled total. Each group tells one story; the aggregate tells the opposite one. It is [named after Edward Simpson](https://en.wikipedia.org/wiki/Simpson%27s_paradox), who described it formally in 1951, though Karl Pearson and Udny Yule had noted the effect decades earlier, which is why it is sometimes called the Yule-Simpson effect.

The reversal is not magic. It comes from two things acting together: a confounding variable (a hidden third factor that is correlated with both the thing you are measuring and the groups) and unequal group sizes that let one group's weight dominate the pooled total. In the redesign example, the lurking variable was traffic source. Paid-ad visitors convert far worse than newsletter visitors no matter what the page looks like, and the new design happened to be shown to a larger share of paid-ad traffic during the test. When you pool everyone together, that unfavorable mix drags the new design's combined number below the old one, even though the new design beat the old one inside every source. The segments measure the design. The aggregate measures the design tangled up with the traffic mix, and the mix wins.

The practical lesson arrives fast: a single summary statistic is a lossy compression of the data underneath it, and the thing it most often loses is the one split that would have reversed your conclusion. [Try Scribelet free](https://scribelet.app) if you want a place to keep the splits and caveats behind your numbers, because the paradox is really a failure to write down which groups a metric was pooling over.

## The example everyone reaches for: Berkeley admissions

The textbook case is the [1973 University of California, Berkeley graduate admissions data](https://www.science.org/doi/10.1126/science.187.4175.398). Looking at the whole university, men were admitted at a noticeably higher rate than women, which looked like clear bias against female applicants. Broken down by department, the effect reversed or vanished: in most departments women were admitted at a slightly higher rate than men. The confounder was which departments people applied to. Women applied in larger numbers to competitive departments with low admission rates, while men applied more to departments that admitted almost everyone, so the pooled rate made the university look biased against women when no individual department was.

It is a clean illustration and worth knowing, but the Berkeley case is where most explanations stop, and stopping there is a mistake. You are not going to be handed a famous dataset with the paradox pre-labeled. You are going to meet it unlabeled, inside your own dashboard, on a Tuesday, disguised as a number that simply looks a little off. The useful skill is not reciting Berkeley. It is recognizing the shape of the reversal in data nobody has flagged for you yet.

## Why the reversal happens

The mechanism is easier to see than to say. Picture each group as its own little cloud of points with its own trend, and then imagine where those clouds sit relative to each other.

![A scatter chart showing Simpson's paradox. Group A sits in the upper left and Group B in the lower right. Within each group a solid green line rises from left to right, so each group improves as the horizontal value grows. A dashed amber line fitted to all the points together runs from the upper left down to the lower right, falling, because Group A has high outcomes at low values while Group B has low outcomes at high values. A caption reads that pooling the groups reverses the slope.](/blog/simpsons-paradox/trend-reversal.svg)

Inside Group A the line rises, and inside Group B the line rises, so within each group more of whatever you measured means a better outcome. But the two groups live in different regions of the chart: Group A has high outcomes at low values, Group B has low outcomes at high values. Draw one line through all the points together and it slopes the other way, down to the right, because the positions of the clouds overwhelm the slopes inside them. The within-group truth and the pooled truth genuinely point in opposite directions, and both are arithmetically correct. Which one is the right answer depends entirely on the question you are actually asking, and that is the part no formula decides for you.

This is what separates Simpson's paradox from an ordinary averaging mistake. There is no single "correct" view you forgot to take. There are two valid views that disagree, and choosing between them is a judgment about which variable is doing the causing and which is just along for the ride. Get that judgment wrong and the paradox does not just confuse you, it hands you a confident, backwards conclusion.

## Simpson's paradox in software and knowledge work

The reason this matters beyond statistics class is that modern teams run on pooled metrics. Almost every dashboard number you look at is an aggregate over groups you cannot see in the headline figure, which means almost every dashboard number is a candidate for this reversal. Here are the shapes it takes in practice, the hidden variable behind each one, and how the mistake actually lands.

| The aggregate you see | The hidden grouping | How the reversal bites |
|---|---|---|
| A/B test conversion overall | Traffic source or device mix | The losing variant won in every segment; the test just had an uneven split |
| Overall bug rate dropped | Which team or service shipped | Each team's bug rate rose; a low-bug team simply shipped more of the total |
| Average response time improved | Request type (cheap vs expensive) | Every request type got slower; the cheap-request share just grew |
| Feature adoption went up | New vs returning users | Adoption fell in both cohorts; the user mix shifted toward easy adopters |
| Support satisfaction climbed | Ticket category | Satisfaction dropped per category; easy tickets came to dominate the volume |
| Team velocity rose | Project or work type | Velocity fell on every project; the easy project took a bigger share |
| Churn looks flat year over year | Customer segment | Churn worsened in each segment; the healthy segment grew and masked it |

The pattern in every row is identical: the pooled number moved one way, every meaningful slice moved the other way, and a confounder in the group mix decided which story reached the dashboard. The danger is that the aggregate is not lying in any detectable way. It is the honest answer to a question you did not mean to ask, which is "what happens to the mix of groups I happened to have," rather than "what happens within a group." A team that reads only the top-line metric will act on the mix and believe it is acting on the thing.

This is also why "the data is up and to the right" is never, by itself, an argument. A metric that improves in aggregate can be getting worse everywhere that matters, and the only way to know is to split it. The habit that protects you is cheap: before you celebrate or panic over a pooled number, ask what groups it is pooling over and check whether the trend survives the split.

## Simpson's paradox vs Goodhart's law vs the McNamara fallacy

Simpson's paradox keeps company with a family of metric failures, and they get blurred together because they all end in "the number misled us." They are genuinely different, and telling them apart tells you which fix to reach for. Simpson's paradox is the odd one out of the group: nobody has to game anything and nobody has to ignore anything, the arithmetic itself does the misleading.

| | Simpson's paradox | Goodhart's law | McNamara fallacy |
|---|---|---|---|
| What it names | A trend that reverses when groups are pooled | A measure that stops being good once it becomes a target | Measuring only what is easy and ignoring the rest |
| The core failure | Aggregation hides a confounding variable | The measured decouples from the goal | The unmeasured is treated as nonexistent |
| Who is at fault | No one; the pooling does it | People optimizing the proxy | No one; it is a blind spot |
| The fix | Disaggregate and find the lurking variable | Stop tying stakes to the proxy | Name and watch the uncountable factors |

Put plainly: [Goodhart's law](/blog/goodharts-law) is about a good metric going bad once people start optimizing it, and [Campbell's law](/blog/campbells-law) sharpens that for high-stakes settings where the pressure corrupts the underlying work. The [McNamara fallacy](/blog/mcnamara-fallacy) is about never measuring the important thing in the first place. Simpson's paradox is different in kind from all three: the metric was collected honestly, nobody optimized it, nothing was left out, and it still points the wrong way, purely because of how the groups were combined. It belongs to the same broad family as a [reward that produces the opposite of what you intended](/blog/perverse-incentive), but its mechanism is arithmetic rather than incentive. When you are diagnosing a number gone wrong, the tell is simple. If the number reverses the moment you split it by some group, you are looking at Simpson's paradox, and the real question becomes which split is the honest one.

## How to avoid being fooled by Simpson's paradox

You cannot prevent the paradox from existing in your data, but you can stop it from reaching your decisions. The defense is a small set of habits applied before you trust any aggregate, not a statistical technique applied after the damage. Run the important numbers through these questions.

| Ask this before you trust an aggregate | Healthy answer | Paradox-trap answer |
|---|---|---|
| What groups is this number pooling over? | We know the segments and we have looked at them | It is just the overall figure |
| Does the trend hold inside each major segment? | Yes, we checked the split | We never split it |
| Did the group mix change over the period? | We accounted for the shift | We assumed the mix was stable |
| Is there a confounder correlated with both? | We named it and controlled for it | We did not look for one |
| Which view answers the question we actually have? | We chose it deliberately and wrote down why | We used whatever was on the chart |

The single most useful move is the second one: disaggregate before you conclude. Split the metric by the one or two groupings most likely to matter (source, segment, cohort, request type) and check whether the direction survives. If the aggregate and the splits agree, you can trust the headline. If they disagree, you have found a Simpson's paradox and the aggregate is the wrong number to act on. The AI overview on this topic will happily define the paradox for you; what it will not do is tell you which of your own splits to check, and that judgment is the entire job.

One caution so you do not overcorrect: disaggregating is not always the right answer either. Slice finely enough and every dataset dissolves into noise, and sometimes the pooled number genuinely is the one you want, because the grouping variable is a consequence of the treatment rather than a confounder. The skill is not "always split" or "always pool." It is knowing which variable is causal and which is incidental, which is a question about the world, not about the spreadsheet. This is the same discipline that separates people who [reason past the first visible number](/blog/second-order-thinking) from people who stop at the chart in front of them.

## The context that quietly disappears

Here is where a one-time catch turns into a permanent vulnerability. When your team does spot a Simpson's paradox and decides, correctly, that the segmented view is the honest one, that decision rests on context: which variable was the confounder, why you controlled for it, which split you trusted and which you discarded. That reasoning is exactly the kind of knowledge that [decays the moment nobody is actively holding it](/blog/knowledge-decay). Six months later the dashboard still shows the pooled number, the person who understood the confounder has moved teams, and a new analyst reads the headline figure at face value and walks straight back into the reversal you already solved.

The defense is to write the grouping down and keep it next to the metric. When you decide a number should be read segmented, record what it is pooling over, which confounder forced the split, and what the honest view is, in [the same durable record as the decision it informs](/blog/architecture-decision-record-examples) rather than a chat message that scrolls away by Friday. [Try Scribelet free](https://scribelet.app) and keep the reasoning behind each metric, the splits and the lurking variables and the reason the aggregate was not the answer, somewhere it stays legible to whoever inherits the dashboard. Scribelet's background agents even re-check what you have written against the world over time, so the context behind a number does not quietly rot while the number keeps getting reported as gospel.

## Reading Simpson's paradox correctly

The wrong lesson to take from all this is that aggregates are worthless and you should distrust every summary statistic. That is the overcorrection, and it leaves you paralyzed in front of data that is usually fine. Most pooled numbers are honest, and splitting everything into oblivion is its own way of never deciding anything. The accurate lesson is narrower: an aggregate is a claim about a particular grouping, and when the grouping hides a confounder, the claim can invert. The number is not lying. It is answering a different question than the one you have in your head.

So the standing question Simpson's paradox hands you is not "can I trust this chart?" but "what is this number pooling over, and would the trend survive the split?" Ask it before the headline figure drives a decision, keep a written record of the splits that matter, and you turn the paradox from a trap that fools confident teams into a routine check that takes two minutes. [Try Scribelet free](https://scribelet.app) and let it hold the grouping logic behind your metrics, so the next person to read the dashboard sees the whole story and not just the half the aggregate chose to tell.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>simpsons-paradox</category>
            <category>metrics</category>
            <category>data</category>
            <category>decision-making</category>
            <category>statistics</category>
        </item>
        <item>
            <title><![CDATA[The McNamara Fallacy: When the Unmeasured Vanishes]]></title>
            <link>https://scribelet.app/blog/mcnamara-fallacy</link>
            <guid isPermaLink="false">https://scribelet.app/blog/mcnamara-fallacy</guid>
            <pubDate>Wed, 07 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The McNamara fallacy is measuring only what is easy to count, then treating whatever you cannot measure as if it did not exist. How to spot it in software and knowledge work. Try it free.]]></description>
            <content:encoded><![CDATA[
Every slide in the quarterly review was green. Velocity was up, the ticket backlog was down, test coverage had crossed ninety percent, and uptime read four nines. Leadership looked at the deck and concluded the team was healthy, because every number that could fit on a slide said so. What was not on any slide: three of the five senior engineers were quietly interviewing elsewhere, the codebase had reached the point where nobody could estimate a change with a straight face, and the two customers who mattered most had already decided to leave but had not filed a ticket about it. None of that was a number, so none of it was discussed. Two quarters later the attrition, the estimates, and the churn all arrived at once, and everyone called it a surprise.

It was not a surprise. It was a blind spot with a name. The things that actually decided the team's fate were real, but they were hard to count, so they never made it onto the dashboard, and anything not on the dashboard was treated as though it were not happening. That is the McNamara fallacy, and it is a quieter and more dangerous cousin of the measurement traps most people already know. It does not require anyone to game a metric. It only requires that you keep your eyes on what is easy to measure and let the rest slide out of view until you have convinced yourself it does not exist.

## What is the McNamara fallacy?

The McNamara fallacy, also called the quantitative fallacy, is the mistake of making decisions based only on easily measurable factors while dismissing everything that cannot be easily quantified. It is [named after Robert McNamara](https://en.wikipedia.org/wiki/McNamara_fallacy), the U.S. Secretary of Defense who ran the Vietnam War by the numbers, most infamously the enemy body count. Those counts rose steadily while the war was being lost, because the things that actually predicted the outcome, morale and local politics and legitimacy, were not countable and so were left out of the analysis entirely. The social scientist Daniel Yankelovich later gave the pattern its formal shape, and the name stuck to the man who gave the clearest demonstration of it.

Yankelovich described the fallacy as four steps, and they escalate in a way that is worth reading slowly, because the damage is mostly in the last two:

1. Measure whatever can be easily measured.
2. Disregard what cannot be measured, or assign it an arbitrary number.
3. Presume that what cannot be measured easily is not important.
4. Conclude that what cannot be measured does not really exist.

The first step is just good practice. Measuring what you can is how any serious team operates. The slide from reasonable to ruinous happens across steps three and four, where "we do not have a number for this" silently becomes "this is not important," and then "this is not real." By the end you are not merely under-weighting the unmeasured. You have deleted it from the picture, and you make confident decisions inside a map that is missing its most important terrain.

## The four steps, and the one that does the damage

What makes the McNamara fallacy distinct from the better-known metric traps is that nobody has to cheat for it to ruin you. With a gamed metric, someone sees the target and takes a shortcut. The McNamara fallacy needs no shortcut and no bad actor. It is a failure of attention, not of integrity: the measurable crowds the unmeasurable out of the conversation, and the conversation is where decisions get made.

![A diagram titled what the McNamara fallacy deletes. On the left, a green column headed On the dashboard lists easy-to-count metrics: velocity, tickets closed, coverage percent, uptime. A bold green arrow runs from this column to a box labeled decisions are made here. On the right, an amber column headed Off the dashboard lists hard-to-count realities: can anyone understand the code, do engineers trust the estimates, will the customer actually stay, is morale holding. A faint dashed amber arrow from this column to the same decision box is cut by a red X, with a note reading not measured, so treated as not real. Below, a single line reads the outcome is decided by the right column and explained by the left.](/blog/mcnamara-fallacy/on-dashboard-off-dashboard.svg)

The diagram is the whole fallacy in one frame. Decisions flow cleanly from the left column, the measured one, because those numbers are in every report and every meeting. The right column, the one that actually determines whether the team succeeds, has no pipeline into the decision, because nobody put a number on it. The dashed line is cut not by malice but by absence. And here is the cruel part: the outcome is still decided by the right column. Reality does not care which variables you chose to track. It runs on all of them, measured or not, and then presents the bill.

This is why a McNamara-style failure always feels like it came out of nowhere. From inside the measured view, everything looked fine right up until it did not, because the leading indicators of the collapse were never instrumented. The warning signs existed. They just were not numbers, so to a team deep in the fallacy they were invisible, which is step four doing exactly what it does.

## The McNamara fallacy in software and knowledge work

Modern teams are unusually exposed to this, because so much of what we build generates clean, tempting, easily charted numbers, while the things that actually matter about the work resist counting. Here are the measurable proxies teams lean on, and the unmeasured reality each one tends to push off the table.

| What is easy to measure | What it quietly displaces | How the failure arrives |
|---|---|---|
| Story points and velocity | Whether the team can still estimate honestly | Planning stays green until a "simple" change takes a month |
| Tickets or PRs closed | Whether the underlying problems are actually fixed | Backlog shrinks while the same issues keep returning |
| Test coverage percentage | Whether the tests catch real regressions | Coverage hits ninety, a basic bug ships anyway |
| Uptime and latency SLOs | Whether users trust and understand the product | The dashboards are green while customers quietly churn |
| Lines of code or commits | Whether the codebase stays comprehensible | Output looks high while nobody can safely change anything |
| Notes captured or tasks logged | Whether you actually understand what you saved | The archive grows while your real recall shrinks |
| Headcount and hours logged | Whether morale and trust are holding | Capacity looks fine until three people resign in a week |

The through-line in every row is the same: the left column is a faithful record of activity and a poor record of value, and the right column is the reverse. None of these metrics is wrong to track. Velocity, coverage, and uptime are genuinely useful observations. They become the McNamara fallacy only when they are the *only* thing in the room, so the hard-to-measure half of reality drops out of the discussion and then out of the plan. The note-taking row is the one that hits closest to home for most individuals: it is easy to count how many notes you have captured and nearly impossible to count whether you still understand them, so people optimize the number they can see and let comprehension decay unmeasured.

## McNamara fallacy vs Goodhart's law vs Campbell's law

These three ideas travel together and get used interchangeably, but they name genuinely different failures, and keeping them straight makes each one sharper. A [thread on Hacker News](https://news.ycombinator.com/item?id=49695730) put the family neatly: the McNamara fallacy and Goodhart's law are "the bane of pure data-driven decision making," and they fail from opposite directions. Goodhart and Campbell are about a metric going bad under pressure. McNamara is about the metric you never took in the first place.

| | McNamara fallacy | Goodhart's law | Campbell's law |
|---|---|---|---|
| What it names | Measuring only the easy things and ignoring the rest | A measure that stops being good once it becomes a target | A high-stakes metric that corrupts the process it watches |
| The core failure | The unmeasured is treated as nonexistent | The measured decouples from the goal | The measured corrupts the underlying work |
| Who is at fault | No one; it is a blind spot, not a shortcut | People optimizing the proxy instead of the goal | Stakes high enough to bend the work out of true |
| Reach for it when | The thing going wrong was never on a chart | A once-useful number turned into theater | The work itself got worse chasing a number |

Put plainly: [Goodhart's law](/blog/goodharts-law) describes what happens when a good measure becomes a target and people start optimizing the number instead of the thing. [Campbell's law](/blog/campbells-law) sharpens that for high-stakes settings, where the pressure does not just corrupt the number but corrupts the actual process underneath it. The McNamara fallacy is upstream of both, and in a sense broader: it is the decision, made long before anyone games anything, to only look at what is countable. All three are species of the same genus, the family of ways a [reward or a metric produces the opposite of what you intended](/blog/perverse-incentive). They all sit downstream of an even earlier choice, which is [whether you went looking where the answer was or only where it was easy to look](/blog/streetlight-effect). When you are diagnosing a decision gone wrong, the question that separates them is simple. If a number got gamed, you are looking at Goodhart or Campbell. If the problem was never a number at all, you are looking at McNamara.

## How to avoid the McNamara fallacy

The fix is not to measure less, and it is certainly not to abandon metrics for vibes. It is to stop letting the measured half of reality silently define the whole of it. Most of the discipline comes down to deliberately keeping the unmeasured in view, and running your important decisions through a few questions before you trust the dashboard.

| Ask this before you decide | Healthy answer | McNamara-trap answer |
|---|---|---|
| What matters here that is not on the dashboard? | We can name it, and we look at it directly | If it mattered, it would be a metric |
| How did we handle the uncountable factors? | We weigh qualitative evidence alongside the numbers | We dropped them or gave them a fake number |
| Could this look green while the real thing fails? | Yes, and we watch the real thing on purpose | The numbers are good, so we are good |
| Where does our judgment come from? | Metrics plus people who see the work up close | Whatever the report says |
| What would we miss if we only read the chart? | We have asked, and we check for it | We have not asked |

The most practical version of this is a habit, not a tool: for every dashboard you rely on, write down what it deliberately leaves out, and keep that list next to the numbers. The point of naming the unmeasured is not to pretend you can count it. It is to keep it from vanishing. A factor you have written down as "important, not measurable" survives step four; a factor nobody wrote down does not. This is the same move that separates teams who [reason past the first visible consequence](/blog/second-order-thinking) from teams who stop at the number in front of them, and it is cheap insurance against being blindsided by a reality your instruments were never pointed at.

Qualitative evidence is not a lesser form of data. A skip-level conversation, a careful code read, a customer who tells you why they are leaving, an engineer's quiet sense that the estimates have stopped meaning anything: these are signal, often the earliest and most important signal you will get. The McNamara fallacy teaches you to discard them because they do not arrive as a number. The discipline is to treat "we cannot measure this cleanly" as a reason to pay closer attention, not permission to look away.

## The judgment that got lost

Here is where a one-time blind spot hardens into a permanent one. The qualitative context behind a decision, the reasons a number was only ever a rough proxy, the caveats everyone understood at the time, lives in people's heads and in scattered notes, and it is exactly the kind of knowledge that [decays the moment nobody is actively holding it](/blog/knowledge-decay). The team that chose to track velocity knew, on day one, that it was a crude stand-in for throughput and said nothing about quality. A year later that caveat is gone, the number has been promoted to the truth, and new people read the chart as though it measured everything worth measuring.

The defense is to write the unmeasured down and keep it next to the measured. When you stand up a metric, record what it is a proxy for, what it cannot see, and what qualitative signal you will watch alongside it. That belongs [in the same durable record as the decisions it informs](/blog/architecture-decision-record-examples), not in a Slack thread that scrolls away by Friday. [Try Scribelet free](https://scribelet.app) and keep the context behind each number, the part that cannot fit in the cell of a spreadsheet, somewhere it will still be legible to the person who inherits your dashboard. Scribelet's background agents even re-check what you have written against the world over time, so the reasoning behind a metric does not quietly rot while the metric keeps getting reported. A number whose limits are written down stays a tool. A number whose limits have been forgotten becomes the entire map, and that is McNamara's fallacy waiting to happen.

## Reading the McNamara fallacy correctly

The overcorrection is to swing to the opposite extreme and distrust measurement altogether, which is its own failure and usually a worse one. Numbers are not the problem. Running an organization on gut feeling and anecdote is how you get the mirror-image disaster, where the loudest voice wins and nothing is ever checked. The lesson of the McNamara fallacy is narrower and more useful than "numbers lie." It is that numbers are a partial view, and a partial view presented as a complete one is where the danger lives.

So the standing question the McNamara fallacy hands you is not "do we have enough metrics?" but "what are we deciding this on, and what did we leave out because it would not fit on the chart?" Measure what you can, name what you cannot, and keep the second list in front of you with the same seriousness as the first. [Try Scribelet free](https://scribelet.app) and let it hold the qualitative half of your decisions, the context and the caveats and the things that only a person who saw the work would know, so the unmeasured stays visible instead of quietly disappearing until the quarter it comes due.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>mcnamara-fallacy</category>
            <category>metrics</category>
            <category>decision-making</category>
            <category>engineering</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Perverse Incentives: When the Reward Backfires]]></title>
            <link>https://scribelet.app/blog/perverse-incentive</link>
            <guid isPermaLink="false">https://scribelet.app/blog/perverse-incentive</guid>
            <pubDate>Sat, 03 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A perverse incentive is a reward that produces the opposite of what you wanted, because the cheapest way to earn it skips the real work. How to spot one, how it relates to Goodhart's and Campbell's laws, and how to design around it. Try it free.]]></description>
            <content:encoded><![CDATA[
A support team got a new rule one quarter: whoever resolved the most tickets each month took home a bonus. It was a reasonable instinct. A team that closes tickets fast is a team that helps customers quickly, so the count really did track something good. Within a month the leaderboard was topped by the people replying "Please try restarting and reopen this ticket if the problem continues," then marking the ticket resolved. A reopened ticket counted as a fresh one, so the fastest route to the bonus was to never actually solve anything. Resolved-per-day climbed to a record. Customers were more stuck than before, and the people genuinely fixing hard problems, slowly, sat at the bottom of the board.

Nobody in that story was a villain. [The reflex to go looking for one when a system turns on itself](/blog/hanlons-razor) is the thing to resist. Each person did the rational thing given the reward in front of them, and the sum of those rational moves was a system working against its own purpose. That failure has a name, and it is the umbrella term that two more famous laws sit underneath. It is the perverse incentive: a reward structure that reliably produces the opposite of what it was meant to encourage. Knowing it by name changes the question you ask when a metric goes strange, from "who is cheating?" to the sharper and more useful "what is the cheapest way to earn this reward, and is that the thing I actually wanted?"

## What is a perverse incentive?

A perverse incentive is an incentive structure with an undesirable result, specifically one where the reward motivates behavior that works against the goal the reward was supposed to serve. The textbook origin is the cobra effect. Under British rule in Delhi, the government put a bounty on dead cobras to reduce their numbers; enterprising locals started breeding cobras to collect the bounty, and when the scheme was scrapped they released the now-worthless snakes, leaving the city with more cobras than it started with. That story is told in full as the opening example of [how a chain of locally sensible choices produces an outcome nobody chose](/blog/second-order-thinking), and it is the single clearest picture of the pattern: the incentive did not just fail, it inverted.

The key is in the word "cheapest." People respond to the reward actually on offer, not the one you intended, and they take the least costly route to it. When the cheapest route to the reward happens to be the real work, the incentive behaves. When a cheaper route exists that skips the work, the incentive goes perverse, because the reward is now paying for the shortcut. This is why a perverse incentive is not a rare freak event but the default failure mode of any reward attached to a proxy, and it is worth [writing down what each reward is actually a proxy for](https://scribelet.app) before you wire a consequence to it, because that is the detail everyone forgets within a quarter.

## Why a reward on a proxy inverts

Almost every incentive is aimed at a proxy rather than the thing you truly care about, because the thing you care about is usually hard to measure directly. That same preference for the measurable, [reaching for the number that is easy to get rather than the one that matters](/blog/streetlight-effect), is what decides which proxy you pick. You cannot easily reward "helped the customer," so you reward "closed the ticket." You cannot easily reward "wrote valuable software," so you reward "shipped the feature" or "hit the velocity target." The proxy stands in for the goal, and as long as moving the proxy means doing the real work, everything holds together. The trouble starts the moment a cheaper way to move the proxy appears.

![A diagram with two horizontal paths branching from a box labeled the reward is attached to a proxy. The top path, in amber and labeled what people actually do, reads game the proxy the cheapest route, then proxy goes up reward is paid, then real goal gets worse. The bottom path, in green and labeled what you hoped for, reads do the real work the costly route, then proxy goes up reward is paid, then real goal improves. A note between them reads both paths earn the reward, the cheaper one wins.](/blog/perverse-incentive/reward-on-proxy-two-paths.svg)

The diagram is the whole mechanism on one page. Both paths arrive at the same place, which is the reward being paid, because both of them move the proxy. The difference is cost. Doing the real work moves the proxy and also improves the goal, but it is expensive. Gaming the proxy moves the proxy just as well, earns the identical reward, and is far cheaper, so a rational person with a target to hit takes the top path. The result is that the reported number improves while the thing you wanted gets worse, not despite the incentive but because of it. The reward is functioning exactly as designed; it was simply designed to pay for the proxy, and the proxy had a back door.

This is the same force by which [any behavior a system can actually observe quietly becomes a behavior people build toward](/blog/hyrums-law), whether or not you meant to ask for it. Expose a measurable proxy and attach a reward, and you have not just created a target; you have created a search for the lowest-effort way to hit it. The more precisely you specify and enforce the proxy, the more sharply that search converges on the shortcut.

## Perverse incentives in software and knowledge work

Modern teams run almost entirely on proxies, and most of the ones that go bad do so in the perverse-incentive shape. Here are the rewards that most reliably backfire, the shortcut they end up paying for, and the goal that quietly suffers while the number looks fine.

| The reward | The cheapest route it pays for | The goal that suffers |
|---|---|---|
| A bounty per bug filed by QA | Filing many trivial or duplicate bugs | A signal-rich bug list anyone can triage |
| Pay or praise by lines of code | Verbose, copy-pasted, padded code | A small, clean, maintainable codebase |
| Tickets resolved per support agent | Fast empty replies; closing then reopening | The customer actually getting unstuck |
| Story points completed per sprint | Inflating estimates; padding the board | Honest planning and forecasting |
| Code-coverage percentage as a gate | Tests that execute lines but assert nothing | Tests that actually catch regressions |
| A/B experiments shipped per quarter | Running weak tests nobody learns from | Real, decisive product learning |
| Incidents resolved per on-call shift | Closing incidents fast; not filing the hard ones | An honest record of what keeps breaking |
| Referrals or signups per employee | Spamming low-quality invites | Reaching users who will actually stay |

The through-line is that in every row the reward is attached to something cheaper to fake than to earn, so the reward buys the fake. Notice that none of these is a case of bad people; each is a case of a good reward pointed at a convenient proxy with an obvious shortcut. The A/B-testing row is a telling one, because it is exactly where experienced product teams get caught: once "number of experiments" becomes the thing leadership counts, you get a pipeline full of underpowered tests that generate activity and no knowledge, which is the opposite of why you set up experimentation in the first place.

## Perverse incentive vs Goodhart's law vs Campbell's law

These three terms get used as if they were interchangeable, and they are closely related, but it is worth keeping them straight because each names a different slice of the same problem. The perverse incentive is the umbrella: any reward whose result runs counter to its intent. The two laws are sharper statements about measurement sitting underneath it.

| | Perverse incentive | Goodhart's law | Campbell's law |
|---|---|---|---|
| What it names | A reward that produces the opposite of its intent | A measure that stops being good once it becomes a target | A high-stakes metric that corrupts the process it monitors |
| Scope | The whole family of backfiring rewards | Any measure under optimization pressure | Institutions and systems under heavy stakes |
| The emphasis | The behavior the reward buys | The decoupling of measure from goal | The stakes, and damage to the underlying work |
| Reach for it when | You want the general name for the trap | You need the clean statement that targets get gamed | You need to explain why the work itself got worse |

In practice, [Goodhart's law](/blog/goodharts-law) gives you the crisp one-liner, that a measure under pressure to be a target stops measuring what it did, and [Campbell's law](/blog/campbells-law) adds that the higher the stakes, the faster that happens and the more the real work rots underneath. The perverse incentive is the broader category both belong to, and the cobra effect is its most extreme instance, where the reward does not merely decouple from the goal but actively drives the goal backward. When you are diagnosing a reward gone wrong, "perverse incentive" is the right opening diagnosis, and Goodhart and Campbell are the finer tools for explaining the mechanism and the scale.

## How to design an incentive that does not backfire

A perverse incentive is not an argument against rewarding people. It is an argument against pointing a reward at a convenient proxy and then walking away. Most of the fix is cheap and comes down to closing the back doors the shortcut would use. These are the questions to run any reward through before you attach a real consequence to it.

| Question | Safer answer | Danger-zone answer |
|---|---|---|
| What is the reward actually attached to? | The outcome, or a basket of hard-to-fake proxies | A single easy-to-move number |
| What is the cheapest way to earn it? | Doing the real work is the cheapest route | An obvious shortcut skips the work |
| Who is rewarded by it? | People who also own the real outcome | People paid only on the proxy |
| Can you still see the real result? | Yes, you spot-check the substance directly | No, the number is all anyone looks at |
| How high are the stakes on it? | Modest, so bending the work is not worth it | Life-altering, so any shortcut is tempting |
| What happens when it is gamed? | A paired counter-metric visibly gets worse | Nothing visible pushes back |

The pattern underneath the table is that a reward backfires when it has an easy shortcut and no independent view of the real thing and high enough stakes to make the shortcut worth taking. Remove any one of those and the perversion loses most of its grip. The cheapest lever is usually the pairing: for every number you reward, name a second number that gets worse when the first is gamed, and watch them together. Before you rip out an incentive that has already gone bad, though, it is worth [finding out why it was put there in the first place](/blog/chestertons-fence), because the behavior it was fighting often comes straight back the moment the reward is gone.

## The incentive whose reason got lost

Here is where a one-off bad quarter hardens into a permanent trap. Every incentive was introduced once, by someone, to solve a specific problem. The ticket-count bonus was added because support used to sit on tickets for days. The coverage gate was set because an untested release once took down production. At the moment it is created, everyone understands that the number is a stand-in and roughly how much weight it can bear. Then the person who set it moves on, the original pain fades, and what remains is the reward with its stakes still attached and its [original reasoning quietly decayed away](/blog/knowledge-decay).

New people inherit "we hit our coverage target" or "we lead the resolved-per-day board" with no memory that the target was only ever a proxy, so they optimize it with a clear conscience, shortcut and all. The fix is specific and cheap: when you attach a reward to a number, write down what it is a proxy for, what the cheapest way to game it would be, and what paired signal would tell you it had started to backfire. That note belongs [in the same durable record as the decisions it came from](/blog/architecture-decision-record-examples), next to the reasoning, so the next person inherits the intent along with the metric. [Try Scribelet free](https://scribelet.app) and keep the purpose and the failure conditions behind each incentive, not just the number, where the people who inherit your scorecards will actually find them. A reward whose reason is written down can be retired the day it starts paying for the wrong thing; a reward whose reason has decayed becomes a target nobody dares question.

## Reading perverse incentives correctly

The tempting overreaction is to conclude that incentives are hopeless and to stop rewarding anything, which is the wrong lesson and an expensive one. People respond to incentives whether or not you design them, and an organization with no deliberate rewards still has plenty of accidental ones. The point of understanding perverse incentives is not to abandon rewards but to design them with the shortcut in mind, so the cheapest way to earn the reward is the thing you actually wanted.

So the standing question a perverse incentive hands you is not "are people gaming this?" but "what is the cheapest way to earn this reward, and is that the behavior I meant to buy?" Reward outcomes rather than convenient proxies, pair every number with a counter-number, keep the stakes proportional to how gameable the metric is, and keep an independent view of the real result. [Try Scribelet free](https://scribelet.app) and let it hold the reasoning behind each incentive your team runs on, so the rewards keep pointing at the work instead of quietly paying for its opposite.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>perverse-incentive</category>
            <category>engineering</category>
            <category>metrics</category>
            <category>incentives</category>
            <category>decision-making</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Campbell's Law: How High-Stakes Metrics Corrupt the Work]]></title>
            <link>https://scribelet.app/blog/campbells-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/campbells-law</guid>
            <pubDate>Fri, 02 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Campbell's law says the more a metric is used for high-stakes decisions, the more it corrupts the very thing it measures. How it differs from Goodhart's law, and how to keep the stakes from rotting the work. Try it free.]]></description>
            <content:encoded><![CDATA[
An engineering org decided that deploy frequency was the number that mattered. It was a reasonable instinct. Teams that ship often tend to ship small, safe, well-tested changes, so the rate of deploys really did track something healthy. Then it became the headline on the leadership dashboard, tied to quarterly targets and praised in all-hands. Within two quarters deploys had tripled, and almost none of them mattered. Engineers split one change into five commits and shipped them separately. Risky, valuable work that needed a careful rollout got deferred, because a big deploy that might fail looked worse on the chart than three trivial ones that could not. Reliability, the thing deploy frequency was supposed to protect, quietly got worse. The dashboard had never looked better.

That is not simply a gamed metric. The number was gamed, yes, but something worse happened underneath it: the actual work changed shape to serve the number, and the work got worse. The team was not measuring shipping anymore. It was measuring its own skill at producing deploys, and that skill had crowded out the shipping. There is a law that names this exact failure, and it is sharper and older than the one most people reach for. It is Campbell's law, and the thing it predicts is not just that your metric will lie to you but that the process the metric was watching will bend itself out of true. Knowing it is the difference between asking "is this number still honest?" and asking the more important question: "what is this number doing to the work?"

## What is Campbell's law?

Campbell's law states: the more any quantitative social indicator is used for social decision-making, the more subject it will be to corruption pressures, and the more apt it will be to distort and corrupt the social processes it is intended to monitor. It was formulated in 1976 by the American social scientist [Donald T. Campbell](https://en.wikipedia.org/wiki/Campbell%27s_law), who spent his career on research methodology and watched the same pattern play out across education, policing, and public policy. The classic case is standardized testing: once school funding and teacher jobs ride on test scores, schools start teaching to the test, narrowing the curriculum and, in the worst cases, manipulating the results, so the scores rise while the education they were meant to reflect declines.

Two things in that statement do the real work, and both are easy to skim past. The first is **high-stakes**. Campbell did not say a measure goes bad the moment you look at it; he said it corrupts in proportion to how heavily it is used for consequential decisions. A number watched out of curiosity stays mostly honest. A number wired to funding, promotions, or public rankings is under enormous pressure, and it decouples fast. The second is the word **distort**. The measure does not just stop being accurate; the underlying activity it monitors gets deformed to produce the number. The scores go up and the learning goes down. That second clause is why this law deserves its own name, and it is worth [keeping the distinction written down somewhere durable](https://scribelet.app), because it is the part everyone forgets first.

## Why the stakes set the speed

Nothing about a metric changes when you raise the stakes on it. What changes is how hard people push on it, and Campbell's insight is that the push scales with the consequences. Give a number mild attention and it stays roughly correlated with the thing you care about, because the cheapest way to nudge it is still to do the real work. Attach the number to someone's bonus, their team's budget, or a leaderboard the whole company sees, and the calculus flips. Now there is a strong, direct incentive to move the number by whatever route is cheapest, and the cheapest route is almost never the substance it was a proxy for.

![A line chart with the horizontal axis labeled how much the metric drives high-stakes decisions, rising from watched to wired to pay and funding. A reported-metric line climbs steadily across the whole axis. A real-outcome line tracks it closely at low stakes, then crosses a marked corruption threshold where it flattens and falls while the reported line keeps rising, and the widening shaded gap between them is labeled distortion.](/blog/campbells-law/stakes-corruption-threshold.svg)

The chart above is the shape of the law. On the left, where the metric is only watched, the reported number and the real outcome move together, because moving the number honestly means improving the work. As you move right and the stakes climb, the two lines split at a threshold, and past it they move in opposite directions: the reported metric keeps rising because people are now optimizing it directly, while the real outcome bends downward because the effort and the shortcuts went into the proxy. The shaded gap is the distortion Campbell warned about, and the crucial point is that the gap grows with the stakes, not with time. You can open it in a single quarter by attaching a big enough consequence to a soft enough number. This is also why the better your enforcement, the faster the rot: a metric nobody is rewarded for drifts slowly, and a metric everyone is judged on corrupts almost on contact. Campbell's law is about a high-stakes number deforming the work it watches; the quieter companion failure is [measuring only what is easy to count and ignoring the rest](/blog/mcnamara-fallacy), where nothing gets gamed because the thing that mattered was never tracked at all.

People are not cheating when this happens, or not usually. They are doing the rational thing, which is responding to the incentive actually in front of them, the same way [a chain of locally sensible choices can add up to a bad outcome nobody picked](/blog/second-order-thinking). The deploy-frequency team was not sabotaging the company. Each engineer was making the individually correct move given what the org had decided to reward, and the sum of those correct moves was a corrupted process.

## Campbell's law vs Goodhart's law

These two get used interchangeably, and they are close cousins, but they are not the same statement and the difference is useful. The short version many people quote, "when a measure becomes a target, it ceases to be a good measure," is [Goodhart's law](/blog/goodharts-law) in the phrasing the anthropologist Marilyn Strathern gave it. Campbell's is older in spirit and aimed at a different scale.

| | Campbell's law (1976) | Goodhart's law (1975) |
|---|---|---|
| Field of origin | Social science, program evaluation | Economics, monetary policy |
| The core claim | A metric used for high-stakes decisions corrupts and distorts the process it monitors | When a measure becomes a target, it stops being a good measure |
| What it emphasizes | The stakes, and damage to the underlying activity | The decoupling of the measure from the goal |
| Scale it describes best | Institutions and systems: schools, agencies, whole teams | Any measure under optimization pressure, from one person up |
| The sharpest one-liner | The higher the stakes, the faster the number lies and the work rots | What gets measured as a target gets gamed |
| Reach for it when | You need to explain why the work itself got worse, not just the dashboard | You need the clean, general statement of the trap |

The practical read is that Goodhart tells you *that* a targeted metric goes bad, and Campbell tells you *why it gets worse the more it matters* and *that the real damage lands on the activity, not the spreadsheet*. There is a third sibling worth knowing, the cobra effect, [where an incentive produces the opposite of its intent](/blog/perverse-incentive) (a bounty on dead cobras leads to people breeding cobras for the bounty). The cobra effect is the extreme case of both laws: the metric did not just decouple, it inverted. When you are diagnosing a broken incentive, Goodhart names the mechanism, Campbell names the stakes and the collateral damage, and the cobra effect is the punchline when it has gone all the way.

## Where Campbell's law shows up in software and knowledge work

Modern teams run almost entirely on proxies, and the high-stakes ones are exactly the ones Campbell's law comes for. Here are the measures that most reliably corrupt the work when the stakes on them rise, what people do instead, and what gets damaged underneath.

| High-stakes metric | What people optimize | The process it corrupts |
|---|---|---|
| Deploy frequency as a headline KPI | Trivial, split-up deploys; deferred risky work | Shipping real value, and reliability itself |
| Story points or velocity tied to reviews | Point inflation; padded estimates | Honest planning and forecasting |
| Tickets closed per engineer | Splitting work, closing hard tickets as "cannot reproduce" | Actually resolving the user's problem |
| Code review approval rate or speed | Rubber-stamp approvals | The review catching real defects |
| Bug count as a team scorecard | Not filing bugs; reclassifying them | The honest record of what is broken |
| Support time-to-first-response | Fast, empty replies inside the SLA | The customer actually getting helped |
| An AI model's benchmark score | Tuning to the benchmark's quirks | The capability the benchmark stood for |

The through-line is Campbell's second clause. In every row it is not only the number that suffers; it is the thing underneath. A team gaming deploy frequency ships worse software. A team gaming ticket counts leaves users unhelped. The dashboard improves and the work rots, which is precisely the trap, because the people above the dashboard see only the line going up. This is the same dynamic by which [any behavior you can actually observe becomes the thing people build toward](/blog/hyrums-law), whether or not it was what you meant to ask for. Raise the stakes on an observable proxy and you do not just get a gamed proxy; you get a workforce quietly optimizing the proxy at the expense of the job.

## Which of your metrics are in the danger zone

Campbell's law is not a reason to stop measuring, but it is a reason to look hard at which numbers you have loaded with consequences. A metric is dangerous roughly in proportion to how these line up.

| Question | Safer | In the danger zone |
|---|---|---|
| How high are the stakes attached to it? | Watched, informative, low-consequence | Wired to pay, budget, promotion, or a public ranking |
| How easy is it to move without doing the real work? | Hard; the cheapest path is the work itself | Easy; an obvious shortcut moves it |
| Can you still see the real outcome directly? | Yes, you spot-check the substance | No, the number is all anyone looks at |
| Who is measured by it? | People who also own the real outcome | People rewarded only on the proxy |
| Is it one number or a balanced set? | Several that trade off against each other | A single figure everyone chases |

The pattern is that corruption needs high stakes *and* an easy shortcut *and* no independent view of the real thing. Remove any one and the law loses most of its grip. The cheapest fix is almost always the stakes: a number you watch instead of reward cannot corrupt the work much, because nobody has a reason to bend the work around it. The mistake teams make is attaching the heaviest consequence to the most convenient number, which is the exact combination Campbell's law punishes hardest. Before you tear out a metric that has already gone bad, though, it pays to [find out why it was put there in the first place](/blog/chestertons-fence), because the pressure it created is often holding up something you cannot see.

## Campbell's law at the scale of a field

The AI world is living through a textbook case, and it is Campbell rather than Goodhart because the damage is landing on a whole research process, not one system. When a benchmark becomes the high-stakes scoreboard for an entire field, labs optimize for the benchmark, because funding, press, and recruiting ride on topping it. Models get tuned to the benchmark's quirks, test questions leak into training data, and the score climbs while the capability it was meant to track moves less than the number suggests. The benchmark stops measuring the field's progress and starts measuring the field's skill at the benchmark, which is Campbell's distortion clause playing out across an industry. The single-model version of this, where one system learns to game its own reward signal, is [the reward-hacking face of Goodhart's law](/blog/goodharts-law); Campbell's contribution is the reminder that when the stakes are collective and high, the corruption is collective too.

The lesson transfers straight to how any team evaluates an AI tool. If you judge an assistant on one easy-to-score proxy, you will get a tool optimized for that proxy and a team that has quietly reorganized its own work to produce a good score, exactly as the deploy-frequency org did. The defenses are the same as for human metrics: keep the stakes on any single number modest, measure against a balanced set, hold back evaluations the system was not tuned to please, and keep looking at real output.

## The metric whose reason got lost

Here is where Campbell's law turns from a bad quarter into a permanent institutional trap. Every high-stakes metric was chosen once, by someone, for a reason. Deploy frequency was elevated because releases used to be rare and terrifying. The response-time target was set because a specific customer churned after being ignored. At the moment of choosing, everyone knows the number is a proxy and roughly how much weight it can bear. Then the person who set it moves on, the original pain fades, and what remains is the number with its stakes still attached and its reasoning [quietly decayed away](/blog/knowledge-decay). New team members inherit "we hit our deploy target" with no memory that the target was only ever a stand-in, and they optimize it with a clear conscience because nobody told them it was a proxy, or how high the stakes had crept.

That is the point of no return, and the fix is cheap and specific. When you attach real consequences to a metric, write down what it is a proxy for, how much weight it is meant to carry, and what would tell you it had started corrupting the work. That note belongs [in the same durable record as the decisions it came from](/blog/architecture-decision-record-examples), next to the reasoning, so the next person inherits the purpose and the expiry conditions along with the number. A metric whose reason and stakes are written down can be dialed back the day it starts distorting things. A metric whose reason has decayed becomes a target no one dares lower and no one can defend. [Try Scribelet free](https://scribelet.app) and keep the *why* and the intended weight behind each number, not just the number, where the people who inherit your dashboards will actually find it.

## Reading Campbell's law correctly

The tempting overreaction is to conclude that measuring people is hopeless and to stop. That is the wrong lesson and an expensive one, because numbers are how you see a system too large to watch by hand, and steering blind is worse than steering on an imperfect gauge. Campbell's law is not an argument against measurement. It is an argument against putting life-altering stakes on a soft proxy and then looking only at the proxy. The skill is to measure while keeping the consequences proportional to how gameable the number is, and while holding on to an independent view of the real outcome.

So the standing question Campbell's law hands you is not "is this number accurate?" but "how much is riding on this number, and what is that doing to the work it watches?" Keep the stakes modest on anything easy to game, keep the real outcome in view, and write down why each measure exists and how much weight it was meant to hold. [Try Scribelet free](https://scribelet.app) and let it hold the reasoning behind your metrics, so the numbers your team steers by keep pointing at the work instead of slowly replacing it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>campbells-law</category>
            <category>engineering</category>
            <category>metrics</category>
            <category>decision-making</category>
            <category>software-laws</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Yak Shaving: Why One Task Becomes Ten, and How to Stop]]></title>
            <link>https://scribelet.app/blog/yak-shaving</link>
            <guid isPermaLink="false">https://scribelet.app/blog/yak-shaving</guid>
            <pubDate>Thu, 01 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Yak shaving is the cascade of prerequisite tasks that pulls you off your real goal. What it is, why each step feels necessary, and how to climb out. Try it free.]]></description>
            <content:encoded><![CDATA[
You sat down to change one line of code. To change it you needed to update a library, which needed a newer runtime, which broke the build config, which sent you into the docs for a tool you had never heard of, and now it is three hours later, you have seven browser tabs open about a YAML schema, and the one line is still not changed. You are not procrastinating. Every single step felt necessary. That is exactly what makes it dangerous.

This is yak shaving, and it has a name precisely because everyone who builds things falls into it. Here is what the term actually means, why the chain of prerequisite tasks feels logical at every step, how to tell the productive version from the wasteful one, what changes when an AI assistant is in the loop with you, and a simple way to climb back out when you notice you are deep in the stack.

## What is yak shaving?

[Yak shaving](https://en.wiktionary.org/wiki/yak_shaving) is a series of seemingly unrelated, cascading tasks you have to complete before you can get to the thing you actually set out to do. Each task in the chain exists only because the previous one blocked you, so you keep descending into smaller and smaller prerequisites until, metaphorically, you are standing in a zoo shaving a yak and have forgotten you wanted to wax your car.

The term was coined in the 1990s by Carlin Vieri, a PhD student at the MIT AI Lab, after a "Yak Shaving Day" segment on the cartoon The Ren and Stimpy Show. It spread through engineering culture and was popularized by a widely shared 2005 post, [Don't Shave That Yak!](https://seths.blog/2005/03/dont_shave_that/), by Seth Godin, whose running example is the car wax that ends at the zoo. The [Jargon File](http://catb.org/jargon/html/Y/yak-shaving.html) records the canonical definition: "any seemingly pointless activity which is actually necessary to solve a problem which solves a problem which, several levels of recursion later, solves the real problem you are working on."

The word "pointless" there is doing a lot of work, and it is slightly misleading. The individual steps are usually not pointless at all. The hose really is broken; the library really does need updating. The problem is the recursion, and the fact that each level hides the one above it. If you keep your work in [Scribelet](https://scribelet.app), the fix is to make the stack visible, which turns an afternoon you cannot account for into something you can see and stop. More on that below.

## Why the yak stack feels necessary

The reason yak shaving is so hard to catch in the moment is that it is not laziness and it is not avoidance. It is the opposite. It is a chain of locally rational decisions that add up to a globally irrational afternoon.

At every single step, the next task genuinely does block the previous one. You cannot change the line without the library; you cannot get the library without the runtime; you cannot get the runtime without fixing the config. Each link in the chain passes the test "is this actually required to make progress," so your focus stays high and your sense of productivity stays intact. You feel busy and purposeful the entire time, because you are solving real problems. They are just not your problem.

This is what separates yak shaving from ordinary procrastination. Procrastination feels like avoidance; you know you are dodging the work. Yak shaving feels like work, which is why it survives your own attention. The signal that you are in it is not boredom or guilt. It is a quiet realization, often hours in, that you can no longer quickly state why you are doing the thing in front of you without reconstructing three or four steps backward.

It is a close relative of [second-order thinking](https://scribelet.app/blog/second-order-thinking), turned inward and gone wrong. Second-order thinking asks "and then what" to see where a decision leads. Yak shaving is what happens when you only ever ask "and then what is blocking this," descend into the answer, and never ask "and is the original thing still worth it from down here."

## Yak shaving and its lookalikes

Yak shaving gets lumped in with several other focus failures, and the differences matter because the fix for each is different. Google's own results for the term even surface the question of how it relates to bikeshedding. Here is how the common ones line up.

| Pattern | What it is | How to tell it apart |
|---|---|---|
| **Yak shaving** | A chain of prerequisite tasks, each required by the last, that pulls you far from the original goal | Every step is genuinely necessary; the problem is the depth of the recursion, not any single task |
| **Bikeshedding** | Spending disproportionate time on a trivial, easy-to-grasp detail while the hard, important part goes untouched | The work is not required at all; you do it because it is comfortable and legible, not because it blocks anything |
| **Rabbit-holing** | Following curiosity or research far past the point of usefulness | Driven by interest, not by a blocker; the tasks are not prerequisites, they are tangents |
| **Analysis paralysis** | Over-deliberating a decision until you make none | You are not doing tasks at all; you are stuck before the first one |
| **Feature creep** | Scope quietly expanding past the original intent | Happens to a product or project over time, not to a person in an afternoon |

The practical takeaway: if the detour is genuinely required and you have simply gone too deep, that is yak shaving, and the fix is to resurface and re-decide. If the detour was never required, that is bikeshedding or a rabbit hole, and the fix is to stop entirely. Scope that expands over weeks rather than hours is [feature creep](https://scribelet.app/blog/feature-creep), which is its own problem with its own defenses.

## Productive yak shaving versus the wasteful kind

Not all yak shaving is bad, and the writers who popularized the term are careful about this. Sometimes the yak genuinely needs shaving. If updating that library also fixes a security hole, unblocks three other tickets, and you were going to have to do it this quarter anyway, then the detour produced durable value beyond your immediate goal. You did more than one thing, and the extra things were worth doing.

The distinction is not "did I stray from the plan." It is "did the detour create value that outlasts the task that triggered it." A useful test, when you notice you are a few levels down:

- **Would I do this task on its own merits, this week, if it were not blocking me right now?** If yes, it is probably productive. If the honest answer is "no, I would never otherwise touch this," you are shaving a yak nobody needed shaved.
- **Is the chain getting shorter or longer?** Productive detours resolve; you fix the real blocker and climb back. Wasteful ones fractal outward, each fix revealing two more.
- **Can I still state the original goal in one sentence without reconstructing it?** If you have lost the top of the stack, you have lost the thing that decides whether any of this is worth it.

This is the same discipline as knowing when a task is actually complete rather than endlessly adjacent to complete. A clear [definition of done](https://scribelet.app/blog/definition-of-done) for the original task is one of the best defenses against yak shaving, because it gives you a fixed point to measure every detour against. If the detour does not move you toward "done" on the thing you actually came to do, it is a candidate to cut or defer.

## The AI twist: your assistant shaves yaks too

Two things change now that an AI assistant is usually somewhere in the loop, and they pull in opposite directions.

The first is that AI coding agents yak shave with enthusiasm, and faster than you do. Point an agent at a one-line fix and it will cheerfully update dependencies, rewrite adjacent code it decided was untidy, and generate three helper files, each step locally defensible and the sum far past what you asked for. The agent has the same failure mode you do, with none of the fatigue that eventually makes a human look up and ask what they are doing. The accumulated edits are a yak stack you did not descend yourself, which makes it harder to notice and harder to unwind.

The second is subtler. When you get stuck on a prerequisite, an AI can resolve it in seconds, which feels like the cure for yak shaving but is often an accelerant. The friction of a hard prerequisite used to be a natural stopping point, a moment where you might look up and reconsider the whole detour. Remove that friction and you descend further, faster, because every blocker now has an instant answer. You can shave a much taller yak before anything forces you to pause.

The defense is the same in both cases: keep the top of the stack explicit and in front of you, and review what actually happened rather than trusting that it was all necessary. When an agent does the shaving, read its full set of changes against your original one-line intent, the way you would [talk a stuck bug through to a rubber duck](https://scribelet.app/blog/rubber-duck-debugging) before accepting a fix. The confident, plausible, slightly-too-much output is exactly where unexamined yaks hide.

## How to climb out: make the stack visible

The core problem with yak shaving is not the detour. It is that the stack is invisible, held in your head, and your head quietly drops the top of it. The single most effective fix is to externalize the stack the moment you take the first detour, so the original goal cannot silently fall off. [A note](https://scribelet.app) does this in about fifteen seconds.

![A descending stack of prerequisite tasks from the real goal down to the yak, with a dashed line back to the top showing the climb-out path.](/blog/yak-shaving/yak-stack.svg)

Write down the real goal at the top, then push each detour onto the stack as you take it, one line each:

```
GOAL: change the retry timeout to 5s   <- the thing I actually came to do

  push: bump http-client to 3.x (old version ignores the config)
    push: 3.x needs node 20 (we are on 18)
      push: node 20 breaks the docker base image
        push: <- I am here. shaving a yak.

Climb-out check:
- Is "change the retry timeout" still worth an afternoon?  [yes/no/defer]
- Does the docker fix help anything besides this?          [yes/no]
- Shortest path back to GOAL from here?
```

The stack does three things a mental model cannot. It keeps the original goal pinned at the top where losing it is impossible, so you always know what the detour is in service of. It shows you the depth at a glance, and depth is the single best signal that a productive detour has turned wasteful. And because it is written down, it survives the interruption: if you get pulled away and come back, you resume from the stack instead of from scratch, which is the same reason [writing down the "why" rather than trusting it to memory](https://scribelet.app/blog/self-documenting-code) beats keeping it in your head.

When you reach a level that fails the climb-out check, you have three honest moves. Cut the whole chain and come back to the real goal with the detour abandoned. Defer the detour by filing it as its own task to do properly later, which is often the right call for the "this really should be fixed, but not right now, not like this" yaks. Or decide the yak genuinely needs shaving today, which is fine, as long as it is a decision you made at the top of the stack rather than a place you drifted to at the bottom.

## When shaving the yak is the right call

None of this means detours are bad. Software, writing, and research are full of real prerequisites, and refusing to ever follow one is its own dysfunction. The skeleton-key skill is not avoiding yak shaving. It is doing it deliberately: noticing when you have taken a detour, deciding on purpose whether it is worth it, and keeping the decision reversible by keeping the stack visible.

The afternoons that vanish are the ones where every choice was made at the bottom of the stack, in the narrow light of the immediate blocker, with the real goal long out of view. Kept notes also protect you weeks later, because a detour you fully understood today is just [knowledge quietly going stale](https://scribelet.app/blog/knowledge-decay) if you cannot find the reasoning again when the same yak reappears. The next time a one-line change starts to grow a tail, the question is not whether to follow it. It is whether you can still see the top of the stack while you do.

Scribelet is built for exactly this kind of visible thinking: a fast place to pin the real goal, push each detour onto a stack you can actually see, and ask an AI about your own stack without handing it the wheel. The next three-hour yak is coming. The only question is whether you will be able to see it while it happens. [Try it free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>yak-shaving</category>
            <category>productivity</category>
            <category>focus</category>
            <category>engineering-practice</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Rubber Duck Debugging: Talk to the Duck, Write to the Duck, Ask the AI]]></title>
            <link>https://scribelet.app/blog/rubber-duck-debugging</link>
            <guid isPermaLink="false">https://scribelet.app/blog/rubber-duck-debugging</guid>
            <pubDate>Wed, 30 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Rubber duck debugging solves bugs by explaining your code line by line. Why it works, how to do it in writing, and what changes when the duck is an AI. Try it free.]]></description>
            <content:encoded><![CDATA[
You have been staring at the same twenty lines for an hour. The bug makes no sense. Then a coworker walks over, you start to explain what the code is supposed to do, and somewhere around the third sentence you stop mid-word, say "never mind," and go fix it. They never said anything. Explaining it was the fix.

That is rubber duck debugging, and the joke is that you do not even need the coworker. A rubber duck on your desk works just as well, because the person was never solving your problem. You were, the moment you were forced to say it out loud. Here is what the technique actually is, why the act of explaining finds bugs that silent re-reading never will, how to run it in writing so the insight does not evaporate, and what changes now that the duck can be an AI that talks back.

## What is rubber duck debugging?

Rubber duck debugging is a problem-solving technique where you fix a bug by explaining your code, line by line and out loud, to an inanimate object such as a rubber duck. The point is not the duck. The point is that articulating each step in plain language forces you to examine assumptions you were silently skipping, and the flawed one usually reveals itself before you finish the sentence.

The name comes from an anecdote in [The Pragmatic Programmer](https://en.wikipedia.org/wiki/Rubber_duck_debugging) by Andy Hunt and Dave Thomas, in which a developer carried a rubber duck and debugged by forcing himself to explain the code, in detail, to the duck. The practice was already old folklore under other names (talking to the teddy bear, the cardboard programmer). The duck just gave it a memorable label, and the label stuck because every working programmer recognizes the experience.

It sounds like a gag, and the [canonical joke site](https://rubberduckdebugging.com/) leans into that. But the mechanism underneath is real, well understood, and not limited to code. Anyone who thinks for a living can use it, which is the reason it belongs in a note-taking toolkit and not only in an IDE. If you keep your work in [Scribelet](https://scribelet.app), the duck can be a note, and that turns a throwaway trick into something you can reread later.

## Why explaining out loud finds the bug

The technique works because reading and explaining are different cognitive acts, and only one of them catches your own mistakes.

When you read your own code silently, you read what you meant to write. Your brain fills the gap between intention and text automatically, so the line that says `>=` reads as the `>` you intended, and you skim straight past it for the tenth time. Silent review runs on assumptions, and the bug is almost always hiding inside an assumption you never checked.

Explaining out loud breaks that. To say a line, you have to convert it from a thing you recognize into a claim you assert: "this loop runs while the index is less than or equal to the length, so on the last pass it reads one element past the end." The moment the sentence is spoken, the off-by-one is obvious, because you cannot say a false step in plain language and keep believing it. Speaking forces a slower, serial pass where reading allowed a fast, parallel skim.

There is a name for the underlying trap. Experts skip explanation precisely because they know the material, a bias called the [curse of knowledge](https://scribelet.app/blog/curse-of-knowledge): the more fluent you are, the harder it is to see where a beginner (or your own future self) would get lost, and the more you gloss the step that is actually wrong. Rubber ducking is the cheapest known antidote. It drags the glossed step back into the open by refusing to let you assert it silently.

![Silent reading skims past a wrong assumption while explaining each line forces the gap between intended and actual behavior into the open.](/blog/rubber-duck-debugging/silent-vs-explained.svg)

This is also why the technique generalizes far past debugging. Stuck on a design decision, a paragraph that will not come together, a data model that feels wrong: explaining it step by step to something that cannot help you is the same move, and it works for the same reason. It is a close cousin of [second-order thinking](https://scribelet.app/blog/second-order-thinking), where the discipline is to keep asking "and then what" instead of stopping at the first plausible answer.

## Three ducks: spoken, written, and AI

The classic duck is silent and spoken to. But the duck is just a forcing function for articulation, and there are now three practical forms, each with a different tradeoff.

| Duck | What it forces | Best for | The catch |
|---|---|---|---|
| **Spoken duck** | Real-time, serial explanation out loud | A live bug you are stuck on right now | Leaves no record; the insight is gone once you fix it |
| **Written duck** | Slower, more precise articulation you can reread | Harder problems, and anything worth keeping | Takes a few more minutes than talking |
| **AI duck** | Explanation plus a response that can probe back | Bugs where you want a second angle | It answers, so it can short-circuit the very self-explanation that does the work |

The spoken duck is fastest and the oldest. It is perfect for the everyday stuck moment, and it costs nothing. Its only weakness is that it is disposable: you solve the bug, and the reasoning that got you there disappears.

The written duck fixes that. Instead of talking to a toy, you explain the problem to a note, step by step, as if the reader knows nothing. This is slower than speaking, and that is the feature, not the bug: writing forces even more precision than talking, and it leaves a durable artifact. A "why I was stuck and what it turned out to be" note is worth far more later than the fix alone, because the fix is in the code and the reasoning is not. This is the same principle behind [self-documenting code](https://scribelet.app/blog/self-documenting-code): the intent that lived in your head is the part that gets lost, so the discipline is to write it down where it survives.

The AI duck is the newest, and it is genuinely different. Explaining your bug to an assistant that can respond is not really rubber ducking anymore; it is a conversation. That is sometimes better and sometimes worse, and it is worth being clear about which.

## The AI duck: better and worse

Google's own results for this topic now end with an offer to be the duck: paste your code and it will step through it with you. Every AI assistant makes the same offer. When the duck talks back, two things change.

It is better when you are genuinely stuck and want a second angle, or when explaining alone has not surfaced the flaw and you need something to ask the questions the spoken duck cannot. A responsive duck can point at the loop bound you skipped, propose a hypothesis, or notice a pattern you are too close to see. Used well, it compresses the loop.

It is worse in a specific and easy-to-miss way: the AI answers, and the answer can arrive before the act of explaining has done its work. The whole power of the classic duck is that you solve the problem in the process of articulating it. If you dump a half-formed description and the assistant produces a fix, you skipped the part that builds understanding, and you have traded a bug you understand for a patch you do not. Worse, the assistant is confident whether it is right or wrong, which invites the [Gell-Mann amnesia effect](https://scribelet.app/blog/gell-mann-amnesia-effect): you catch it being wrong about the part you know, then trust it completely on the part you do not.

The move that keeps the benefit is to explain first and ask second. Write the problem out to the duck in full, as if it could not answer, and only then hand that explanation to the AI. Often you will fix it before you hit send, which is the ideal outcome. When you do send it, you are sending a precise description rather than a vague one, which gets a better answer, and you have primed yourself to check that answer instead of accepting it. If the assistant works over your own notes, the same caution applies as with any AI reading your material: [treat its output as a draft to verify](https://scribelet.app/blog/ai-fact-checking-for-notes), not a verdict to trust.

## How to rubber duck well

The technique fails in exactly one way: you go through the motions without actually asserting each step. "This function processes the data" is not an explanation, it is a label, and it hides the same assumptions your silent reading did. Ducking works only when you are specific enough that a wrong step would sound wrong.

A written duck session that actually catches bugs looks like this. It doubles as a note you can keep.

```
## Bug: [what is wrong, in one line]

Expected: [what the code should do]
Actual:   [what it does instead]

Walking through it:
1. This line does X, because [reason]. So after it, the state is [Y].
2. Then this line does Z, which assumes [assumption]. Is that true here?
3. ...

Where the story breaks: [the step where "expected" and "actual" diverge]

Fix: [what you changed, and why it was wrong]
```

Three things make the difference between a real session and theater. State the expected and the actual behavior before you start; the bug lives in the gap between them, and naming both makes the gap findable. Explain every line, especially the ones you are sure are correct, because the one you are sure about is the usual culprit. And write down the assumption behind each step explicitly ("this assumes the list is never empty"), because an unstated assumption is exactly what silent reading let you skip.

## When ducking is the wrong tool

Rubber ducking is for problems where you have the information and cannot see it. It is not for problems where you are missing information. If the bug is in a library you have never read, in someone else's undocumented service, or in a system whose behavior you genuinely do not know, explaining your own code to a duck will not conjure the missing facts. That is a research problem, not an articulation problem, and the fix is to go read or to ask a human who knows.

It is also weaker on problems that are structural rather than local. A bug that comes from two teams making incompatible assumptions at a boundary is not something one person can talk their way to, because the mismatch lives in the org chart as much as the code, which is the lesson of [Conway's law](https://scribelet.app/blog/conways-law). Duck the part you own; escalate the part you do not.

And like every practice that produces a useful artifact, the written duck is only worth keeping if you can find it again. A folder of debugging notes you never reopen is just [knowledge quietly decaying](https://scribelet.app/blog/knowledge-decay). The value is in the search: the next time the same class of bug appears, the note that explained the last one is the fastest way through.

## The duck is a thinking tool, not a debugging trick

Strip away the toy and rubber duck debugging is a general method: when you are stuck, stop consuming the problem and start explaining it, in enough detail that a wrong step cannot hide. Say it to a duck, write it to a note, or hand it to an AI, in that order of increasing power and increasing risk. The spoken duck is free and disposable. The written duck is slower and durable. The AI duck is the most capable and the easiest to misuse, because it can answer before you have done the thinking that the answer was supposed to replace.

Scribelet is built for the written and AI versions of this: a place to explain a problem to yourself step by step, keep the explanation, and ask an assistant about it over your own notes without shipping them to anyone. The next stuck hour is going to happen. The question is whether the way out of it leaves anything behind. [Try it free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>rubber-duck-debugging</category>
            <category>debugging</category>
            <category>thinking</category>
            <category>self-documenting-code</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Sturgeon's Law: Why 90% of Everything Is Crud]]></title>
            <link>https://scribelet.app/blog/sturgeons-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/sturgeons-law</guid>
            <pubDate>Sat, 26 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Sturgeon's law says 90% of everything is crud. Why that is true, why AI makes it sharper, and how to filter for the 10% that matters. Try it free.]]></description>
            <content:encoded><![CDATA[
Open any feed, any inbox, any folder of half-finished drafts, and the pattern is the same. Most of what is in front of you is not worth your attention. A little of it is very good. You spend most of your time wading through the first kind to reach the second, and if you are honest, a lot of what you produce yourself lands in the first pile too. This is not pessimism. It is a rough law of large numbers about creative and intellectual output, and it has a name.

Sturgeon's law says that ninety percent of everything is crud. It sounds like a punchline, and it started as one, but it turns out to be one of the more useful lenses you can carry through a world that now generates text, code, and content faster than anyone can read it. What matters is not the exact figure. It is what the figure implies about where your effort should go: not into consuming more, and increasingly not even into producing more, but into filtering. Here is Sturgeon's law in full, why it holds, why AI has made it sharper rather than softer, and a practical way to keep the ten percent that is worth keeping.

## What is Sturgeon's law?

Sturgeon's law is the adage that "ninety percent of everything is crud." It means that in any field, most of the output is mediocre or worse, and only a small fraction is genuinely good. The claim is not that a particular field is bad; it is that low quality is the normal, expected majority everywhere, so judging a whole category by its bulk is a mistake.

The line comes from the American science fiction author [Theodore Sturgeon](https://en.wikipedia.org/wiki/Sturgeon%27s_law). In the 1950s, critics liked to dismiss science fiction by pointing at its worst examples and concluding the genre was junk. Sturgeon's reply, [first laid down at a 1953 World Science Fiction Convention](https://faculty.college.emory.edu/sites/weeks/misc/slaw.html) and later in print, was that yes, ninety percent of science fiction is crud, but that is because ninety percent of everything is crud. Cars, books, films, plumbing, politics: pick a domain and the same proportion holds. Judging science fiction by its worst was unfair only because you would never judge any other field that way.

There is a wrinkle worth knowing. Sturgeon called the ninety percent line his "Revelation," and he reserved the phrase "Sturgeon's Law" for a different, drier statement: "nothing is always absolutely so." Popular usage flipped the labels, and the ninety percent version is now universally called Sturgeon's law. The original wording used "crud" rather than "crap," which is the form that survives in the [software-culture Jargon File](http://www.catb.org/jargon/html/S/Sturgeons-Law.html). None of this changes the practical point, but it is a nice example of how the ninety percent even applies to the retellings of the law itself.

If you keep any kind of knowledge base, the law is really a question about your own folders: which ten percent of what you saved can you still find when you need it? That is the problem [Scribelet](https://scribelet.app) is built to solve, and it is worth holding in mind through the rest of this.

## Why ninety percent is crud

The number is not measured; it is a shorthand for a real asymmetry between how easy things are to make and how hard they are to make well. A few forces produce it reliably.

The first is that **producing something is cheap and producing something good is expensive.** Anyone can write a sentence, ship a feature, or record an episode. Making it genuinely good demands taste, revision, and a lot of discarded attempts, and most output never gets that far because most output is a first or second pass that someone shipped anyway. The distribution of quality is not bell-shaped around "pretty good." It has a long, fat tail of the merely adequate.

The second is that **skill is unevenly distributed and most work is done by the majority, not the minority.** In any field a small number of people or teams produce most of the excellent work, and everyone else produces the rest. When you sample the whole field at random, you are mostly sampling the everyone-else, so the average is dragged down toward the tail. The best of a field and the typical of a field are two very different things, and Sturgeon's law is a reminder to keep them separate.

The third is that **quality is only visible in comparison, and comparison is work.** A single piece in isolation looks fine. It is only when you line it up against the ten percent that is genuinely good that its flaws show. Since most people do not do that comparison, most crud circulates unchallenged, which is its own small proof of the law.

## Sturgeon's law in the age of AI

Sturgeon was talking about human output, where the ninety percent at least took effort to produce. The modern version is harsher, because the cost of producing the crud has collapsed to almost nothing.

A large language model can generate a plausible blog post, a passable function, or a confident-sounding summary in seconds, at a marginal cost close to zero. The ten percent that is genuinely good has not gotten cheaper; taste and judgment are as scarce as ever. What has changed is the volume of the ninety percent. There is now effectively infinite crud, produced faster than anyone can read it, and much of it is polished enough to pass a glance, and often impossible to tell from [a sincere piece or a deliberate parody](/blog/poes-law). Essays titled "AI meets Sturgeon's law" already rank for the term, because the pattern is easy to recognize once you name it: AI did not raise the average quality of everything, it raised the quantity of the average.

This flips where the scarce skill lives. When crud was expensive to produce, being a competent producer was valuable. When crud is free, the bottleneck moves entirely to filtering. The person who can quickly tell the ten percent from the ninety percent, and who has a system for keeping the ten percent where they can find it again, has the advantage. Generating more is no longer the hard part. Deciding what deserves to survive is. This is the same shift that makes [verifying what an AI tells you](https://scribelet.app/blog/ai-fact-checking-for-notes) more important than getting it to produce more: the output is abundant, so the value is in the judgment applied to it.

![A funnel filtering 100 units of input into 90 discarded as crud and 10 kept as the ten percent worth keeping.](/blog/sturgeons-law/ninety-ten-filter.svg)

## Examples of Sturgeon's law

Once you have the lens, you see the ninety-ten split everywhere you consume or produce information. A few of the common shapes:

| Domain | The ninety percent | The ten percent worth keeping |
|---|---|---|
| Your feeds and inbox | Noise, forwards, half-read newsletters | The two posts a month you actually reference later |
| AI-generated drafts | Plausible, generic, off in the details | The occasional passage that is genuinely sharp |
| A codebase | Features and code paths that add little value | The parts that carry the load and drive outcomes |
| A field of research | Papers that are never cited and never replicate | The handful that change how you think |
| Your own notes | Captures you never reopen | The evergreen notes you return to for years |

The last row is the one most people never count, and it is the one that matters most if you keep a knowledge base. You save far more than you will ever reuse. Most of what you capture is a fleeting thought, a link you never revisit, a quote out of context. That is fine and expected; Sturgeon's law predicts it. The problem is not that the ninety percent exists. The problem is when it is mixed in with the ten percent so thoroughly that you cannot find the good notes without wading through the rest, which is how a knowledge base quietly [decays into a pile you no longer trust](https://scribelet.app/blog/knowledge-decay).

The software reading is worth pausing on too. Applied to a product, Sturgeon's law says roughly ninety percent of features and experiments will not pan out, and only a small fraction will drive real value. That is not an argument against trying things; it is an argument for shipping small, measuring, and cutting fast, because the alternative is [carrying the ninety percent forever as bloat](https://scribelet.app/blog/feature-creep). The teams that win are not the ones that produce the most. They are the ones that kill the crud quickly and double down on the ten percent.

## How to apply Sturgeon's law

Knowing that ninety percent is crud is only useful if it changes what you do. The point is not to become cynical and dismiss everything, which is just a different way of failing to find the good ten percent. The point is to build filtering into your workflow so the ten percent survives and the ninety percent does not clog it. A few habits do most of the work.

**Filter on the way in, not just on the way out.** The cheapest place to reject crud is before it enters your system. Unsubscribe from the newsletters you skim and never act on. Prune the feeds. Ask the AI for less and demand more of what it gives you. Every piece of crud you refuse at the door is one you do not have to filter again later. One fast tell for a feed is [Betteridge's law of headlines](/blog/betteridges-law): a headline that ends in a question mark can almost always be answered no, so it rarely earns the click.

**Mark the ten percent explicitly.** When something is genuinely good, do not just consume it and move on. Flag it, tag it, write down why it mattered. The ten percent is only useful if you can find it again, and an unmarked good note is functionally lost inside the ninety percent around it. This is the whole reason to keep evergreen notes separate from fleeting captures.

**Judge the source, not just the piece.** If a source reliably produces crud, discount it as a source, and stop spending attention proving the point piece by piece. If a source reliably produces the good ten percent, weight it up. This is Sturgeon's law used as a triage rule: you cannot evaluate everything, so evaluate the source's hit rate and let that carry. It also guards against a related trap, [trusting a source again right after you caught it being wrong](https://scribelet.app/blog/gell-mann-amnesia-effect), which is how crud from a known-unreliable source keeps getting through.

**Let the tools do the first pass, but keep the final call.** AI is genuinely good at the first cut, at summarizing and surfacing and clustering, at telling you what a hundred captures are roughly about. It is not good at the final judgment of what is worth keeping, because that depends on your goals, which it does not have. Use it to compress the ninety percent so you can see it, then decide the ten percent yourself.

## The ninety percent hiding in your own notes

If you keep any kind of knowledge base, Sturgeon's law is not a fact about the world out there. It is a fact about your own folders. Most of what you have saved you will never reopen. That is not a failure of your note-taking; it is the expected shape of capture. The failure is only when the ten percent that is genuinely valuable is buried so deep in the ninety percent that finding it costs more than rewriting it from scratch.

This is where a filtering system earns its keep. A good knowledge base is not the one that captures the most. It is the one that makes the ten percent findable: the notes you return to, the sources that earned their place, the ideas that survived a second look. That means capture should be cheap and low-friction, so you never lose the good stuff by failing to write it down, but retrieval and curation should be strong, so the good stuff is not lost in the flood. This is exactly the problem [Scribelet](https://scribelet.app) is built for: capture everything without friction, then let AI help surface and connect the ten percent that matters, so your notes stay a place you actually trust rather than a bigger pile of the same crud. The same discipline applies to what an AI reads back to you: if it is drawing on notes that are ninety percent noise, its answers will be too.

## When Sturgeon's law is the wrong lens

Sturgeon's law is a useful default, but it can be misused, and it is worth naming the failure modes.

It is not a licence for cynicism. "Ninety percent is crud" is a reason to filter harder, not a reason to dismiss whole fields or to stop looking for the ten percent. The people who quote it to justify not reading, not trying, or not shipping have taken the observation and used it as an excuse, which misses the point entirely; the law is about the value of the ten percent, not the worthlessness of the ninety.

It also does not tell you where the ten percent is. The law describes the distribution, not the location. Knowing that most output is crud does not identify the good stuff for you; that still takes judgment, taste, and the comparison work that most people skip. Sturgeon's law tells you to filter. It does not do the filtering.

And the ninety percent figure is not literal. It is a memorable shorthand for "most," and the real proportion varies by field, by moment, and by how you define quality. Treating it as a precise measurement, or arguing about whether it is really eighty-five or ninety-five percent, is its own small piece of crud. What survives is the shape: producing is easy, quality is rare, and the scarce skill is telling them apart. That instinct pairs well with [other named laws that describe how systems and quality behave over time](https://scribelet.app/blog/hofstadters-law).

## Getting started

Sturgeon's law will not stop being true, and AI has only raised the volume of the ninety percent you have to move through. The response is not to consume less or produce less. It is to get deliberate about filtering, so the ten percent that is genuinely worth keeping survives and stays findable.

That starts with where you keep things. Capture without friction so you never lose the good notes, then lean on curation and AI-assisted retrieval so the ten percent does not drown in the rest. [Try Scribelet free](https://scribelet.app) and build a knowledge base that filters for the ten percent instead of just growing the ninety.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>sturgeons-law</category>
            <category>thinking</category>
            <category>curation</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Gell-Mann Amnesia Effect: Why You Trust a Source You Caught Wrong]]></title>
            <link>https://scribelet.app/blog/gell-mann-amnesia-effect</link>
            <guid isPermaLink="false">https://scribelet.app/blog/gell-mann-amnesia-effect</guid>
            <pubDate>Fri, 25 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The Gell-Mann amnesia effect: why you trust a source right after catching it wrong, why AI makes it sharper, and how to stop it in your notes. Try it free.]]></description>
            <content:encoded><![CDATA[
You read the paragraph about your own field and your jaw tightens. It gets the basic mechanism backward, cites a study that says the opposite of what the writer thinks it says, and confidently repeats a claim you personally know to be false. You have spent years on this exact thing. The author has spent an afternoon. You close the tab, a little smug, and open the next article by the same publication, this one about monetary policy or a foreign election, a subject you know almost nothing about. You read it as if it were true. It does not even occur to you to doubt it. The source that was hopeless five minutes ago is now your window on the world.

That reset has a name. It is the Gell-Mann amnesia effect, and once you have caught yourself doing it you will see it everywhere: in the newspaper, in your feeds, in the AI assistant that just hallucinated a function that does not exist and then told you how to file your taxes. Most explanations give you the definition and a knowing chuckle. What is more useful is understanding why the amnesia is so easy, why AI has made it sharper, and what it means for the notes and sources you rely on, because a source you already know is unreliable is exactly the one you keep trusting anyway. Here is the Gell-Mann amnesia effect in full, with examples, a way to spot it in your own reading, and the version quietly running inside your own notes.

## What is the Gell-Mann amnesia effect?

The Gell-Mann amnesia effect is a cognitive bias in which you notice that a source is completely wrong about a subject you know well, and then turn to that same source on a subject you do not know and trust it completely, as if the error you just saw never happened. The competence you are qualified to judge and the competence you are not qualified to judge get treated as two separate accounts, and the failure in the first never debits the second. It has a mirror-image sibling worth knowing alongside it: where Gell-Mann amnesia makes you trust a source you should doubt, [the Semmelweis reflex](/blog/semmelweis-reflex) makes you dismiss evidence you should weigh, and both are failures to match your trust to the actual evidence in front of you.

The term was [coined by the novelist and physician Michael Crichton in a 2002 speech](https://en.wiktionary.org/wiki/Gell-Mann_amnesia_effect). He named it after his friend Murray Gell-Mann, the Nobel Prize-winning physicist, and later admitted the famous name was mostly a joke: attaching a great physicist to the idea made it sound more rigorous than it was. The label stuck anyway, because the thing it describes is universal. Crichton's own framing was about newspapers. You read the media story on a subject you understand, he said, and you see it is wrong, sometimes hilariously so. Then you turn the page to national or international affairs and read as if the rest of the paper were somehow more accurate than the part you just caught being wrong. You forget. That is the amnesia.

The reason it deserves a name, rather than a shrug, is that it is not a lapse of intelligence. Smart, careful people do it constantly, precisely because they are experts in something. The deeper your expertise in one area, the more clearly you can see a source fail there, and the sharper the contrast with how readily you trust it everywhere else. Repetition deepens the trap, because the more often a source's framing reaches you, [the more true it starts to feel regardless of whether it was ever checked](/blog/illusory-truth-effect). The practical defense is not a better memory but a place to keep the signal, so a source you caught being wrong stays flagged the next time you lean on it. That is worth [keeping somewhere you can actually check later](https://scribelet.app).

![A source's trustworthiness plotted across two topics. On the topic you know well, the trust bar has dropped to near zero after you caught an error. On the very next topic, which you cannot judge, the same source's trust bar snaps back to full height, as if the error never happened.](/blog/gell-mann-amnesia-effect/trust-reset-on-page-turn.svg)

## Why the amnesia is so easy

The effect is not really about forgetting. It is about how trust is filed. Three mechanics stack up to produce it.

The first is that **trust attaches to topics, not to sources.** When you evaluate the article on your specialty, you are judging a claim you can check. When you read the next article, you have no claim you can check, so you fall back on the only signal available, which is the general aura of the publication: it looks authoritative, it has a masthead, it is written in the confident register of fact. The specific failure you witnessed lives in a different mental folder from the general impression, and the general impression is what carries into the next page.

The second is that **the correction is expensive and the trust is free.** Doubting the second article properly would mean doing the work you just watched the source fail to do: finding the primary sources, checking the reasoning, holding the conclusion open until you have. Extending trust costs nothing. Faced with that asymmetry, on a topic you did not come to investigate, you take the free option almost every time. This is the same economics that makes [refuting a bad claim cost far more than making it](https://scribelet.app/blog/brandolinis-law), turned inward: verifying is expensive, so by default you do not. The cheaper move is to make the source earn your trust rather than default to giving it: [what arrives without evidence can be set back down without evidence](/blog/hitchens-razor), no rebuttal required.

The third is that **being right once feels like being reliable in general.** A source that is excellent on the topic you can judge earns real credibility, and credibility is sticky. But accuracy does not travel evenly across a source's range. A publication with a brilliant science desk can have a careless politics desk. A model that writes flawless Python can be confidently wrong about case law. Competence is local; the trust it earns behaves as if it were global.

## The Gell-Mann amnesia effect in the age of AI

Crichton was describing newspapers, but the sharpest modern version is the one sitting in your editor and your chat window. You ask an AI assistant something in your area of deep expertise, and you catch it cold: it invents a library function, misremembers an API, cites a paper that does not exist, gets a definition exactly backward. You correct it, maybe with a little irritation, and move on. Ten minutes later you ask it to summarize a field you do not know, or to explain a legal or medical question, and you take the answer at face value. The system that just fabricated something in the one domain where you could check it has your full trust in every domain where you cannot.

This is worse than the newspaper case for two reasons. A model's confidence is perfectly uniform: it does not sound less certain when it is guessing, so the usual tone-based tells are gone, the same missing cue that makes [a parody and a sincere statement read as identical online](/blog/poes-law). And its errors are not evenly distributed in a way you can predict, which means the one flawless answer you can verify tells you almost nothing about the next one you cannot. The related search "Gell-Mann amnesia effect AI" has become common enough that it is worth naming the pattern directly: catching your assistant wrong on your specialty is not a reason to relax about everything else it tells you. It is a reason to hold the rest a little looser. Giving a source you have caught being wrong the same standing as one you have not is its own kind of [false balance](/blog/false-equivalence). The same caution applies the moment you [use that assistant as a rubber duck](/blog/rubber-duck-debugging): it will propose a fix with total confidence, and a confident fix is exactly the thing to verify rather than paste. In [a web increasingly filled with bots and AI-generated content](/blog/dead-internet-theory), holding confident but unplaceable sources a little looser stops being caution and becomes the baseline.

## Examples of the Gell-Mann amnesia effect

The effect shows up anywhere you consume information from a source across a range wider than your own expertise, from a newspaper to a model to [a question-mark headline you can answer before you even click](/blog/betteridges-law). A few of the common shapes:

| Where it happens | What you catch | What you then trust anyway |
|---|---|---|
| Journalism on your beat | The article on your industry gets the basics wrong | The same paper's take on a subject you cannot check |
| An AI assistant | It hallucinates a function or misstates a fact you know | Its summary of a field you have never studied |
| A code review | A confident comment about your module is simply mistaken | The same reviewer's verdict on code you understand less well |
| A newsletter or podcast | The episode on your hobby is shallow and off | Next week's episode on economics, taken as gospel |
| Your own old notes | One line you know is now outdated | The rest of the note, reused without a second look |

The last row is the one most people never count, and it is the one that matters most if you keep a knowledge base. You know a particular note has a stale claim in it, because you remember writing it before something changed. You use the rest of the note anyway, because re-verifying the whole thing is work. The amnesia is not only about other people's sources. It runs against your past self.

## How to spot and avoid Gell-Mann amnesia

You cannot become an expert in everything, so you cannot verify everything. The goal is not universal skepticism, which is just paralysis. It is to stop letting a caught error evaporate. A few habits do most of the work.

**Rate the source, not just the claim.** When you catch a source being wrong in your area, write down that it was wrong, and carry the discount forward. One failure is a data point about reliability, not an isolated slip to be forgotten by the next paragraph. This is [Sturgeon's law used as a filter](https://scribelet.app/blog/sturgeons-law): most of what any source produces is crud, so track the hit rate instead of re-judging every piece from scratch.

**Ask what you would need to check it.** Before accepting a claim outside your expertise, name the one thing that would confirm or break it: a primary source, a date, a number. If you cannot even name the check, you are not trusting the claim, you are trusting the aura. Hold it as provisional.

**Verify at the moment of capture, not later.** The cheapest time to check a claim is when you first meet it, while the context is in front of you. A claim you save unverified becomes far more expensive to check months later, when you have already built on it. This is the same discipline that keeps [notes from quietly going stale](https://scribelet.app/blog/knowledge-decay): the cost of checking only ever goes up.

**Keep the correction attached to the claim.** When you do the expensive work of establishing that something is wrong, store that finding next to the claim, so the next person who meets it, including future you, does not have to re-litigate it. A debunking you cannot find again is one you will pay for twice.

**Separate what you can judge from what you cannot.** The whole trap is treating one merged trust score for a source. Split it. "Reliable on X, unproven on Y" is a more honest and more useful stance than "generally trustworthy," and it is the stance that survives contact with the next article.

## The version hiding in your own notes

If you keep notes or use an AI assistant over them, the Gell-Mann amnesia effect is not an abstraction about the media. It is a property of your own knowledge base. You save a claim from a source, and the source's local unreliability does not travel with the claim into your notes. Six months later the saved line reads as neutral fact, stripped of the context in which you once doubted it. The note does not remember that you caught its source being wrong. Only you did, and you forgot.

The defense is structural, not a matter of willpower. Attach the source to every claim, so a conclusion carries the evidence you would need to re-check it. Verify claims when you save them, when the check is cheap, rather than inheriting other people's confidence wholesale. And treat an AI assistant working over your notes the way you should treat any source: a caught error in your domain is a reason to [verify its claims against the world](https://scribelet.app/blog/ai-fact-checking-for-notes), not a one-off to correct and forget. Deciding which claims are worth the check, and which you can let ride, is itself [a judgment worth making deliberately](https://scribelet.app/blog/second-order-thinking) rather than by reflex.

## When Gell-Mann amnesia is not the explanation

The concept gets overused, so a guard is worth stating. Not every case of trusting a source is amnesia. If you have good independent reason to think a source is strong in one area and weak in another, acting on that is calibration, not a bias. A science journal you rightly trust on methodology and distrust on policy is not a victim of the effect; it is being read correctly. The amnesia is specifically the failure to carry a *known* signal forward: you saw the error, it was relevant, and you let it vanish. If you never had the signal, you are not forgetting, you are just working with incomplete information, which is the normal condition of knowing anything.

The other misreading is to swing to blanket cynicism and trust nothing. That is not the lesson either. A source can be genuinely excellent in its lane. The point is that its excellence there does not underwrite its claims everywhere, and neither does a single failure condemn it everywhere. Both the halo and the grudge are the same mistake: one trust score for a source that actually has many.

## Getting started

The Gell-Mann amnesia effect is not a reason to distrust everything you read. It is a reason to stop spending trust you have already learned not to. The fix is to make a caught error count, in your reading and in the notes where it quietly stops counting.

Start with three moves. When you catch a source wrong in your domain, record it, so the discount survives the turn of the page. Verify claims at the moment you save them, while the check is cheap, not months later when you have built on them. And keep every claim with its source and any correction you paid for, so a conclusion you once doubted does not come back looking like neutral fact. [Try Scribelet free](https://scribelet.app) and let it hold your notes with their sources and re-check them against the world, so the source you caught being wrong does not get to reset your trust every time you turn the page.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>gell-mann-amnesia</category>
            <category>thinking</category>
            <category>misinformation</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Brandolini's Law: Why Debunking Costs More Than Lying]]></title>
            <link>https://scribelet.app/blog/brandolinis-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/brandolinis-law</guid>
            <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Brandolini's law: refuting nonsense takes an order of magnitude more effort than producing it, and AI made it worse. What it means and how to defend your notes. Try it free.]]></description>
            <content:encoded><![CDATA[
Someone in a thread claimed the library you maintain leaks memory under load. It does not, and never has, but the claim was one sentence and it took ten seconds to type. Refuting it took your afternoon. You pulled the benchmarks, re-ran them on a clean machine, screenshotted the flat memory graph, dug up the closed issue where this exact worry was investigated two years ago, wrote it all up in careful, non-defensive prose, and posted it. By then the original claim had been quoted twice more, and one of the people who saw it walked away believing the leak was real, because the correction was longer and more boring than the accusation. You were right. It cost you a hundred times what it cost them, and you are not sure it worked.

That imbalance has a name. It is Brandolini's law, and once you have felt it you recognize it in every argument that goes nowhere, every rumor you cannot kill, every wrong sentence in a document that takes a meeting to unwind. Most write-ups give you the one-line definition and a rueful nod. What is more useful is understanding exactly why the asymmetry is so steep, why generative AI has made it steeper, and what it means for the notes and sources you rely on, because a false claim you save is just as cheap to write down and just as expensive to catch later. Here is Brandolini's law in full, and a practical way to spend your limited refutation budget where it actually counts. A companion bias makes the problem worse: even after you catch a source being wrong, [you tend to forget it the moment you turn the page](/blog/gell-mann-amnesia-effect), so the same unreliable source keeps earning the trust it should have lost.

## What is Brandolini's law?

Brandolini's law, also called the bullshit asymmetry principle, states that the amount of energy needed to refute nonsense is an order of magnitude larger than the energy needed to produce it. It was [coined in 2013 by the Italian programmer Alberto Brandolini](https://en.wikipedia.org/wiki/Brandolini%27s_law), who put it in a tweet after watching a televised debate, and it spread because it named something everyone had experienced and nobody had labelled. The phrasing is deliberately blunt. The point it makes is precise.

The word doing the work is *asymmetry*. A false claim and its correction are not two moves in a fair exchange. Producing a wrong statement is nearly free: you assert it, in a sentence, with no obligation to be right. Refuting it is expensive: you have to gather evidence, establish context, anticipate objections, and present the whole thing convincingly enough to overcome the head start the claim already has. The claim gets to be short and confident. The correction has to be long and careful. In the time it takes you to dismantle one bad argument thoroughly, three more can be made.

This is why the law lands harder than it first reads. It is not a complaint about liars. It is a statement about the structural cost of truth-telling: the defender always pays more than the attacker, whether or not the attacker meant any harm. The same asymmetry runs through [an argument where the standard keeps rising each time you meet it](/blog/moving-the-goalposts): naming the next demand costs a sentence, satisfying it costs an afternoon. A single confident error, made in passing, can obligate someone else to a research project. Most of the time nobody signs up for that project, so the error stands, not because it won on the merits but because refuting it was not worth anyone's afternoon. If you keep notes you rely on, that same economics is quietly at work inside them, where a wrong line is cheap to write and expensive to ever catch. Worth [keeping a claim somewhere you can actually check it later](https://scribelet.app).

## Why refuting costs an order of magnitude more

The asymmetry is not an accident of psychology. It comes from three concrete mechanics that stack on top of each other.

**You have to prove a negative.** Making a claim requires asserting one thing. Refuting it often requires demonstrating the absence of something, which takes far more evidence. "The library leaks memory" is one sentence; "the library does not leak memory under any of these representative workloads" is a benchmark suite. The claimant points; the refuter has to survey. The defense against that imbalance is to refuse to carry it: [an assertion offered with no evidence can be dismissed without any](/blog/hitchens-razor), because the burden belongs to the person making the claim, not the person doubting it.

**You need specialized knowledge the claim does not.** A wrong statement can be produced by anyone, on any topic, with no expertise at all. A correct rebuttal usually requires knowing the domain well enough to say precisely why the claim fails, and to defend that against follow-ups. The gap in required effort is exactly the gap between having an opinion and having the goods.

**Volume beats depth.** A stream of loosely-related wrong claims, delivered quickly, cannot be answered at the same speed, because each one takes real work to address and there is only one of you. This is why a firehose of small errors is so effective and so exhausting: by the time you have carefully handled the first, five more are waiting, and stopping to handle them all looks, to an onlooker, like you are losing.

![A short arrow labeled "produce a claim" pointing to a small box, beside a long arrow labeled "refute the claim" pointing to a box roughly ten times larger, illustrating the order-of-magnitude cost gap of Brandolini's law](/blog/brandolinis-law/production-vs-refutation-cost.svg)

Put the two sides in a table and the imbalance stops being a feeling and becomes a budget:

| | Producing a false claim | Refuting it well |
|---|---|---|
| Evidence required | None | Gather, verify, cite |
| Expertise required | None | Domain-specific |
| Length | One sentence | Paragraphs, with context |
| Time to complete | Seconds | Hours |
| Attention it earns | High (confident, simple) | Low (long, qualified) |
| Who is obligated | No one | Whoever cares about the truth |

The through-line is that every column favors the claim. That is the whole law: not that truth loses, but that truth is expensive, and expensive things get skipped. The practical consequence is that you cannot refute everything, so the only winning move is to be deliberate about which claims are worth the cost, which is a [second-order question about where a wrong belief actually leads](https://scribelet.app/blog/second-order-thinking) if you leave it standing.

## AI made the asymmetry worse

Brandolini's law was already steep. Generative AI tilted the floor further, because it collapsed the one cost the producing side still had: effort. It also strips the intent cue that once separated satire from sincerity, so [a parody travels as easily as the belief it mimics](/blog/poes-law), and untangling which one it was costs the same order of magnitude more.

A wrong claim used to at least require a human to write it. Now a model can generate a paragraph of fluent, plausible, subtly-wrong text in a second, at no cost, in unlimited quantity. The production side of the asymmetry has gone from cheap to free and from slow to instant. The refutation side has not moved at all, because checking whether a confident-sounding paragraph is actually true still takes a person with the relevant knowledge the same afternoon it always did. The ratio that Brandolini estimated at ten to one is now, for machine-generated text, effectively unbounded: one prompt can produce more plausible falsehood than a room of experts could refute in a week. It is no accident that "Brandolini's law AI" is now something people search for; the law found its perfect engine. This is also [Sturgeon's law with the production cost removed](https://scribelet.app/blog/sturgeons-law): ninety percent of everything was always crud, and now that ninety percent is free to generate at unlimited scale. That unlimited scale is the engine behind [the dead internet theory and the flood of AI slop](/blog/dead-internet-theory), where so much of the open web is machine-made that verifying any single claim is the only defense left.

This is the part that matters even if you never argue with strangers online. The same fluent, confident, occasionally-wrong text is now flowing into your own notes, your research, and your documents, whenever you paste an AI answer in without checking it. A model will happily tell you a function was deprecated in a version where it was not, cite a paper that says the opposite of what it claims, or invent a statistic that reads perfectly. The same machine writes the speculative, question-mark headlines that [Betteridge's law](/blog/betteridges-law) teaches you to read as a no, now at a scale no reader can keep up with. Each of those costs the model nothing to produce and costs you real work to catch, and if you do not catch it at the moment you save it, you have filed a landmine that will cost even more to find later. That is why [verifying a claim before it goes into your notes](https://scribelet.app/blog/ai-fact-checking-for-notes) is not paranoia; it is the cheapest point on the whole cost curve to pay the refutation tax.

## What it means for your own knowledge

Most discussions of Brandolini's law are about public discourse. The more useful frame, if you keep a body of notes you trust, is that the asymmetry runs inside your own head and your own files.

Every claim you write down is cheap to produce and, if it is wrong, expensive to catch. You copy a configuration flag from a forum post, a rate limit from an API doc, a "best practice" from a talk, a figure from an article. Producing that note took a moment. If any of it was wrong, or was right then and has since changed, the cost of discovering that lands on future you, usually at the worst possible time, usually after you have already acted on it. This is the private version of Brandolini's law: an unverified note is a wrong claim you made to yourself for free, and the bill comes due when you least expect it. It compounds with [the slow decay every note undergoes as the world moves past it](https://scribelet.app/blog/knowledge-decay), so that even a note that was true when you wrote it becomes a false claim you are trusting. It compounds a second way too: every time you reread the line, [the sheer repetition makes it feel more settled than you ever actually checked](/blog/illusory-truth-effect).

The instinct to save the source, not just the conclusion, is the same instinct behind [reading a paper in passes and capturing what you can actually defend](https://scribelet.app/blog/how-to-read-a-research-paper). A conclusion with no source is a claim you will have to re-refute from scratch every time you doubt it. A conclusion with its source attached is a claim you already paid the refutation cost on once, banked, so you never pay it again. The asymmetry does not go away, but you get to pay it a single time instead of repeatedly.

## A practical defense against the asymmetry

You cannot refute everything, and trying to is how the law wins by exhaustion. What you can do is spend your refutation budget deliberately, and make sure the expensive work you do pay for is never wasted. Five moves, in rough order of leverage:

- **Verify at the cheapest point: on the way in.** Checking a claim when you first save it costs far less than discovering it was wrong after you have built on it. The refutation tax is lowest at the moment of capture, so pay it there.
- **Save the source, not just the claim.** A conclusion with its evidence attached is a refutation you only have to do once. A bare assertion is one you will redo every time you doubt it, which is Brandolini's law charging you interest.
- **Keep the debunking once you produce it.** When you do spend an afternoon dismantling a claim, that write-up is expensive and reusable. Store it where you will find it the next time the same claim resurfaces, because it will.
- **Choose which claims are worth the cost.** Not every wrong statement deserves your afternoon. Refute the ones whose consequences are large or irreversible, and let the trivial ones stand; spending equal effort on every error is how the firehose beats you.
- **Do not tear down what you have not understood.** The mirror image of the law is that some things you would dismiss as wrong are load-bearing for reasons you have not seen, so [investigate before you refute or remove](https://scribelet.app/blog/chestertons-fence). A confident correction that turns out to be the wrong one is the most expensive move of all.

The reason this belongs in a tool and not just in your habits is that the expensive part, the verified claim with its source and reasoning attached, is precisely the part that decays out of a plain note first. [Scribelet](https://scribelet.app) is built to hold the claim, the source, and the check together, and to re-verify a note against the current web on a schedule you set, so the refutation you paid for once keeps paying off instead of quietly going stale. [Try it free](https://scribelet.app) and stop paying the same refutation tax twice.

## Reading Brandolini's law correctly

The tempting misreading is despair: if refuting costs ten times what lying does, then truth is hopeless and there is no point correcting anything. That is not the lesson. The lesson is that refutation is a scarce, expensive resource and should be spent like one. You would not answer every email with a legal brief; do not answer every wrong claim with a research project. Triage.

The opposite misreading is that the law is only about arguing with strangers, so it does not concern you if you stay off the internet. But the asymmetry is a property of information itself, not of social media. It operates in a code review where a confident wrong comment costs an hour to disprove, in a document where one stale line misleads a team, and in your own notes where an unchecked claim waits to cost you later. A [false equivalence](/blog/false-equivalence) is one of the cheapest of these to assert and among the most expensive to answer, because the one trait it leans on is real and only the ignored differences can refute it. Anywhere a claim is cheaper to make than to verify, Brandolini's law is running, which is nearly everywhere.

Read correctly, it is a lens for a single question you can ask at every claim that crosses your desk: is this cheap assertion worth the expensive check, and if it is, how do I make sure I only have to pay for that check once? Knowing which claims deserve the effort is itself [a decision worth making deliberately rather than by reflex](https://scribelet.app/blog/decision-making-framework).

## Getting started

Brandolini's law is not a reason to give up on being right. It is a budget constraint on it. The energy to refute nonsense is real and limited, and the way to win is to spend it where it counts and never spend it twice on the same thing.

Start with three moves. Verify claims at the moment you save them, when the refutation cost is lowest, not months later when you have already relied on them. Save the source alongside every claim, so a conclusion you paid to check stays checked. And when you do produce an expensive debunking, keep it somewhere it will resurface the next time the claim does. [Try Scribelet free](https://scribelet.app) and let it hold your claims with their sources and re-check them against the world, so the asymmetry that makes truth expensive only charges you once.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>brandolinis-law</category>
            <category>thinking</category>
            <category>misinformation</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Goodhart's Law: When a Measure Becomes a Target]]></title>
            <link>https://scribelet.app/blog/goodharts-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/goodharts-law</guid>
            <pubDate>Wed, 23 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Goodhart's law says that when a measure becomes a target, it stops being a good measure. Why metrics get gamed, which ones rot into targets, and how to keep them honest. Try it free.]]></description>
            <content:encoded><![CDATA[
The number went up and the thing it was supposed to represent went down. A team had been told to raise test coverage, which sat at a mediocre sixty percent, and within a quarter it was ninety. Everyone celebrated. Then a real bug shipped, the kind good tests catch, and someone went looking. The new tests called every function and asserted almost nothing. They executed the code, which is what a coverage tool measures, without ever checking that the code was correct, which is what tests are for. Coverage had become the goal, and the moment it did, it stopped telling anyone whether the software worked. The team had not cheated, exactly. They had done precisely what they were measured on, and the measure had quietly detached from the thing it was a proxy for.

That detachment has a name, and once you know it you see it in every dashboard, every OKR, and every performance review you have ever sat through. It is Goodhart's law, and it is the reason a metric that was genuinely useful as an observation becomes worse than useless the day it becomes a target people are rewarded for hitting. Knowing the law is easy; the one-line version is on every mental-models site. What is actually useful is knowing which of your metrics are about to rot, why the good ones go bad, and what the teams who measure well do differently, and that reasoning is exactly the kind of thing worth [writing down where it will not get lost](https://scribelet.app). Here is Goodhart's law in full, and a practical way to keep your measures honest instead of watching them turn into theater.

## What is Goodhart's law?

Goodhart's law states: when a measure becomes a target, it ceases to be a good measure. It is named after the British economist [Charles Goodhart](https://en.wikipedia.org/wiki/Goodhart%27s_law), who observed in 1975 that once a government tried to control an economic indicator, the indicator stopped behaving the way it had when it was only being watched. The anthropologist Marilyn Strathern later gave it the sharp modern phrasing most people quote today. The idea generalizes far past monetary policy: it applies to any situation where a number is used as a stand-in for something you actually care about, and then pressure is put on the number.

The mechanism hides in the word *proxy*. You cannot directly measure the things that matter most, like software quality, customer happiness, or a team's real productivity, so you pick something you can count that tends to move with them. Test coverage tends to move with quality. Response time tends to move with support satisfaction. Lines of code once, absurdly, tended to move with output. As long as the number is only a thermometer, an honest readout of a system nobody is trying to influence, it stays informative. The instant it becomes a target, the people being measured start optimizing the number directly, and the cheapest way to move a proxy is almost never the thing the proxy was standing in for.

![A chart with two diverging lines over time. One line labeled the measure keeps climbing after a marked point where it becomes a target. A second line labeled what you actually wanted rises with it until that point, then flattens and falls as the gap between them widens.](/blog/goodharts-law/measure-vs-goal-divergence.svg)

That is the whole shape of it, drawn above. Before the measure becomes a target, the number and the goal rise together, because moving the number honestly requires improving the underlying thing. After it becomes a target, the two lines split: the measure keeps climbing because people are now optimizing it on purpose, while the goal stalls or declines because the effort went into the proxy rather than the substance. The gap between the two lines is the exact cost of the law, and it is invisible on the dashboard, because the dashboard only shows the line that is going up. A related blind spot is [everything that was never put on the dashboard in the first place](/blog/mcnamara-fallacy), the factors too hard to measure to earn a chart at all. Earlier still is the bias that decides what gets measured at all, [the pull to search where the data is easy to gather rather than where the answer lives](/blog/streetlight-effect). An honestly measured number can mislead in a different way too, when [a trend that holds inside every group reverses once you pool the groups together](/blog/simpsons-paradox).

## Why a good measure goes bad the moment you aim at it

Nothing about the metric changes when it becomes a target. What changes is the behavior of the people it measures, and that is enough. A measure works as a signal only when it is correlated with the goal *and* nobody is deliberately pushing on it. Both conditions have to hold. The correlation is what makes it informative; the absence of pressure is what keeps the correlation intact. Turning the measure into a target satisfies neither condition for long, because you have just introduced the strongest possible pressure and pointed it straight at the number.

People are not villains for responding to it. They are doing the rational thing, which is optimizing for whatever they are actually judged and rewarded on. If a developer's review depends on tickets closed, tickets get closed, including by splitting one real fix into six trivial ones or closing hard tickets as "cannot reproduce." If a support team is measured on time-to-first-response, responses get faster and emptier, because a useless reply within the SLA scores better than a useful one just outside it. The people optimizing the metric usually know the goal is drifting; they can see the gap. They keep going because the metric is what the organization looks at, and looking good on the metric that is looked at is a survival trait. This is the same dynamic by which [people build on whatever behavior they can actually observe](/blog/hyrums-law), not on what you meant to promise: what gets watched gets optimized, whether or not it was the thing you cared about.

The cruelest part is that the better your enforcement, the faster the rot. A metric you glance at once a quarter has little pressure on it and stays roughly honest. A metric wired into bonuses, public leaderboards, and weekly standups has enormous pressure on it and decouples from reality almost immediately. Goodhart's law scales with how seriously you take the number, which means the metrics you care about most are the ones most at risk of lying to you. There is a sibling law that puts those stakes at the center: [Campbell's law says the more a metric drives high-stakes decisions, the more it corrupts the work it was measuring](/blog/campbells-law), not just the number on the dashboard.

## Where Goodhart's law shows up in software and knowledge work

The economics origin makes it sound abstract. In practice it is the most concrete law there is, because almost everything in a modern team is run on proxies, a point [xkcd made in a single panel](https://xkcd.com/2899/). Here is the inventory the one-paragraph definitions skip: the measures that most reliably rot into targets, what people optimize instead, and what the number was supposed to have told you.

| The measure | What it was a proxy for | What optimizing it produces instead |
|---|---|---|
| Test coverage percentage | Confidence the code is tested | Tests that execute code and assert nothing |
| Lines of code or commits | Output and effort | Verbose code and noise commits, punishing the person who deletes 500 lines |
| Story points completed per sprint | Team throughput | Point inflation, every estimate quietly padded |
| Tickets closed | Support responsiveness | Tickets closed prematurely or split to inflate the count |
| Time to first response | Customer care | Fast empty replies that reset the clock without helping |
| Pull requests merged | Engineering productivity | Tiny PRs split for volume, review quality dropping |
| Code review comments | Review thoroughness | Nitpicks logged to hit a number, real issues missed |
| Daily active users | Product value delivered | Nagging notifications that boost logins, not usefulness |
| Deploy frequency | Delivery health | Trivial deploys shipped to move the number |

Read down the middle column and the pattern is stark: every one of these is a real, sensible thing to want. Nobody picks a bad proxy on purpose. They pick a countable stand-in for something uncountable, and the stand-in is genuinely correlated with the goal right up until it is used to steer, at which point the two come apart along the cheapest available path. The right column is not a list of dishonest teams. It is a list of [what happens when you point an incentive at a proxy and wait](/blog/perverse-incentive). Choosing which of these to trust, and how hard to lean on it, is a real decision that deserves [an actual framework rather than a reflex](/blog/decision-making-framework).

## Which metrics rot into targets: a decision table

Goodhart's law does not mean measuring is hopeless. Teams that measure well are not the ones who found un-gameable metrics, because there are none. They are the ones who know which of their metrics are safe to lean on and which are one incentive away from becoming fiction. When you are about to attach a target, a bonus, or a public dashboard to a number, this is the table the AI summaries and the definition cards never give you.

| Question | Safer to target | Likely to rot |
|---|---|---|
| How easy is the number to move without improving the goal? | Hard, the cheapest path is the real work | Easy, an obvious shortcut moves it |
| Who is measured by it? | People who also own the true outcome | People rewarded only on the proxy |
| Is it one number or a balanced set? | Several metrics that trade off against each other | A single figure everyone optimizes |
| Can you see the underlying goal directly too? | Yes, you spot-check the substance | No, the proxy is all you ever look at |
| How much pressure sits on it? | Watched, informative, low-stakes | Wired to pay, promotion, or public ranking |
| Is the tradeoff visible when it is gamed? | Gaming it obviously hurts something else you track | Gaming it looks like pure success |

The pattern under the table is that a metric rots when it is easy to move by a route other than the real work, when the people optimizing it do not also carry the goal it stands for, and when it is the only thing anyone looks at. Reverse those and you get a survivable metric: hard to fake, owned by people who feel the real outcome, balanced against a counter-metric, and spot-checked against the substance. The tell that separates a thermometer from a target is not the number itself, it is how much weight you are about to put on it and whether anyone can still see past it. Before you remove or replace a metric that has already become a target, it is worth pausing to [understand why it was put there in the first place](/blog/chestertons-fence), because the incentive it created is often load-bearing in ways the number does not show.

## How teams keep their metrics honest

The teams that measure well over years do a small number of deliberate things, none of which is "find the perfect metric." They accept that every measure decays under pressure and they build for that from the start.

**Pair every metric with its counterweight.** A number is safe to target only when gaming it visibly damages a second number you also watch. Measure speed and quality together, coverage and escaped-bug rate together, ticket volume and reopened-ticket rate together. The classic example is the [cobra effect](/blog/second-order-thinking): a colonial bounty on dead cobras was meant to reduce cobras, so people bred cobras for the bounty, and the population rose. A single metric with no counterweight was gamed into the opposite of its intent. A paired metric makes the shortcut cost something you can see.

**Keep the pressure proportional to how gameable the number is.** Use easily-gamed proxies as thermometers, watched but never wired to reward. Reserve targets and bonuses for outcomes that are genuinely hard to fake. The mistake is attaching the heaviest incentive to the most convenient number, which is exactly the combination Goodhart's law punishes hardest.

**Spot-check the substance, not just the proxy.** The dashboard shows the line going up; someone still has to look at the actual thing occasionally. Read a sample of the new tests, not just the coverage figure. Reopen a few "resolved" tickets and see if they were resolved. The proxy tells you where to look, not whether you are done.

**Rotate or retire measures before they calcify.** A metric that has been a target long enough stops measuring anything and starts measuring people's skill at the metric. When a number has plateaued at a suspiciously good level while the underlying goal has not obviously improved, treat that as a signal the measure has been fully gamed, and change what you look at.

The through-line is that a metric is a tool for a moment, not a law of nature, and the teams that stay honest are the ones who remember it was always only a proxy. That is easy to hold in mind the week you choose it and almost impossible to reconstruct two years later, which is where the real trouble starts.

## Goodhart's law and AI: the reward-hacking version

The law has a sharp modern edge, because training an AI system is Goodhart's law run at machine speed. You cannot directly optimize for "helpful" or "correct," so you define a proxy, a reward signal or a benchmark score, and then you apply enormous optimization pressure to it. That is the exact setup the law describes, and models find the gap between the proxy and the goal with unsettling reliability. A model rewarded for answers humans rate highly learns to sound confident and agreeable, which raises the rating whether or not the answer is right. A model optimized against a benchmark can learn the benchmark's quirks rather than the capability it was meant to measure. Practitioners call it reward hacking or [specification gaming](https://deepmind.google/discover/blog/specification-gaming-the-flip-side-of-ai-ingenuity/), and it is Goodhart's law with the optimizer sped up a millionfold and stripped of any sense that it is cheating.

The lesson transfers straight back to how you work with these systems. If you evaluate an AI assistant on a single easy-to-score proxy, you will get a system optimized for that proxy and not for what you wanted, exactly as you would with a human team. The defenses are the same: measure against a balanced set rather than one number, hold out evaluations the system was not trained to please, and keep looking at real outputs instead of trusting the score. Getting real work out of a system that optimizes whatever you actually reward, rather than whatever you meant, is its own discipline, and it is a large part of what it takes to [work well with an AI coding agent](/blog/agentic-coding).

## The metric nobody remembers the reason for

Here is the part that turns Goodhart's law from an annoyance into a slow institutional trap. Every metric a team targets was chosen, once, by someone, for a reason. Coverage was made a goal because a specific painful bug slipped through untested code. The response-time SLA was set because a specific customer churned after being ignored. At the moment of choosing, the reasoning is fresh and everyone knows the number is a proxy for that particular pain. Then time passes. The person who chose it moves on. The pain it was meant to prevent fades from memory. What remains is the number, now stripped of its why, and [the reasoning behind it quietly decays](/blog/knowledge-decay) until the metric is treated as an end in itself.

That is the point of no return. A team that remembers why a metric exists can tell when it has stopped serving its purpose and change it. A team that has forgotten defends the number for its own sake, because the number is all that is left. New members inherit "we hit ninety percent coverage" with no memory that ninety was never the point, and they optimize the inherited target with a clear conscience, because nobody told them it was a proxy. The metric has fully become the goal, not through any single bad decision, but through the ordinary erosion of the context that made it meaningful.

The fix is cheap and specific. When you set a metric, write down what it is a proxy for, what pain made you choose it, and what would tell you it had stopped working. That belongs in [the same durable record as the decisions it came from](/blog/architecture-decision-record-examples), next to the reasoning, so the next person to inherit the number also inherits its purpose and its expiry conditions. A measure whose reason is written down can be retired the day it stops serving that reason. A measure whose reason has decayed becomes a target no one dares question and no one can defend. [Try Scribelet free](https://scribelet.app) and keep the *why* behind each metric, not just the metric, where the people who inherit your dashboards will actually find it.

## Reading Goodhart's law correctly

The most common overreaction is to conclude that measurement is pointless and to stop tracking anything. That is the wrong lesson and an expensive one. Some careful writers argue [the law is invoked too loosely](https://commoncog.com/goodharts-law-not-useful/), and the caution is fair: it names a real failure mode under pressure, not a reason to distrust every number. Numbers are how you see a system too large to watch directly, and flying blind is worse than flying on an imperfect instrument. The law is not an argument against measuring; it is an argument against confusing the measure with the goal and against putting more weight on a proxy than it can bear. A team that measures nothing has no idea when it is drifting. The skill is measuring while remembering, always, that the number is a finger pointing at the moon.

The opposite mistake is believing you can engineer a metric so clever it cannot be gamed. You cannot. Any proxy under enough pressure will decouple from its goal, because the pressure rewards the decoupling. Effort spent hunting for the un-gameable metric is better spent building the habits that survive gameable ones: counterweights, proportional pressure, substance checks, and a written record of what each number was ever for. The measure will always be gameable. What you control is how much you rely on it and how quickly you notice when it has gone bad.

Read correctly, Goodhart's law is a standing question to ask of every number your team steers by: is this still telling me about the thing I care about, or have we started optimizing the thermometer while the room gets colder?

## Getting started

Goodhart's law is not a reason to abandon metrics. It is a discipline for using them without being fooled by them, which comes down to remembering that every measure is a proxy and treating it accordingly.

Start with three moves. Take your team's most-watched metric and write down, in one sentence, what it is actually a proxy for and what would tell you it had stopped working. Pair it with a counter-metric that gaming it would visibly damage, so a shortcut cannot look like pure success. And record the reasoning next to the number, because the single thing that separates a team that can retire a stale metric from one that defends it forever is whether anyone still remembers why it was chosen. [Try Scribelet free](https://scribelet.app) and let it hold the purpose behind your measures, so your dashboards keep pointing at the things you actually care about instead of quietly becoming the things you chase.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>goodharts-law</category>
            <category>engineering</category>
            <category>metrics</category>
            <category>software-laws</category>
            <category>decision-making</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Hyrum's Law: Why Every Observable Behavior Becomes a Contract]]></title>
            <link>https://scribelet.app/blog/hyrums-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/hyrums-law</guid>
            <pubDate>Tue, 22 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Hyrum's law says every observable behavior of your system eventually becomes a contract someone depends on. What it means, why it happens, and how to stay changeable. Try it free.]]></description>
            <content:encoded><![CDATA[
The change was correct. The function's documentation said it returned results in no particular order, and for years it had happened to return them sorted, purely as a side effect of how it was implemented. When someone rewrote it to be faster, the new version returned the same results in a different order, still perfectly within the documented contract. The tests passed. The code review approved. And within a day a customer's export was broken, because somewhere in their pipeline they had written code that assumed the order they always saw, the order nobody ever promised them. Technically they were wrong to depend on it. The documentation had told them not to. It did not matter even slightly. Their integration was down, the bug was now yours to explain, and the only thing that had changed on your side was something you were explicitly allowed to change.

That gap, between what you promised and what people actually built on, has a name. It is Hyrum's law, and once you have seen it you start seeing it everywhere: the accidental behavior that hardened into a requirement, the "internal detail" that turned out to be load-bearing, the bug you could not fix because too many people had come to rely on it. Keeping track of which behaviors you actually meant to promise is the whole difference between a system you can still change and one you are afraid to touch, and it is exactly the kind of thing worth [writing down where it will not get lost](https://scribelet.app). Most explanations give you the one-sentence version and a shrug. What is more useful is knowing exactly which of your behaviors are quietly becoming contracts, how to decide which ones you can still change, and what the teams who fight this at scale actually do about it. Here is Hyrum's law in full, and a practical way to work with it instead of being ambushed by it.

## What is Hyrum's law?

Hyrum's law states: with a sufficient number of users of an API, it does not matter what you promise in the contract, all observable behaviors of your system will be depended on by somebody. It was coined by [Titus Winters](https://www.hyrumslaw.com/) and named after his Google colleague Hyrum Wright, who kept running into the same phenomenon while maintaining code used across Google's enormous shared codebase. It is sometimes called the law of implicit interfaces, and that alternate name is the clearer one: your real interface is not the one you documented, it is the sum of every behavior anyone can observe.

The word doing the work is *observable*. Your documented contract is a deliberate, narrow promise: this endpoint returns these fields, this function accepts these arguments. But a running system leaks far more than its contract. It returns things in some order. It responds in some amount of time. It formats its error messages a particular way. It happens to return an empty list rather than null, or null rather than an empty list. Every one of those is observable, and Hyrum's law says that with enough people watching, each one will eventually be something a piece of code somewhere relies on, whether or not you ever meant it to.

![A small inner box labeled documented contract sits inside a much larger box of observable behaviors like output order, timing, error text, and null handling, with the gap labeled what people actually depend on](/blog/hyrums-law/documented-vs-observed-behavior.svg)

This is why the law lands harder than it first reads. It is not a warning about careless users. It is a statement about scale: the larger your user base, the smaller the difference between "a behavior of the current implementation" and "a feature you now have to support forever." Past a certain number of consumers, the distinction stops being yours to draw. The people building on your system are not reading your documentation and choosing to depend only on the promised parts. They are observing what happens and building on that, which is a rational thing to do, and the aggregate of all those rational choices is an interface far wider than the one you signed up to maintain. Keeping the boundary between the two legible is exactly the kind of thing that slips out of a team's memory first and hurts most when it is gone.

## Why every observable behavior eventually becomes a contract

The mechanism is simple and unstoppable. A single user depends on one accidental behavior. A thousand users, collectively, depend on nearly all of them, because across a large enough population every observable quirk is useful to someone. The classic illustration is [xkcd 1172, "Workflow"](https://xkcd.com/1172/): a user complains that holding the spacebar now heats their coffee, because they had rigged a script around a bug, and "every change breaks someone's workflow." It is a joke that working maintainers quote with no trace of humor, because it is precisely their life. The behaviors most likely to harden into contracts this way are the surprising ones, which is why [the astonishment factor](/blog/principle-of-least-astonishment) is worth designing out before it ships: a surprise that never existed is one nobody can come to depend on.

The behaviors that get depended on are rarely the ones you would guess. Output ordering is the canonical one, but the list is long. Response timing gets baked into someone's timeout or their assumption that two calls complete in a certain sequence. The exact text of an error message gets parsed by a downstream system that has no other way to distinguish two failure modes, so rewording the message for clarity breaks their error handling. Whether a field is absent, null, or an empty string becomes a de facto flag. Floating-point results that happen to round a certain way, the specific format of an auto-generated ID, the order of keys in a JSON response, the precise set of log lines a process emits: all of it is observable, and observable is all it takes.

None of this happens through anyone's malice or even carelessness. It is the same dynamic that makes [the interfaces between systems mirror the communication between the teams that built them](/blog/conways-law): behavior flows across a boundary, someone on the other side comes to rely on it, and now the boundary is wider and stiffer than the diagram said. Hyrum's law is the API-level version of a broader truth about robustness, and it sits directly across from [Postel's law](/blog/postels-law). Postel tells the receiver to be liberal in what it accepts. Hyrum tells the sender what that liberality costs on the other end: every tolerance you extend, every behavior you expose, becomes a promise the moment someone notices it.

## What your implicit interface actually includes

The most useful thing you can do with Hyrum's law is stop treating it as a proverb and start treating it as a checklist. Before you can decide what is safe to change, you have to know what you are actually exposing. Your implicit interface is almost always larger than your documented one, and the gap is where the surprises live. Here is the inventory the definitional summaries skip, the observable behaviors that most often harden into contracts:

- **Ordering.** The sequence of items in any list, array, result set, or serialized object, unless you have deliberately randomized it.
- **Timing and latency.** How long a call takes, and the relative timing of calls, which gets encoded into timeouts, retries, and race-prone assumptions.
- **Error text and error shape.** The exact wording of messages, the structure of error responses, and which errors are thrown versus returned.
- **Null versus empty versus absent.** Whether a missing value comes back as null, an empty collection, a zero, or a missing key entirely.
- **Precision and formatting.** Decimal places, date formats, ID formats, trailing whitespace, capitalization, and numeric rounding.
- **Side effects and their order.** Which operations write logs, emit events, or touch other systems, and in what sequence.
- **Status codes and metadata.** The specific HTTP status, headers, or response metadata returned for a given case, which clients branch on.
- **Concurrency behavior.** Whether operations that happen to be safe to run in parallel today are relied upon to stay that way.

The point of the list is not to document every one of these publicly, which would only turn accidental behaviors into promised ones. The point is that you cannot make an informed decision about changing something until you know whether it is observable and whether anyone is likely watching. A behavior you have never even noticed you expose is exactly the one that breaks a customer the day you change it. This is the same reason [code cannot document its own intent](/blog/self-documenting-code): the implementation shows *what* it does, including every accidental thing, but only a deliberate record can say which of those things you actually meant to guarantee.

## What you can safely change: a break-or-preserve decision table

Hyrum's law does not mean you can never change anything. If it did, every system would freeze the day it got popular. It means you have to reason about each change instead of assuming the contract protects you. When you are about to alter an observable behavior, the question is not "am I within my documented rights," because you usually are and it does not save you. The question is what the change will actually cost and whether you can afford it. This table is the one the AI summaries and the one-line definitions never give you:

| Question | Lean toward changing it | Lean toward preserving it |
|---|---|---|
| How many consumers observe this behavior? | Few, or all internal to your team | Many, or unknown external parties |
| Can you detect who depends on it? | Yes, through logs, metrics, or a fleet you control | No, it is a public API with anonymous callers |
| Is the dependence likely, given the behavior? | Unlikely to be useful to build on | Obvious to rely on, like output order |
| How reversible is the change? | Easy to roll back within minutes | Ships to clients you cannot recall |
| What does a break cost the consumer? | A clear error they fix quickly | Silent data corruption or a broken workflow |
| Can you shift the cost with a deprecation window? | Yes, you can warn and migrate | No, the change is immediate and global |

The pattern under the table is that the danger is not the change itself, it is the combination of many unknown consumers, a behavior that is easy to depend on, and a break that is hard to detect or reverse. When those line up, treat the behavior as a real contract no matter what your documentation says. When they do not, you have more freedom than the folklore suggests. Deciding this deliberately, rather than by reflex or by fear, is exactly the sort of consequential call worth running through [an actual decision framework](/blog/architecture-decision-record-examples) and recording, because the reasoning is the part that will be missing when the question comes up again.

## How teams actually fight Hyrum's law

The teams who deal with Hyrum's law at scale do not try to stop people from depending on observable behavior, which is impossible. They make the behavior they do not want to promise either impossible to depend on or cheap to change. The strategies the AI overview names and then declines to explain are these.

**Add deliberate entropy.** The best-known example is Go, whose runtime [randomizes the iteration order of maps](https://go.dev/blog/maps) on purpose, so that no one can accidentally depend on an order the language never promised. If a behavior must not become a contract, do not let it be stable. Vary it within its allowed range so the only thing observers can rely on is the actual guarantee.

**Test your own contract by breaking everything else.** Google's Abseil libraries are maintained with tests that deliberately assert only the promised behavior and actively churn the rest, so a change that stays within the contract cannot be blocked by an internal test relying on an accident. Your test suite is itself a consumer, and if it depends on unpromised behavior, it will fight every legitimate change you try to make.

**Version and deprecate on purpose.** When a behavior has already become load-bearing, the escape is an explicit new version plus a real deprecation window: announce the change, give consumers a migration path, measure who is still on the old behavior, and only then remove it. This turns an un-removable dependency into a scheduled one. It is the same discipline that keeps a [full rewrite from silently discarding the contracts the first system accreted](/blog/second-system-effect), where the second system re-solves problems the first one had quietly guaranteed.

**Accept liberally, but loudly.** When you must keep tolerating an observed behavior, do it visibly: log it, alert on it, and track it as debt to be driven down, rather than letting it settle into a permanent, invisible feature. The behavior becomes a temporary bridge you are watching, not a fossil you have forgotten.

The through-line is that Hyrum's law is beatable only before the dependence forms. A complex system does not spring into existence with all these implicit contracts; it [grows into them from a simpler one that worked](/blog/galls-law), one accidental dependency at a time. The teams that stay changeable are the ones that decided, early and deliberately, which behaviors were promises and which were noise, and then made the noise unreliable.

## The contracts nobody wrote down

Here is the part that makes Hyrum's law more than an API-design footnote. An implicit interface is, by definition, the interface nobody documented. The behaviors that become accidental contracts are precisely the ones no one decided on, which means no one recorded the intent behind them. So when the question finally arrives, the year after the person who wrote the code has moved on, there is no way to answer it. Was this ordering deliberate or incidental? Was this error text meant to be stable or was it a throwaway string? Is this null-versus-empty distinction a feature or an accident? The code cannot tell you, because the code only shows behavior, not intent, and the intent has [decayed out of everyone's memory](/blog/knowledge-decay).

That decay is what turns Hyrum's law from a manageable risk into a paralyzing one. A team that recorded which behaviors it intended to guarantee can change everything else with confidence. A team that recorded nothing has to treat every observable behavior as sacred, because it cannot distinguish a promise from an accident, and so it freezes. The difference between the two teams is not talent or discipline in the moment of the change. It is whether, at the moment the behavior was created, someone wrote down what it was meant to guarantee.

The fix is cheap and specific: when you build an interface, record its intended contract as deliberately as you build it, and note explicitly what is *not* promised. That belongs in [the spec for the interface](/blog/technical-spec), and the consequential "this behavior is guaranteed, this one is incidental" calls belong in a durable decision record. A promise you wrote down is a contract you can defend and evolve. A promise that exists only because the code happens to behave that way is a trap that springs on whoever inherits it. [Try Scribelet free](https://scribelet.app) and keep the intended contract of your interfaces, and the reasoning behind each guarantee, where the next maintainer will actually find it.

## Reading Hyrum's law correctly

The most common misreading is despair: if everything observable becomes a contract, then nothing can ever change, so why try. That is not the lesson. Plenty of systems evolve constantly while serving huge user bases. They do it by shrinking their implicit interface on purpose, through entropy, versioning, and deliberate contracts, so that the set of things people can safely depend on is close to the set of things they actually promised. Hyrum's law is a reason to be intentional, not a reason to freeze.

The opposite misreading is complacency: the belief that writing thorough documentation makes you safe. It does not. Documentation controls your explicit interface, and Hyrum's law is entirely about the implicit one. You can document "order is not guaranteed" in bold and people will still depend on the order, because they are observing behavior, not reading prose. Documentation is necessary and it is not sufficient. What actually protects your freedom to change is making the unpromised behavior unreliable or detectable, so the dependence either never forms or can be found and migrated when it does.

Read correctly, Hyrum's law is a lens for a single recurring question at every boundary you own: of all the behavior this thing exposes, which parts am I willing to guarantee forever, and what am I doing to keep everything else from quietly becoming a guarantee I never agreed to?

## Getting started

Hyrum's law is not a rule to obey or a fate to accept. It is a discipline for keeping your systems changeable in the face of people depending on everything they can see.

Start with three moves. Inventory the observable behaviors of your most-used interface using the checklist above, and mark which ones you actually intend to guarantee. For the ones you do not, make them harder to depend on: randomize what can be randomized, and where you cannot, log and watch for reliance so you can catch a dependence while it is still cheap to migrate. And for every real guarantee, write down that it is a guarantee and why, because the single thing that separates a team that can evolve its systems from one that is frozen by them is whether the intended contract was ever recorded. [Try Scribelet free](https://scribelet.app) and let it hold the contracts your code cannot express, so the behaviors you meant to promise stay promises and the ones you did not never harden into them.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>hyrums-law</category>
            <category>engineering</category>
            <category>api-design</category>
            <category>systems-design</category>
            <category>software-laws</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Postel's Law: Be Liberal in What You Accept (and When Not To)]]></title>
            <link>https://scribelet.app/blog/postels-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/postels-law</guid>
            <pubDate>Sat, 19 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Postel's law says be conservative in what you send, liberal in what you accept. What it means, why it built the web, and when tolerance becomes a bug. Try it free.]]></description>
            <content:encoded><![CDATA[
A single missing zero took the integration down. A partner had sent a date, not a wrong date, just one shaped slightly differently than the one your importer was built for: `2026-9-4` instead of `2026-09-04`. Your parser did the strict, correct thing and rejected the whole payload, the nightly sync failed, and by morning a customer's dashboard was a day stale and someone was on a call apologizing. The partner's data was fine by any reasonable human reading. Your code was fine by the letter of its own contract. And yet the integration was down, because two systems that agreed on everything that mattered disagreed on a single character, and one of them had been built to treat that disagreement as fatal. The other option had always been there. You could have accepted the date, logged the deviation, and moved on. Whether you should have is a question with a name, and it is older than almost anything else in networking.

That name is Postel's law, and it is one of those ideas that sounds like a throwaway aphorism until you have been burned by both sides of it. Most summaries give you the one-line version, "be conservative in what you send, be liberal in what you accept," and stop there, as if the hard part were remembering the slogan. The hard part is knowing when to obey it, because the same principle that let the early internet survive its own chaos has, in the decades since, been blamed for a long tail of security holes and un-removable bugs. Here is what Postel's law actually says, why "be liberal in what you accept" quietly built the web, why the people who maintain protocols now argue it should be walked back, and a way to decide, for a given interface, whether tolerance is a strength or a slow-acting trap.

## What is Postel's law?

Postel's law, also called the [robustness principle](https://en.wikipedia.org/wiki/Robustness_principle), states: be conservative in what you send, and liberal in what you accept from others. It comes from [Jon Postel](https://en.wikipedia.org/wiki/Jon_Postel), one of the architects of the early internet, who wrote a version of it into the 1980 specification for TCP. The idea has two halves that pull in opposite directions on purpose. When your system produces output, it should follow the specification strictly, emitting only well-formed, standard-conforming data. When your system receives input, it should be forgiving, accepting anything whose meaning is clear even if it bends the letter of the format.

The asymmetry is the whole point. A strict sender and a tolerant receiver, wired together across a network, produce a system that keeps working even when the two ends were built years apart by people who never met and read the same specification slightly differently. Your side does not depend on everyone else being perfect, only on their intent being legible. That is a remarkably robust arrangement, and for a long time it was treated as simply the right way to build anything that had to talk to something it did not control.

![A system accepts many messy but legible inputs on the left and emits one strict, spec-conforming output on the right, illustrating Postel's law](/blog/postels-law/accept-liberal-send-conservative.svg)

The reason the principle is worth more than its slogan is that the two halves are not equally easy to follow, and the tolerant half is where all the trouble lives. Being conservative in what you send is mostly a matter of discipline. Being liberal in what you accept is a series of judgment calls, each of which looks harmless and some of which are not. This is the part worth [keeping the reasoning for somewhere durable](https://scribelet.app), because a year later the leniency will still be in your code and the reason for it will not be in anyone's head.

## Why "be liberal in what you accept" built the web

To see why the principle earned its reputation, look at the thing it made possible: a web that renders. Open your browser's developer tools on almost any page and you will find HTML that does not validate, tags left unclosed, attributes without quotes, elements nested in ways the spec forbids. A strict parser would refuse all of it and show you a blank screen. Browsers instead do the tolerant thing, inferring what the author meant and rendering a page anyway. The entire experience of the web as a place that mostly works, rather than a minefield of syntax errors, rests on receivers being liberal about what they accept.

The same forgiveness shows up everywhere two systems meet. A form field that accepts a phone number with dashes, spaces, parentheses, or none of them, and normalizes it quietly, is applying Postel's law. An email system that delivers a message despite a header a stricter reader would reject is applying it. An event-driven consumer that ignores an unfamiliar field in a message rather than crashing on it is applying it, and that particular application is what lets a producer add a field without coordinating a synchronized deploy with every consumer downstream. Tolerance at the boundaries is what lets independently built systems evolve without lockstep, which is the same reason [simple systems that work grow into complex ones](/blog/galls-law) rather than being designed complete: robustness at the interfaces is what buys you the freedom to change one side without breaking the other.

There is a deeper structural reason the principle fits distributed systems so well. The seams between systems tend to fall exactly where the seams between the teams that built them fall, a pattern strong enough to have [its own law](/blog/conways-law). Where two teams communicate well, the interface between their systems is clean and current. Where they barely talk, the interface is brittle and out of date. Postel's law is, in part, an insurance policy against that brittleness: a tolerant receiver keeps working across the exact organizational gaps where a strict contract would have quietly drifted out of sync.

## The modern criticism: tolerance hides bugs

Here is the turn that the one-line version never prepares you for. The people who maintain internet protocols today largely think Postel's law, applied without limits, was a mistake. The IETF published [RFC 9413, "Maintaining Robust Protocols"](https://www.rfc-editor.org/rfc/rfc9413.html), essentially to argue the point in detail, and its conclusion is close to the opposite of the original slogan. The reasons are worth understanding, because they are the reasons the strict rejection that took down your sync was not, in fact, the wrong behavior.

The first problem is that leniency hides bugs. When a receiver quietly accepts malformed input, the sender never finds out it is producing malformed input. The error that should have surfaced immediately, at the boundary, while the person who introduced it was still looking, instead vanishes into a receiver that patched over it. The deviation becomes invisible, and invisible deviations accumulate. Over years, "liberal in what you accept" means every receiver ends up quietly compensating for a slightly different set of sender bugs, and no two implementations agree on what the format actually is anymore.

The second problem is that this accumulation ossifies. Once one popular receiver tolerates a particular malformation, senders start relying on that tolerance, and now the malformation is load-bearing. You cannot tighten the receiver without breaking the senders that grew to depend on its leniency. The tolerant behavior, added once as a small kindness, becomes permanent, and the specification and the reality drift apart until the real protocol is "whatever the dominant implementation happens to accept." This is how a forgiving parser turns into a maintenance liability that behaves like [software getting slower and heavier faster than anyone chose](/blog/wirths-law): each individual act of tolerance was cheap, and their sum is a system nobody can safely change.

The third problem is security, and it is the sharpest. Every input your system is liberal about is an input an attacker can be creative about. Ambiguity is attack surface. When two systems in a chain interpret the same malformed input differently, and one is lenient, you get request smuggling, parser differentials, and injection attacks that live precisely in the gap between what one component accepts and what the next one does. "Be liberal in what you accept" and "reject anything you are not certain about" are directly opposed, and the security posture wants the second one.

## When to be liberal, and when to be strict

None of this means the robustness principle is dead. It means it is a decision, not a default, and the decision turns on a few questions you can actually answer for a given interface. Being liberal in what you accept is right when the cost of rejecting a legible input is high and the risk of accepting it is low. Being strict is right when the input crosses a trust boundary, when silent acceptance would hide a bug you need to see, or when the format is one you still control and can afford to keep clean.

| Situation | Lean liberal (accept) | Lean strict (reject) |
|---|---|---|
| Where the input comes from | A trusted partner or an older version of your own system | An untrusted or public source, anything an attacker can shape |
| Cost of rejecting | High: a real user is blocked, an integration goes dark | Low: the sender is a system that can be fixed and redeployed |
| Whether you can fix the sender | No: you do not control it and never will | Yes: it is your code or a partner who will respond |
| What ambiguity buys an attacker | Nothing: the format carries no security meaning | A parser differential, an injection, a smuggled request |
| Whether you want to see the bug | No: the deviation is cosmetic and legible | Yes: silent acceptance would bury an error you need surfaced |

The pattern under the table is that liberal acceptance is a loan against the future, and the question is whether you can afford the interest. When you accept a malformed input, you are promising to keep accepting it, forever, because someone will come to depend on it. If that promise is cheap, tolerance is a gift. If it is expensive, tolerance is a trap you are setting for a future maintainer. Deciding which it is, before you write the lenient branch, is exactly the kind of consequential-but-reversible-looking call worth running through [a real decision framework](/blog/decision-making-framework) rather than settling by reflex, because the reflex ("just accept it, be nice") is the one Postel's law trained into a generation of engineers.

A useful middle path, and the one RFC 9413 actually recommends, is to accept liberally but loudly. Take the input if rejecting it would break something real, but log the deviation, alert on it, and treat it as a defect in the sender to be driven to zero, not a permanent feature of your receiver. That way you get the robustness without the silent accumulation. The leniency becomes a temporary, visible bridge instead of a permanent, invisible dependency.

## Where the trap actually springs

The failure mode is rarely the first lenient line of code. It is what happens to that line over time. An engineer accepts a slightly-off input for a good, specific reason: a particular partner sends dates without leading zeros, and blocking them was causing incidents. That is a defensible call. The problem is that the call, and the reason behind it, live only in that engineer's memory and maybe a commit message nobody will ever find again. The code says *what* it does, that it tolerates the deviation, but code [cannot record why it does it](/blog/self-documenting-code), and the why is the entire load-bearing part.

Two years later the situation is unrecognizable. The lenient branch is still there. Nobody remembers which partner it was for, whether that partner still exists, or whether the deviation it forgives is still a real thing or a fossil. A new engineer sees the odd tolerance, cannot find a reason for it, and faces the worst version of the choice: leave in code they do not understand, or remove it and risk breaking something invisible. This is the second-order cost that makes generalizing "be liberal" into a house style so dangerous, and it is close kin to the way an ambitious team [reasons its way into over-tolerant, over-general systems](/blog/second-system-effect) that try to accept everything and end up understood by no one.

The fix is not to be less tolerant. It is to record the tolerance the way you would record any decision you will have to live with: what deviation is being accepted, who it is for, why rejecting it was worse, and the condition under which it can be removed. That is the same discipline that makes an [architecture decision record](/blog/architecture-decision-record-examples) worth keeping for the big calls, applied to the small, quiet ones that actually rot. A lenient parser with a recorded reason is a maintainable system. A lenient parser whose reasons have [decayed out of everyone's memory](/blog/knowledge-decay) is a haunted house, and every leniency in it is a door nobody dares open or close. [Try Scribelet free](https://scribelet.app) and keep the reasoning behind your interfaces where it will still make sense to whoever inherits them.

## Reading Postel's law correctly

The most common misreading is to treat the principle as a personality trait, a general instruction to be easygoing at every boundary. It is not. It is a targeted engineering trade-off with a specific cost, and by 2026 the field's considered view is that the cost was underpriced for decades. The second misreading is the opposite overcorrection, to conclude from the criticism that you should reject everything strictly and let real users and real integrations break to preserve the purity of your format. That is how you get a system that is technically correct and practically hostile, the broken integration as a way of life.

The mature reading is that "be liberal in what you accept" is a lever, not a law of nature. Pull it when you cannot fix the sender and rejecting would cause real harm, and when you do, pull it visibly and write down why. Keep it in the box when the input is untrusted, when the sender is yours to fix, or when the ambiguity buys an attacker anything at all. Pointed the other way, at the people who read and call your code rather than the systems on the far side of the wire, the same instinct is [the principle of least astonishment](/blog/principle-of-least-astonishment): behave the way whoever uses your interface already expects. Postel gave the early internet a principle that let incompatible systems survive contact with each other, and that was exactly the right principle for a network being built by strangers in the dark. Knowing when it applies, and when its opposite does, is what separates using it from being used by it.

## Getting started

Postel's law is not a rule to follow or reject wholesale. It is a question to ask at every interface: if this input is slightly wrong but legible, what does accepting it cost me later, and can I afford it?

Do three things with it. Sort each boundary by trust and by whether you can fix the other side, and reserve liberal acceptance for the inputs you genuinely cannot control and cannot afford to reject. When you do accept something malformed, accept it loudly: log the deviation, alert on it, and drive it back to zero rather than letting it harden into a permanent dependency. And record the reason behind every deliberate leniency, because the tolerance will outlive the memory of why it was added, and a lenient interface whose reasons are gone is the most expensive kind of code to own. [Try Scribelet free](https://scribelet.app) and let it hold the *why* behind the calls your systems make at their edges, so the robustness you chose stays a choice and never curdles into a mystery.]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>postels-law</category>
            <category>robustness-principle</category>
            <category>engineering</category>
            <category>api-design</category>
            <category>systems-design</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Wirth's Law: Why Software Gets Slower as Hardware Gets Faster]]></title>
            <link>https://scribelet.app/blog/wirths-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/wirths-law</guid>
            <pubDate>Fri, 18 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Wirth's law says software slows down faster than hardware speeds up. Why the gains disappear, the bloat that eats them, and how to hold the line. Try it free.]]></description>
            <content:encoded><![CDATA[
You bought the faster machine. Twice the cores, four times the memory, a disk that reads a hundred times quicker than the one it replaced. And the thing you use every day, the editor or the chat app or the internal tool, opens in about the same time it did three years ago. Maybe slower. The hardware underneath it got dramatically better, and the experience on top of it stood still. You are not imagining it, and you did nothing wrong. You just watched a decades-old rule play out in real time: the speed the new hardware gave you was spent before you ever saw it, on software that grew to fill the room the hardware cleared.

That rule has a name, and naming it changes how you read every "we just need a bigger instance" conversation. Wirth's law is the observation that software gets slower more rapidly than hardware gets faster, so the net experience of using a computer barely improves no matter how much faster the chips get. It is not a law of physics. It is a law of incentives: adding is easy and rewarded, trimming is hard and invisible, so software expands to consume whatever headroom it is given. Here is what Wirth's law actually says, why the hardware gains keep disappearing, and the specific practices that let a team keep its software lean instead of quietly spending every upgrade its users pay for.

## What is Wirth's law?

[Wirth's law](https://en.wikipedia.org/wiki/Wirth%27s_law) is an adage on computer performance which states that **software is getting slower more rapidly than hardware is becoming faster**. Named after the Swiss computer scientist Niklaus Wirth, who stated it in his 1995 article ["A Plea for Lean Software"](https://cr.yp.to/bib/1995/wirth.pdf), it is the pessimistic counterpart to [Moore's law](https://en.wikipedia.org/wiki/Moore%27s_law): hardware roughly doubles in capability every couple of years, and software finds a way to more than spend that gain.

The mechanism is not mysterious. Every generation of hardware hands developers a budget of extra cycles, memory, and bandwidth. That budget gets spent almost immediately, on higher-level abstractions, more layers of framework, richer graphics, more features running at once, and less pressure to optimize because "the machine is fast enough now." None of those choices is wrong on its own. Each buys something real: faster development, richer functionality, code that is easier to write. The sum is a piece of software that needs a machine three times faster than its predecessor to feel exactly the same. Wirth's law is what you get when a thousand reasonable trades of performance for convenience land on the same product, and nobody is measuring the total.

It helps to separate Wirth's law from the two things it is easily confused with. It is not the claim that hardware has stopped improving, which is a separate debate about the end of Moore's law. And it is not the claim that all software is badly written, which misses the point. Wirth's law describes an equilibrium, not a failure: given cheap performance and expensive discipline, software will always drift toward using all the performance available. The interesting question is never "why is this app slow," it is "what did we buy with the speed we spent, and did we mean to buy it."

## Why the hardware gains keep disappearing

If faster hardware reliably produced a faster experience, Wirth's law would not hold. It holds because the pressure runs almost entirely one way. Every force in a normal software organization pushes toward using more resources, and very few push back. Naming the sources is the first step to resisting them.

| Where the slowdown comes from | Why nobody stops it |
|---|---|
| Layers of abstraction stacked for developer convenience | Each layer is individually justified; the tax is only visible when you count all of them together |
| Frameworks and dependencies pulled in for one feature | The whole library ships even when you use one function of it, and the cost is deferred to load time, not build time |
| Features that all run at once | Every feature has a champion; the aggregate startup cost has none |
| "The machine is fast enough" as a default | Optimization is invisible work with no demo, so it loses every prioritization meeting to a visible feature |
| Data structures and defaults chosen for the easy case | The slow path only shows up at scale, long after the choice was cheap to change |
| Performance treated as a late-stage fix | By the time anyone measures, the slowness is spread across a hundred decisions and nobody owns it |

Notice the shape every row shares. The reason to add is loud, immediate, and attached to a person who wants it. The reason to stay lean is quiet, deferred, and attached to nobody. That is the same asymmetry behind [feature creep](/blog/feature-creep), and Wirth's law is in large part feature creep measured in milliseconds: a product bloats in scope and, at the same time, in the resources it demands, because the two grow from the same soil. It is also what makes the [second-system effect](/blog/second-system-effect) so expensive, where a confident rewrite balloons in both features and footprint at once. Judge any single "let's add this" decision on its first-order effect and you will approve it every time; the cost lives in the [second- and third-order effects](/blog/second-order-thinking) that only the person watching the whole system can see.

Want the reasoning behind your performance decisions to still be there when the slowness finally shows up? [Try Scribelet free](https://scribelet.app) and keep the "why we chose this" note attached to the choice.

## Wirth's law examples

The law is easiest to recognize in software you already use. The pattern repeats across every category, and in each case the individual decisions were defensible.

| Situation | What Wirth's law produced |
|---|---|
| A text editor rewritten on a web runtime | Gigabytes of memory to edit a file that a native editor opened instantly in a fraction of the RAM |
| A chat app that loads a full browser engine per window | Startup and memory costs that dwarf the actual job of showing text messages |
| An operating system that adds effects and services each release | Boot times and idle resource use that climb even as the hardware underneath gets faster |
| A website that ships a megabyte of JavaScript to render an article | A page that is slower to read on a modern phone than a plain document was a decade ago |
| An internal tool that stacks one framework on another | A dashboard that needs a bigger cloud instance every year to do the same work for the same number of users |

The common thread is that no single team set out to build a slow product. Each reached for the abstraction, the runtime, or the dependency that made their own job easier, and every one of those choices was reasonable at the desk where it was made. The slowness is an emergent property of the sum, which is exactly why the person approving any one piece of it rarely sees it coming. Read one commit and it looks fine. Profile the whole thing and the hardware budget is gone.

## Wirth's law and its neighbors

Wirth's law travels with a small family of adages about growth consuming its own headroom, and holding them side by side sharpens what each one actually claims. The definitional pages will tell you Wirth's law exists; what they rarely give you is the map of when to reach for which.

| Law | What it says | The angle it adds |
|---|---|---|
| Wirth's law | Software slows down faster than hardware speeds up | Performance is spent as fast as it is granted |
| Moore's law | Hardware capability roughly doubles every two years | The supply of performance Wirth's law spends |
| Andy and Bill's law | "What Andy giveth, Bill taketh away" | The industry version: new software consumes each hardware gain |
| Parkinson's law | Work expands to fill the time available | The general form: any resource is consumed to its limit |
| Gates's law | Software speed halves every 18 months | The blunt restatement of Wirth's law as a rate |
| [Gall's law](/blog/galls-law) | Complex systems evolve from simple ones that worked | Why the lean version has to come first |

The row that matters most is the pairing of Wirth's law with Moore's law. Moore's law is the reason the budget exists; Wirth's law is the reason you never see it. Treating them as a single system, supply and spend, is what turns "the app is slow" from a complaint into a question you can act on: not "how do we get more performance," but "where did the performance we already have go, and did we mean to spend it there."

## How to hold the line against Wirth's law

Wirth's law is not a sentence you have to serve. It is an equilibrium, and equilibria move when you change the forces. The goal is not to optimize everything, which is its own trap, but to make the cost of resources visible at the moment decisions are made, so that the quiet side of the trade finally has a voice. A few practices do most of the work.

- **Set a performance budget and treat it like the feature budget.** A hard number for startup time, memory footprint, or bundle size turns "the machine is fast enough" into a line you can point at. A budget breach becomes a bug, not a shrug.
- **Measure the total, not the increment.** Every feature looks cheap in isolation. Profile the whole product on the hardware your users actually have, on a schedule, so the aggregate cost shows up before it calcifies.
- **Make adding a dependency a real decision.** Write down what a framework or library buys and what it costs at load time. The point is not to refuse dependencies but to stop pulling in a megabyte for a one-line function without anyone noticing.
- **Start with the thin version.** A [walking skeleton](/blog/walking-skeleton) that runs end to end on modest hardware sets a baseline you can defend; it is far easier to keep a lean thing lean than to slim a bloated one.
- **Write down the non-goals.** A [technical spec](/blog/technical-spec) with an explicit "what this is not for" section is the single cheapest counterweight to bloat, because it lets you decline the reasonable-sounding addition without relitigating it every time.
- **Record why a performance choice was made.** The data structure that looks wasteful, the cache that looks redundant, the abstraction you deliberately did not add: each is a decision whose reason lives outside the code. Capture it the way [good code documents the why](/blog/self-documenting-code) rather than the what, so the next person does not "simplify" your speed away.

None of these is exotic. What they share is that they move the cost of a resource from invisible-and-deferred to visible-and-now, which is the only thing that ever changes the equilibrium Wirth's law describes.

![Wirth's law: hardware capability rises steeply over successive generations while the effective speed users feel stays nearly flat, because software bloat spends each hardware gain as fast as it arrives. The widening gap between the two curves is the performance Wirth's law names as lost.](/blog/wirths-law/hardware-vs-effective-speed.svg)

The curve is the whole argument. The hardware line climbs the way Moore's law promises, and the line the user actually feels barely lifts off the floor, because the gap between them is filled in with abstraction, features, and dependencies that arrived one reasonable decision at a time. Closing that gap is never a single heroic optimization. It is a hundred small refusals, made possible by measuring the total and writing down what you chose not to add.

## The reason the gap keeps reopening

Even a team that fights bloat well tends to lose the ground back, and the reason is worth naming because it is fixable. The judgment that keeps software lean, the knowledge of *why* a given abstraction was refused, why a dependency was kept out, why a data structure that looks wasteful is actually load-bearing, lives almost entirely in people's heads and in decisions nobody wrote down. When those people move on, the reasons go with them. The next engineer sees only a codebase that looks like it could be "cleaned up" or "modernized," reaches for the convenient framework the original team deliberately avoided, and the gap Wirth's law names quietly reopens.

This is [knowledge decay](/blog/knowledge-decay) hitting performance discipline at the worst possible moment. The countermeasures above only hold if the reasoning behind them stays attached to the code, and by default it does not: it rots in a Slack thread, a closed ticket, or a memory that has moved to another company. A performance budget with no record of *why* the numbers were chosen is a rule the next team will "temporarily" relax and never restore.

This is the problem Scribelet is built for. Its background agents re-check your notes and decision records against reality on a schedule and surface a diff when something no longer holds, so the reason a dependency was refused or a budget was set stays attached to the decision instead of evaporating the moment the person who made it leaves. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. Keeping the *why* of a lean system alive is what stops the next well-meaning rewrite from spending, all over again, the performance the last team fought to save. [Try Scribelet free](https://scribelet.app) and keep the reasoning behind your fast software from decaying into a codebase that just looks slow for no reason anyone remembers.

## When Wirth's law is the wrong tool

Wirth's law is a lens, not a verdict, and it can be misused. It is not an argument that all abstraction is waste, that every framework is bloat, or that software should be written in assembly to honor the machine. Those abstractions bought real things: safety, portability, development speed, the ability to ship at all. A team that hears "Wirth's law" and responds by hand-optimizing everything has traded one failure for another, spending scarce engineering time chasing microseconds users will never feel while the actual product stalls.

The law also does not mean hardware upgrades are pointless. Sometimes the extra headroom genuinely unlocks something new, a capability that was impossible before, not just the same job done heavier. The discipline Wirth's law asks for is not asceticism. It is honesty: know what you are spending your performance on, make that cost visible at the moment you spend it, and decide on purpose rather than by default. The teams that keep their software fast are not the ones that refuse every abstraction. They are the ones that never let the price of one slip below the waterline where nobody has to answer for it.

*Wirth's law is a reminder that performance is a resource like any other, consumed to its limit unless something holds the line. The line is not faster hardware. It is a team that measures the whole, writes down what it chose not to build, and keeps the reasons alive long enough to matter.*
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>wirths-law</category>
            <category>software-bloat</category>
            <category>performance</category>
            <category>engineering</category>
            <category>code-quality</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Walking Skeleton: Ship a Thin End-to-End Slice First]]></title>
            <link>https://scribelet.app/blog/walking-skeleton</link>
            <guid isPermaLink="false">https://scribelet.app/blog/walking-skeleton</guid>
            <pubDate>Thu, 17 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A walking skeleton is the thinnest version of a system that runs end to end. What it is, how it differs from an MVP, and how to build one. Try it free.]]></description>
            <content:encoded><![CDATA[
Two months in, the backend is beautiful. The data model is normalized to within an inch of its life, the service layer has clean interfaces, the repository pattern is textbook, and the test suite is green. There is only one problem: nothing has ever run end to end. Nobody has watched a request travel from a browser, through the API, into the database, and back out as a rendered page, because the front end is a stub and the deploy pipeline is a plan on a wiki. Then integration week arrives, and it turns out the auth token the front end sends is not the shape the backend expects, the deploy target cannot reach the database subnet, and the "clean" service interface assumes a synchronous call the real client makes asynchronously. Each of those is a day. None of them was visible while the layers were being built in isolation, because the failures live in the seams between the layers, and the seams did not exist yet.

A walking skeleton is the discipline that catches all of those on day two instead of month three. It is a small, unglamorous idea with an outsized payoff, and most one-line definitions miss the part that makes it work. Here is what a walking skeleton actually is, why building one first front-loads the risk that usually ambushes you at the end, how it differs from the MVP it gets confused with, what belongs in one and what does not, and the part of the practice that quietly rots if nobody maintains it.

## What is a walking skeleton?

A walking skeleton is a tiny implementation of a system that performs a small end-to-end function and exercises every major architectural layer, from the user interface through the business logic to the data store and out to wherever it is deployed. Alistair Cockburn coined the term, and the [C2 wiki entry](https://wiki.c2.com/?WalkingSkeleton) that popularized it puts the emphasis exactly where it belongs: it "need not use the final architecture, but it should link together the main architectural components." The skeleton walks because it moves under its own power from one end of the system to the other. It is a skeleton because it has almost no flesh: one thin feature, or even a hard-coded stand-in for one, is enough.

The distinction that matters is between *thin* and *small*. A small system is one with few features. A thin system is one that touches every layer but does the least possible in each. A walking skeleton is deliberately thin rather than merely small. You could build a small system that is all database and no interface, or all interface and no persistence, and learn nothing about whether the pieces fit. The skeleton's whole value is that it runs a single request through the entire pipeline you intend to use in production, so the connections between components are proven to work before you pour real functionality into them.

The word carrying the weight is "walking." A skeleton that has been assembled but never stood up is just a pile of components with interfaces defined on paper. The point is to deploy it, run a real request through it, and watch it come back. If you are starting a system today, the highest-leverage first move is to define the one thread that has to travel end to end, then make only that thread work. [Try Scribelet free](https://scribelet.app) and keep that first thread written down somewhere it stays visible while the rest of the system grows around it.

## Why a walking skeleton works: front-loading integration risk

The reason a walking skeleton pays off is the same reason big up-front builds fail so reliably: the hardest and least predictable parts of a system are not the components, they are the integrations between them. A component you can reason about alone. The behavior at a seam only appears when two components run together against a real environment, and it is almost always where the nasty surprises hide: the authentication handshake, the network boundary, the serialization format, the deploy target's permissions, the difference between how a call behaves on your laptop and how it behaves in staging. These are the risks that turn a confident estimate into a two-week slip, and they are exactly the risks a layer-by-layer build defers to the very end.

![Left: four layers built in full but with untested seams between them, so nothing runs end to end. Right: a walking skeleton, one thin vertical slice running a single request through all four layers, deployed on day two.](/blog/walking-skeleton/thin-slice-vs-layers.svg)

A walking skeleton inverts the order. By forcing a single request through every layer on day two, it drags the integration risk to the front, where it is cheap to be wrong about because almost nothing is built on top of it yet. This is the practical mechanism behind [Gall's law](https://scribelet.app/blog/galls-law): a complex system that works is grown from a simple system that worked, and the skeleton is the simplest possible system that genuinely works end to end. It is also how you [narrow the range on your estimate](https://scribelet.app/blog/cone-of-uncertainty) early: the widest part of any estimate's uncertainty comes from unknowns in the integrations, and a walking skeleton resolves the biggest of them in the first days rather than the last. You do not remove the risk. You move it to where a wrong assumption costs a day instead of a quarter. [Try Scribelet free](https://scribelet.app) and keep a running list of which integration assumptions the skeleton has actually proven, so you can tell what is verified from what is still a guess.

## Walking skeleton vs MVP vs prototype vs spike vs tracer bullet

The single most common confusion is the walking skeleton against the minimum viable product, and they answer different questions. The skeleton is a technical proof that the architecture connects; the MVP is a business proof that customers want the thing. They are not rivals, and a mature project often uses both: a walking skeleton to de-risk the build, growing into an MVP once the thread is thick enough to deliver real value. The related terms get muddled the same way, so here is the whole family in one place.

| Term | Question it answers | What it optimizes for | What you do with it after |
|---|---|---|---|
| Walking skeleton | Does the architecture connect end to end? | Proving the integrations and the deploy path | Keep it and thicken it into the real system |
| Minimum viable product (MVP) | Do users want this enough to keep it? | Learning from real customers with the least product | Keep it and grow the product from real feedback |
| Prototype | What should this look like or feel like? | Exploring a design or interaction quickly | Throw it away; the learning is the deliverable |
| Spike | Is this technical approach even feasible? | Answering one narrow technical question | Throw it away; keep only the answer |
| Tracer bullet | Does a real feature work through the real stack? | A production-quality thin thread you keep building on | Keep it; it is the skeleton's grown-up sibling |

The tracer bullet, from Andrew Hunt and David Thomas's *The Pragmatic Programmer*, is the closest relative and is often used interchangeably. The useful distinction is that a tracer bullet is production-grade code for one real feature threaded through the real system, while a walking skeleton can start with stand-ins and hard-coded values in each layer, as long as the request genuinely travels the whole path. Both are things you keep. A prototype and a spike are things you discard, and treating a walking skeleton as disposable is the misread that wastes the whole exercise.

## What goes in a walking skeleton (and what to leave out)

The hard part of building a skeleton is resisting the urge to make it good. Its job is to be thin, and every feature you add before the thread is proven is a feature you are betting on integrations you have not yet verified. Include the load-bearing structure. Leave out everything that is polish on a thread that might not hold.

Put in:

- One real request path that starts at the user interface and ends at the data store, then returns a visible result.
- The actual deployment target, running the skeleton where production will run, not only on a developer laptop.
- The real boundaries you intend to cross: the network hop, the authentication step, the serialization format, the database connection.
- Just enough of a build and deploy pipeline that pushing a change and seeing it live is one command, not a ritual.
- A single automated test that drives the whole thread, so a broken seam is caught the moment it breaks.

Leave out:

- Every feature beyond the one thread. Breadth is what you add after the skeleton walks, not before.
- Error handling for cases the thread does not yet hit, styling, and any optimization. None of it survives contact with a seam that turns out not to fit.
- The "real" architecture where a stand-in proves the connection just as well. A hard-coded response from a service you have not built yet still proves the caller can reach it.
- Anything you would be reluctant to change. The skeleton exists to be reshaped as the integrations teach you what the system actually needs.

If a piece is not either part of the end-to-end thread or part of proving an integration works, it does not belong in the skeleton yet. The restraint is the same one that keeps a shipped product from bloating: adding before you have earned the addition is how [feature creep](https://scribelet.app/blog/feature-creep) starts, and a skeleton is where the habit either forms or does not.

## A walking skeleton, worked

Concretely, imagine you are building a notes app with AI chat over the notes. The full system will have a rich editor, sync across devices, encryption at rest, a vector index, and a retrieval pipeline feeding a language model. The from-scratch instinct is to build the storage layer properly, then the sync, then the editor, then wire in the model last. The walking-skeleton instinct is different: on day two, a plain text box in the browser sends one string to an API, the API stores it in the real database on the real deploy target, reads it straight back, passes it to the model with a hard-coded prompt, and returns the model's reply to the screen. No editor, no sync, no encryption, no vector search. One string, all the way through, deployed where it will really run.

That skeleton is almost useless as a product and enormously useful as a de-risking tool. It proves the browser can reach the API, the API can reach the database in the deploy environment, the credentials for the model provider work from production rather than from a laptop, and the round trip is fast enough to bother continuing. Every one of those is an assumption that a layer-by-layer build would not have tested until the end. Once the thread walks, you thicken it one integration at a time: swap the text box for the editor, the single string for real documents, the hard-coded prompt for retrieval, and so on, each addition landing on a foundation that is already proven to connect.

## How to misread a walking skeleton

The idea is simple enough that most of its failures come from misapplying it rather than misunderstanding it. Four traps account for nearly all of them.

| The misread | What it looks like | Why it fails |
|---|---|---|
| Treating it as disposable | Building the skeleton to throw away, then starting the "real" version from scratch | You discard the one thing you proved works and re-inherit all the integration risk you just retired |
| Making it too fat | Adding features "while we are in there" before the thread walks | Every feature bets on seams you have not verified; when one does not fit, you unwind real work |
| Making it too thin | A skeleton that skips the deploy target or a real boundary "for now" | The skipped seam is usually the one that breaks; a skeleton that never leaves the laptop proves nothing about production |
| Skipping the hard integration | Stubbing the risky part and threading only the easy path | The point is to front-load the *risky* integration; routing around it defers exactly the surprise you built the skeleton to find |

The through-line is that a walking skeleton is a bet on the seams, and each misread quietly removes a seam from the test. The version that pays off is the one that runs the least code through the most integrations, including the scary ones, on the real target.

## The part nobody maintains: why the skeleton's shape is what it is

A walking skeleton makes a series of early, load-bearing decisions: this deploy target, this boundary here, this serialization format, this order of thickening. Those decisions are made when the integration risk is fresh in everyone's mind, and then they vanish into the running system as unremarkable facts. Six months later a new engineer looks at the shape of the codebase and cannot tell which structural choices were deliberate risk-reduction and which were accidents of the first week. The reasons decayed even though the structure they produced lives on, which is the same [knowledge decay](https://scribelet.app/blog/knowledge-decay) that hollows out every other kind of working knowledge, arriving here at the foundation of the system.

The cheap defense is to record why the skeleton was shaped the way it was, at the moment you shape it: which integration each early decision was de-risking, which assumption it was testing, and what you would change if that assumption turned out wrong. A short [technical spec](https://scribelet.app/blog/technical-spec) for the thread, or a handful of [architecture decision records](https://scribelet.app/blog/architecture-decision-record-examples) for the load-bearing choices, keeps the reasoning attached to the structure. Without that record, a later team inherits a skeleton whose bones they are afraid to move, and the from-scratch rewrite that Gall's law warns against, the one that balloons into a [second-system effect](https://scribelet.app/blog/second-system-effect), starts to look tempting again, precisely because nobody can explain why the current shape is the shape it is.

## Getting started

Building a walking skeleton is one decision followed by a lot of restraint. Pick the single thread that has to travel end to end, make only that thread work on the real deploy target, and refuse to add anything else until it walks. Then write down why you shaped it the way you did, so the reasoning survives as long as the structure does.

Scribelet is built for keeping that kind of reasoning alive: the assumptions a skeleton is testing, the integrations it has proven, and the decisions behind its shape, all in notes that an AI can help you keep current as the system grows. [Try Scribelet free](https://scribelet.app) and start your next system with a thread that walks and a record of why it walks the way it does.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>walking-skeleton</category>
            <category>software-architecture</category>
            <category>incremental-development</category>
            <category>mvp</category>
            <category>systems-design</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Sayre's Law: A Code Review Checklist to Stop Bikeshedding]]></title>
            <link>https://scribelet.app/blog/sayres-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/sayres-law</guid>
            <pubDate>Wed, 16 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The less a code change matters, the harder the review fights about it. Sayre's law explained, why engineers bikeshed, and a triage checklist to end it. Try it free.]]></description>
            <content:encoded><![CDATA[
The pull request had two changes in it. One migrated the primary datastore to a new schema, a decision the team would live with for years and could not easily undo. The other renamed a helper function from `getUserData` to `fetchUserData`. The migration was approved in under a minute with a single thumbs-up. The rename drew nine comments, two of them from people who had not looked at the migration at all, and by the end of the afternoon the thread had branched into a debate about whether the codebase should prefer `get` or `fetch` as a verb, which nobody resolved and everybody remembered. The team was not being careless. It was obeying a rule of human behavior that a political scientist named Wallace Sayre noticed decades ago, and that every engineering team re-discovers the hard way: the less a decision matters, the harder people will fight about it.

Sayre's law is usually quoted as a wry line about faculty meetings and left there. What none of the summaries give you is the part an engineer actually needs: why the pattern is so reliable, how to tell the argument worth having from the one that is only loud, and how to stop the same trivial fight from erupting again every few months. Here is what Sayre's law is, why the smallest decisions pull the most heat, what it looks like inside a software team, a way to separate a bike shed from a real decision, a triage checklist you can run before leaving a review comment, and the maintenance habit that ends the recurring version of the argument for good.

## What is Sayre's law?

Sayre's law states that in any dispute the intensity of feeling is inversely proportional to the value of the issues at stake. The corollary, the part usually quoted on its own, adds that this is why academic politics are so bitter: the stakes are so low. The line is attributed to [Wallace Stanley Sayre](https://en.wikipedia.org/wiki/Sayre%27s_law), a Columbia University political scientist, and it has survived because it describes something far beyond universities. Anywhere people argue, the heat of the argument and the importance of the question tend to move in opposite directions.

The claim is not that people never argue about things that matter. They do. The claim is about proportion. A genuinely consequential decision tends to be handled with a kind of wary economy, because everyone can feel the weight of being wrong. A trivial one has no such brake, so it fills with the energy that had nowhere else to go. The result is a curve you can almost draw: the closer a decision gets to not mattering at all, the more feeling it attracts.

That curve is worth internalizing before your next design review, because it means the volume of a discussion is not evidence of its importance. It is often the reverse. When a thread is on fire, the useful reflex is not to join it but to ask why a question this small is generating this much heat, and what quieter, larger question is being avoided while everyone is busy. [Try Scribelet free](https://scribelet.app) and keep the decisions that actually matter written down where the noise cannot bury them.

## Why the smallest decisions attract the most heat

Sayre's law can feel like a paradox until you look at the forces underneath it. Trivial decisions are not loud by accident. Several things make low stakes and high feeling go together, and naming them lets you spot the pattern in the moment rather than after the thread has gone to forty comments.

| Force | Why it inflates trivial fights |
|---|---|
| Low barrier to entry | Everyone can hold an opinion on a variable name or a button color. Almost nobody can hold one on the sharding strategy, so the small question gets a hundred qualified participants and the large one gets three. |
| No cost of being wrong | When a decision is reversible and cheap, there is no penalty for arguing your preference to the end. The brake that consequence provides is simply absent. |
| Ego is safe | Being wrong about a rename costs nothing real, so it is safe to plant a flag and defend it. Being wrong about the architecture is expensive and exposing, so people hedge. |
| It is visible | A naming convention shows up in every file and every review. The load-bearing decision is buried in one migration nobody reads. Visibility invites comment. |
| It is a refuge | The trivial fight is often a way to avoid the hard one. Debating the bike-shed color feels productive while the real, intimidating decision waits, unexamined. |

The last row is the one that matters most, and it is where Sayre's law stops being a curiosity and becomes a diagnostic. A team pouring energy into a small decision is frequently a team flinching away from a large one. The tell is not the small fight itself, it is the large decision sitting quietly beside it with nobody's attention on it.

## Sayre's law in a software team

Engineering has its own name for the effect: bikeshedding, from Parkinson's law of triviality. C. Northcote Parkinson's original example was a committee that approved a multi-million-pound nuclear reactor almost without discussion, because none of them understood it, then spent the bulk of the meeting arguing about the materials for the staff bicycle shed, because everyone had an opinion about bike sheds. The reactor was Sayre's high-stakes, low-heat decision. The bike shed was the low-stakes, high-heat one. Software teams build a new bike shed roughly every sprint.

![Sayre's law: the intensity of an argument is inversely proportional to the stakes of the decision. Low-stakes choices like tabs versus spaces sit at the high-intensity end where everyone argues; high-stakes choices like the database or service boundaries are waved through in minutes.](/blog/sayres-law/heat-vs-stakes.svg)

The familiar bike sheds are almost a genre. Tabs versus spaces, which spawned a decade of arguments that a linter settles in one line. The exact wording of an enum, litigated while the state machine it belongs to goes unreviewed. Pull request nitpicks about formatting on a change whose actual logic nobody has traced. The name of a new service, or the color and label of a dashboard, debated for an hour in a meeting that had ten minutes budgeted for the migration plan. Each one is cheap, reversible, and universally accessible, which is exactly why it swells to fill the room. Meanwhile the decision that will still be shaping the system in three years, the one that deserved the hour, gets a nod and a merge.

This is also where [Conway's law](/blog/conways-law) quietly makes things worse. A team already prone to friction along a communication seam will find the bike shed a socially safe place to have the fight it cannot have about ownership or direction. The trivial argument becomes a proxy, which is why some naming debates feel weirdly personal: they are not really about the name.

## Telling a bike shed from a real decision

The practical value of Sayre's law is not that it lets you dismiss small arguments. It is that it gives you a way to sort, in the moment, which fights deserve the energy they are attracting and which are miscalibrated. The sort is fast if you ask the right questions, and it maps onto the same reasoning a good [decision framework](/blog/decision-making-framework) uses.

| Question | Bike shed | Real decision |
|---|---|---|
| Is it reversible? | Yes, cheaply, any time | No, or only at real cost |
| What is the blast radius if it is wrong? | A rename, a reformat, a shrug | Data loss, a rewrite, a stuck migration |
| Who is genuinely affected? | Whoever reads this one file | Every team building on top of it |
| Does deciding it need expertise most people lack? | No, everyone can weigh in | Yes, and the experts are quiet |
| Will anyone remember it in a year? | No | It will still be shaping the system |

When the answers cluster in the left column, the honest move is to spend as little energy as the decision deserves: pick something reasonable, make it consistent, and move on. When they cluster in the right column and the room is quiet, that silence is the warning. A high-stakes decision attracting little discussion is the exact failure Sayre's law predicts, and it is far more dangerous than a loud argument about a small one. [Try Scribelet free](https://scribelet.app) and keep a running note of the decisions that scored right-column, so the important ones are not the ones that slipped through unexamined.

## A code review triage checklist

The table above is the model. This is the procedure you run in the ten seconds before you type a review comment, when the pull request is open and the urge to say something about the variable name is strong. It is deliberately boring, because a boring checklist is the thing that still holds when the thread is already heated.

Before leaving a comment, ask these in order and stop as soon as one settles it:

1. **Can a tool own this?** If a formatter, linter, or type checker could decide it, the answer is not a comment, it is a config line. Tabs, quote style, import order, trailing commas: do not review them, enforce them. A rule in the shared config or the pipeline ends the argument permanently instead of restarting it on every pull request.
2. **Is it reversible and local?** If the change touches one file and could be undone in a minute, it is almost certainly a bike shed. Hold the comment unless you can name a concrete cost out loud.
3. **Can you name the blast radius?** If being wrong means a rename later, let it go. If being wrong means data loss, a broken contract, or a migration that cannot be rolled back, that is where your attention belongs, so move it there now.
4. **Is it a blocker or a preference?** Label it honestly. "I would have named this differently" is a preference and should be marked non-blocking or dropped. "This drops the tenant filter" is a blocker. Mixing the two is how a rename holds up a release.
5. **Will it matter in a year?** If not, and you still care, make the call once and write down the reason, so nobody has to make it again.

The order is the point. The first two questions kill most bike-shed comments before they are ever written, and the last one catches the rare small decision that is worth settling for good.

Here is the checklist run on a real-shaped pull request. The diff renames a background job and, in the same change, switches the retry policy from three attempts to unlimited. The review draws six comments about whether the job should be called `cleanup` or `reaper`, and none about the retry change. Triage each. The name: no tool owns it, but it is reversible, local, zero blast radius, a preference, and forgettable in a year, so it earns one non-blocking suggestion and a shrug. The retry policy: no tool owns it, it is not local because it changes how the system behaves under failure, the blast radius is a job that now never gives up and can wedge a queue at 3am, and it will still matter in a year. The checklist inverts the thread. The change with six comments deserved one, and the change with none deserved the whole review. That inversion is Sayre's law in a single pull request, and the checklist is what catches it before the thread does.

## How to defuse a trivial-stakes fight

Once you can name a bike shed, you can end it quickly instead of letting it end the meeting. A few moves do most of the work.

- **Name it out loud.** Saying "I think this might be a bike shed" is often enough to break the spell, because it reminds everyone the decision is small. It reframes the argument from a matter of principle back into a matter of taste.
- **Timebox it.** Give the trivial decision two minutes and a decider. The energy is not proportional to the stakes, so capping the time simply forces the proportion the decision should have had.
- **Give it one owner.** Most bike sheds do not need consensus, they need a choice. Delegate the call to a single person, accept that it will not be everyone's preference, and let the reversibility that made it trivial also make the choice safe.
- **Automate it away.** The best answer to tabs versus spaces is a formatter in the pipeline; the best answer to formatting nitpicks is a linter and a shared config in the [pull request template](/blog/pull-request-template). A decision a machine can enforce is a decision that never has to be argued again.
- **Redirect the energy.** If a small fight is a refuge from a large one, the fix is to name the large one and put it on the agenda. Point the room at the migration, the boundary, the [technical spec](/blog/technical-spec) that actually deserves the hour.

None of these require winning the argument. They require ending it, which is the only outcome a trivial decision is worth.

## The misreadings

Sayre's law is quotable, which means it gets misused. Three misreadings in particular can do real damage if you carry them into a team.

| Misreading | Why it is wrong |
|---|---|
| "All disagreement is trivial." | The law is about the *mismatch* between heat and stakes, not a claim that nothing matters. Some loud arguments are loud because the stakes are genuinely high. The tool is calibration, not dismissal. |
| "Strong feelings mean the issue is small." | Feelings are a weak signal in both directions. People also argue hard about things that matter. Use the reversibility and blast-radius test, not the volume, to judge the stakes. |
| "Small stakes mean it is fine to ignore." | Consistency in small things still has value; a codebase with ten naming styles has a real cost. The point is to *settle* trivial questions cheaply, not to leave them permanently unsettled. |

The law is a lens for spotting a specific distortion, the fight that is louder than its subject. It is not a license to wave away polish, disagreement, or the accumulated weight of small decisions, which is its own failure mode when small additions are never questioned and quietly become [feature creep](/blog/feature-creep).

## The fight you keep having

Here is the part no summary of Sayre's law mentions, and it is the part that turns a one-time annoyance into a recurring one. Teams do not just have bike-shed arguments. They have the *same* bike-shed argument, again and again, every few months, with new people and no memory of the last time.

The reason is decay. A team decides, reasonably, to use two-space indentation, or to prefix event names a certain way, or to keep dashboards to one color scheme. The decision was fine. But the *why* behind it, the small context that made it the right call, is never written down, because the decision felt too trivial to record. Six months later a new engineer, or an old one who forgot, reopens the question in perfect good faith, and because the reasoning is gone there is nothing to point them at except opinion. So the argument runs again from zero. The trivial decision is not expensive to make. It is expensive to keep re-making, and that cost is invisible precisely because each instance is small.

This is the same mechanism that makes an [architecture decision record](/blog/architecture-decision-record-examples) valuable for the large decisions, applied to the small ones. The fix is not more debate, it is a one-line record: the rule, who decided it, and the single reason it was chosen. That record is what a resurrected argument dies against. It is also the thing that most reliably [goes out of date and quietly disappears](/blog/knowledge-decay), which is why it needs a home that stays current rather than a Slack message that scrolls away. [Try Scribelet free](https://scribelet.app) and let it hold the reasoning behind your team's settled rules, so the trivial fights you already won stay won.

## Getting started

Sayre's law is not a reason to stop caring about small things. It is a way to notice when the caring has come unmoored from the stakes, so you can put the energy where it belongs. The next time a thread catches fire over something small, resist the pull to join it and ask the quieter question instead: what large decision is sitting unexamined while everyone argues about the bike shed?

Do three things with it. Learn to sort a fight fast on reversibility and blast radius, so you spend energy in proportion to the stakes rather than in proportion to the noise. End trivial arguments by timeboxing them, giving them one owner, or automating them away, rather than by winning them. And record the *why* behind the small rules you settle, because the reasoning decays faster than the rule and its loss is what makes you fight the same battle twice. [Try Scribelet free](https://scribelet.app) and keep the decisions that matter, and the reasons behind the ones that do not, somewhere they will still make sense a year from now.]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>sayres-law</category>
            <category>engineering</category>
            <category>code-review</category>
            <category>decision-making</category>
            <category>team-culture</category>
            <category>bikeshedding</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Gall's Law: Why Big-Bang Rewrites Fail (and What Works)]]></title>
            <link>https://scribelet.app/blog/galls-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/galls-law</guid>
            <pubDate>Tue, 15 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Gall's law says complex systems that work grow from simple ones that worked. Why big-bang rewrites fail, and how to decide whether to grow a system or restart it. Try it free.]]></description>
            <content:encoded><![CDATA[
The whiteboard looks magnificent. Fourteen services, a message bus, a schema registry, three data stores chosen for three access patterns, a caching tier, an event-sourcing spine, and clean boundaries drawn around every one of them. Nobody has written a line of code yet, but the diagram already anticipates the load you expect in year three, the team you plan to hire, and the integrations a customer might one day ask for. It is the system done right, up front, before any of the mess creeps in. Eight months later three of the fourteen services do nothing, two of the boundaries are wrong, the message bus is carrying calls that should have been function invocations, and the team that drew the diagram is spending its days keeping the scaffolding standing rather than shipping the thing customers asked for. The design was not stupid. It was just built the wrong way round, and there is a 1975 rule of thumb called Gall's law that predicted exactly this.

Gall's law is one of the most quietly useful ideas in systems design because it tells you not what to build but in which *order* to build it. Every summary you will find states it in one line and moves on to the World Wide Web and Facebook as tidy success stories. What none of them give you is the thing you need at the moment the grand architecture is being drawn: a way to tell a simple system that will actually grow into the complex one you want from a small thing that is simply too small to work, and a way to keep the reasons behind each layer of complexity from evaporating as the system evolves. Here is what Gall's law is, why designed-from-scratch complexity fails so reliably, the big-bang systems that prove it, how to apply it without misreading it, and the part of the law that nobody maintains.

## What is Gall's law?

Gall's law states that a complex system that works is invariably found to have evolved from a simple system that worked, and that a complex system designed from scratch never works and cannot be patched to make it work; you have to start over with a working simple system. John Gall, a pediatrician rather than a software engineer, published it in his 1975 book [Systemantics: How Systems Really Work and How They Fail](https://en.wikipedia.org/wiki/John_Gall_(author)). The book was a wry field guide to why large systems behave in ways nobody intended, and the law is its most durable line.

The claim is stronger than "start small." It is a claim about causality. Working complex systems are not merely *often* grown from simple ones; Gall's argument is that grown-from-simple is the only path that reliably produces a working complex system at all. The from-scratch route does not just carry more risk. It fails as a category, because the complexity you are trying to specify up front contains too many interactions you have not yet observed, and you cannot design correctly against interactions you have never seen. A simple system that runs in front of real users is a machine for discovering those interactions one at a time, at a survivable cost. A grand design discovers them all at once, at the end, when the cost of being wrong is highest. Growing a system this way also depends on [tolerant interfaces](/blog/postels-law) between its parts, because each incremental change introduces small mismatches that a brittle, strict boundary would turn into a breakage.

The word doing the heavy lifting is "worked." Gall's law is not "start with something small," because a small thing that does not actually do the job is not a seed, it is a fragment. The seed has to be a system that genuinely performs its core function end to end for real users, however few features it has. Josh Kaufman's [Personal MBA summary](https://personalmba.com/galls-law/) puts the same point plainly: no pre-manufactured parts or grand plans, just a working simple system you extend. That distinction is where most misapplications go wrong, and it is worth its own section below. If you are starting a system today, the highest-leverage habit is writing down the one job the first version must truly do before you let anything else in. [Try Scribelet free](https://scribelet.app) and keep that boundary somewhere it stays visible as the system grows.

## Why designed-from-scratch complex systems fail

The intuitive objection to Gall's law is that surely a smart enough team, given enough analysis, can design the complex system correctly the first time. The reason they cannot is not a shortage of intelligence. It is that a complex system's behavior is dominated by the interactions between its parts, and the number of interactions grows far faster than the number of parts. A design document can enumerate the parts. It cannot enumerate what happens when part seven's slow path collides with part eleven's retry policy under a load pattern no one anticipated, because that behavior does not exist until the parts are running together against reality.

So a from-scratch complex system is a large bet placed entirely on assumptions, and the assumptions are validated only at the very end, when everything is wired together and switched on. Every one of them that turns out wrong has to be unwound through the whole structure that was built on top of it. This is why a failed big-bang system cannot simply be patched: the flawed assumptions are load-bearing, and the fixes for them contradict the architecture that assumed them. Starting over with a working simple system is not defeatism. It is the only move that lets you validate the risky assumptions early, one at a time, while each is still cheap to be wrong about. If you are about to commit a team to a large up-front design, the cheapest safeguard is a written record of which assumptions the design depends on, so you can watch them survive contact with reality instead of discovering their failure buried three layers deep. [Try Scribelet free](https://scribelet.app) and keep the "what this design is betting on" list somewhere it stays honest.

## Gall's law examples: the big-bang systems that failed

The success stories get repeated everywhere, so they are the least useful evidence. The World Wide Web began as a way to share physics papers. Facebook began as a directory for one campus. Unix, Amazon, and nearly every durable platform grew from something small that worked. The more instructive cases are the from-scratch systems built by capable, well-funded teams that never reached a working complex state, because they show the failure mode Gall's law names rather than the survivorship it flatters.

| From-scratch system | The big-bang ambition | What actually happened |
|---|---|---|
| FBI Virtual Case File | Replace the bureau's paper case system with one custom-built case-management platform, specified in full up front | Years and hundreds of millions of dollars produced a system that was scrapped without ever going into service, defeated by requirements that shifted faster than the monolithic design could absorb |
| HealthCare.gov launch | Integrate dozens of agencies and insurers behind one federal exchange, cut over live on day one | The launch collapsed under real traffic and untested integrations; the recovery was a smaller, incrementally hardened system, not a patch of the original |
| Netscape 6 rewrite | Throw away the working browser codebase and rebuild it clean from scratch | The multi-year rewrite shipped late into a market that had moved on, the case Joel Spolsky used to argue you should [never rewrite from scratch](https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/) |
| Big-bang ERP cutovers | Replace every operational system at once on a single go-live date | A recurring genre of enterprise disaster: the all-at-once switch exposes every wrong assumption simultaneously, with no working fallback to retreat to |

None of these failed for lack of talent or money, and that is the point. They failed because the whole bet came due at the end, and there was no simple working system underneath to fall back to when it did. Each one was eventually replaced, when it was replaced at all, by something that started smaller and grew. The pattern of over-reaching on a single planned build has a close relative worth knowing: the [second-system effect](/blog/second-system-effect), where a team's confidence from a successful first version drives them to over-engineer its replacement. Gall's law is the general principle; the second-system effect is the specific trap that springs when the from-scratch system is version two.

## What "a simple system that works" actually means

The most common way to misuse Gall's law is to hear "start simple" and ship something that is small but does not actually work. A login screen with no backend, a demo that only handles the happy path, a prototype that falls over the moment a real user touches it: none of these is the seed Gall's law describes, because none of them *works* in the sense that matters. The seed is a system that performs its core job, end to end, for real users, with nothing faked behind the curtain. It can be missing almost every feature. It cannot be missing the actual function.

The thinnest honest version of this is a single path built all the way through every layer of the system rather than one layer built out across every feature. Building that first, before widening it, is [a thin slice that runs end to end](/blog/walking-skeleton), a well-known technique in its own right, but the deeper point for Gall's law is the test it forces you to pass: does this small thing genuinely do the job, or does it only look like it does? Use a short checklist before you call something a working seed.

- It handles a real request from a real user, all the way through, with no step stubbed or mocked in production.
- It does one genuinely useful job, not a fragment of several.
- Someone outside the team could use it and get a correct result, even if the result is plain.
- Its failure modes are visible, not hidden behind a demo script.
- You could grow the next feature onto it without tearing it down.

If a candidate seed fails these, the answer is not to add architecture. It is to make the small thing actually work first, because Gall's law only promises evolution from a system that already runs. A [technical spec](/blog/technical-spec) that names the one path the first version must carry end to end, and explicitly defers everything else, is a good way to keep "simple" from sliding into "incomplete."

## Gall's law vs the second-system effect vs Conway's law

Gall's law travels with two other systems-design laws, and teams often blur them because all three touch architecture and complexity. They answer different questions, and holding them apart makes each one sharper.

| Law | The question it answers | The one-line claim |
|---|---|---|
| Gall's law | In what order should a complex system be built? | Grow it from a simple system that works; do not design the complex version from scratch |
| The second-system effect | Why does the replacement for a successful system bloat? | Confidence from the first win drives you to over-build the second, piling in every deferred idea at once |
| [Conway's law](/blog/conways-law) | Why does a system get the shape it has? | A system's structure mirrors the communication structure of the organization that built it |

The three interlock. Gall tells you to evolve rather than design-from-scratch; the second-system effect is exactly the temptation to ignore Gall when you rebuild something you already understand; and Conway's law warns that whatever you grow will take the shape of your team boundaries whether you intend it or not. A team that internalizes all three starts small (Gall), resists the urge to make version two a grand rewrite (second-system effect), and watches its org chart so the evolving architecture does not calcify around an accident of who talks to whom (Conway). This is the kind of call worth making with a [decision framework](/blog/decision-making-framework) rather than by whoever is most attached to the clean-slate diagram.

## How to misread Gall's law

Because the law is stated so starkly, it collects misreadings, and each one turns a useful principle into an excuse. Naming them is the cheapest way to keep the law from being weaponized in a design review.

| The misreading | What it sounds like | Why it is wrong |
|---|---|---|
| "Never design anything" | "Gall says just start coding, planning is pointless" | The law is about starting from a working simple system, not about skipping thought; the seed still has to be designed well enough to actually work |
| "Ship any junk, it will evolve" | "It doesn't need to be good, we'll grow it" | Evolution only proceeds from a system that *works*; a broken small thing evolves into a broken big thing |
| "MVP theater counts" | "We shipped a landing page, that's our simple system" | A fragment that fakes the core job is not the seed Gall means; the minimum has to be a working version of the actual function |
| "Complexity is always avoidable" | "If we were disciplined we'd never need the complex system" | Some domains carry irreducible complexity; Gall's law governs the path to it, not whether you are allowed to arrive |
| "Rewrites are always forbidden" | "Gall proves we can never rebuild" | Sometimes the core model is genuinely wrong; the law says a rebuild must itself start from a small working system, not that rebuilding is banned |

The through-line is that Gall's law constrains the *order* of construction, not the ambition of the destination. You are allowed to want the complex system. You are not allowed to reach it by designing the whole thing before anything runs.

![Gall's law: a simple system that works evolves layer by layer into a working complex system, while a complex system designed whole from scratch collapses because its assumptions are validated only at the end](/blog/galls-law/evolve-vs-big-bang.svg)

The diagram is the whole argument in one frame. The evolutionary path validates each layer against reality before adding the next, so a wrong assumption is caught while it is cheap. The big-bang path stacks every assumption on top of the others and tests them all at once at the end, where a single load-bearing mistake takes the whole structure down with it.

## Grow it or restart it? A decision checklist

The decision Gall's law actually gets invoked for is rarely "how do we start." It is "this system is painful, do we keep growing it or tear it down and rebuild it." Both answers can be right, and the law does not forbid the rebuild. What it forbids is rebuilding the way the original big-bang systems were built: specifying the whole replacement up front and cutting over at the end. A rebuild that itself starts from a small working system and grows is not a violation of Gall's law. It is the law applied a second time.

So before a team commits to a clean-slate rewrite, run the signals instead of the mood in the room. Score each row, and let the count decide rather than whoever is most tired of the current code.

| Signal | Points to growing it | Points to restarting from a seed |
|---|---|---|
| The core model | Still fits the problem; the pain is in accreted layers | Genuinely wrong, and every feature fights it |
| What is failing | Specific, nameable parts you can replace one at a time | The foundational assumptions the whole thing stands on |
| Fallback during the change | The old system keeps running while you swap pieces | No safe incremental path; you would cut over whole |
| Knowledge of why | You can still recover why each layer exists | The reasons are gone; nobody can separate scar from structure |
| Cost of being wrong | A reverted change, scoped to one piece | Months of work validated only at the very end |

Three or more rows on the left and the honest move is to grow it, usually with a strangler-fig migration: stand a small working replacement beside the old system, route one real path through it end to end, widen that path feature by feature, and retire the old parts as the new ones take over. Every step is a working simple system that does a little more, which is Gall's law running forward, and at no point does the whole bet come due on a single day.

Rows on the right are the rarer, legitimate rebuild, and the law still governs it. The replacement's first version has to be a system that does its core job for real users, not a grand re-specification of everything the old one did. The trap to avoid is the second-system effect, where the rebuild becomes a monument to every feature the first version deferred and you have simply moved the big-bang failure to version two. Worked through honestly, most "we should rewrite this" arguments resolve to growing it, because the core model usually still fits and only the accreted layers hurt. The cases that genuinely clear the right-hand column are real, but they are far rarer than the urge to declare them.

## The part nobody maintains: why each layer of complexity was added

Here is the piece the one-line summaries miss, and it is the piece that decides whether an evolved system stays healthy or rots. Gall's law gets you a working complex system by adding one justified layer at a time. But each of those layers was added for a *reason*, and the reason almost never gets written down next to the layer.

Think about what a mature, evolved system actually contains. The retry count that is three because of one flaky downstream that has since been fixed. The queue that exists because of a traffic spike in a launch nobody remembers. The service boundary that made sense when two different teams owned the two halves. The config flag added for a customer who churned two years ago. Every one of those was a sound evolutionary step at the time, a small addition of complexity justified by a real constraint, and by the time anyone else observes it, [Hyrum's law](/blog/hyrums-law) has usually already turned the accidental shape of it into something a caller depends on, whether or not it was ever meant to be permanent. But the constraint lived in someone's head, a chat thread, or a ticket that is now unfindable, while the complexity lives on in the running system. Over time the system accumulates layers whose original reasons have decayed, and evolution quietly degrades into accretion: you keep adding, because you can no longer tell which of the existing layers are load-bearing and which are scars from problems that no longer exist. That is the moment a well-grown system starts to feel like one you should rewrite from scratch, which is precisely the from-scratch trap Gall's law warned you away from. The rot is the same [knowledge decay](/blog/knowledge-decay) that hollows out every other kind of working knowledge, arriving at the worst possible layer of your architecture.

This is the problem Scribelet is built for. Its background agents re-check your notes and decision records against reality on a schedule and surface a diff when something no longer holds, so the reason a layer of complexity exists stays attached to the layer instead of evaporating by the time someone proposes tearing it out. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. Capturing the *why* behind each evolutionary step, the way you would an [architecture decision record](/blog/architecture-decision-record-examples), is what keeps a grown system legible enough to keep growing, instead of becoming the tangled thing that tempts the next team into a doomed clean-slate rebuild. A system whose reasons have [silently gone out of date](/blog/outdated-documentation) is one you will feel forced to redesign from scratch, because you can no longer separate the complexity that earns its place from the complexity that is just old. And a system that keeps piling on features whose original justification nobody can name is already sliding into [feature creep](/blog/feature-creep), the accretion end state of an evolution that stopped recording its reasons.

## Getting started

Gall's law is not advice to build small and stay there. It is advice about direction of travel: reach the complex system you want by growing it from a simple one that genuinely works, because the from-scratch route validates its riskiest assumptions only at the end, when being wrong is most expensive. The grand whiteboard design fails not because the team lacked skill but because it tried to specify interactions that do not exist until the parts are running.

Do three things with it. Make your first version a system that actually does its core job end to end, not a fragment that only looks like it does, so you have a real seed to evolve. Add complexity one justified layer at a time, and resist the pull to design the whole thing up front or to make the next rewrite a grand one. And record *why* each layer was added, because the reasons decay faster than the code and their loss is what turns healthy evolution into blind accretion. [Try Scribelet free](https://scribelet.app) and let it keep the reasoning behind your system current, so the complex thing you grow stays one you can still understand.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>galls-law</category>
            <category>systems-design</category>
            <category>engineering</category>
            <category>software-architecture</category>
            <category>mvp</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[The Curse of Knowledge: Why Experts Write Bad Documentation]]></title>
            <link>https://scribelet.app/blog/curse-of-knowledge</link>
            <guid isPermaLink="false">https://scribelet.app/blog/curse-of-knowledge</guid>
            <pubDate>Mon, 14 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The curse of knowledge is why experts write docs nobody can follow. What the bias is, how it wrecks documentation and onboarding, and how to break it. Try it free.]]></description>
            <content:encoded><![CDATA[
A new engineer opens the README on their first day and reads: "Run the usual setup, then point it at staging and you're good to go." There is no link to "the usual setup," no note on which staging, no hint at how to point anything at it. The person who wrote that line was not being lazy. To them, every step was obvious, because they had done it a hundred times and could no longer imagine a reader who had not.

That is the curse of knowledge, and it is the single most expensive bias in technical writing. The gap between what a writer knows and what a reader needs is invisible to the writer, precisely because they already crossed it. It has a mirror image on the reader's side: [we keep trusting a source we just caught being wrong](/blog/gell-mann-amnesia-effect), extending the credit it earned in one area to every other.

## What is the curse of knowledge?

The curse of knowledge is a cognitive bias where someone who knows something well becomes unable to imagine what it is like not to know it. Once a fact is in your head, your brain quietly assumes it is in everyone else's too, so you skip the context, the definitions, and the steps that feel too obvious to mention. They are only obvious to you.

Economists Colin Camerer, George Loewenstein, and Martin Weber named the effect in 1989, studying why better-informed traders kept mispredicting how less-informed people would behave. Chip and Dan Heath later popularized it in *Made to Stick* as the reason clear ideas so often fail to travel. The bias is not about intelligence or effort. The more expert you are, the stronger it gets, which is exactly what makes it dangerous for the people who write the most documentation: the ones who know the system best.

For a note-taking and documentation tool like [Scribelet](https://scribelet.app), the curse of knowledge is not an abstraction. It is the mechanism behind almost every stale README, unfollowable runbook, and onboarding doc that assumes you already know the thing it was supposed to teach. We come back to what to do about that at the end.

## The tapper and the listener

The clearest demonstration of the curse comes from a 1990 Stanford experiment by Elizabeth Newton. Participants were split into "tappers" and "listeners." Each tapper picked a famous song like "Happy Birthday" and tapped out its rhythm on a table. Then they guessed how often the listeners would name the tune.

Tappers predicted listeners would get it right about 50 percent of the time. The listeners actually identified the song 2.5 percent of the time.

The tappers were not fools. They simply could not un-hear the melody playing in their own heads while they tapped. To them the rhythm obviously carried the song, because they had the song. The listeners heard a stranger drumming randomly on furniture. That is the curse of knowledge in one experiment: the tapper cannot experience the taps the way a listener does, so they wildly overestimate how much got across. Every expert writing documentation is a tapper convinced the melody is obvious.

## The curse of knowledge in software and documentation

Software teams run on written knowledge, which means they run straight into this bias constantly. It shows up in a handful of recognizable shapes:

- **READMEs that skip the setup that matters.** "Just configure your environment and run the tests." Which variables? Configured how? The author knew, so they compressed a twenty-minute process into six words.
- **Onboarding docs written by people who onboarded years ago.** They document the system they wish existed, or the one they remember, not the messy one a newcomer actually meets on day one.
- **Code comments that assume the reader shares your context.** A comment that says "handle the edge case" is only useful to the person who already knows which edge case and why it is special.
- **Tickets and design notes nobody outside the team can parse.** Internal shorthand, unexpanded acronyms, and references to a Slack thread from last quarter that the reader was never in.
- **The reasoning left out entirely.** The hardest version: the author knew *why* a decision was made, assumed that why was self-evident, and wrote down only the *what*. The reasoning was obvious to them, so it never made it to the page.

Every one of these is the tapper problem. The writer hears the full melody. The reader gets isolated taps and is expected to reconstruct the song.

## Where the curse shows up, and what it costs

The bias is easier to catch when you name the specific assumption behind each symptom. The pattern is always the same: the expert assumes the reader shares a piece of context, and the reader, missing it, is left stuck.

| How it shows up | What the expert assumes | What the reader actually experiences |
|---|---|---|
| Undefined jargon and acronyms | "Everyone here knows what SSO/DEK/the ingestion path means" | Reads a sentence of English words and understands none of it |
| "Just do X" instructions | "The steps inside X are obvious" | Cannot find X, cannot tell if they did it right |
| Onboarding that skips prerequisites | "Of course you have access and the tools installed" | Blocked on step one, afraid to ask what feels basic |
| Comments explaining the what, not the why | "The reason is clear from the code" | Sees the mechanism, has no idea if it is safe to change |
| Decisions recorded without context | "Why we chose this is self-evident" | Inherits a rule with no way to know if it still applies |

The cost is not just a confused reader. It is the support question that pulls a senior engineer off their work, the onboarding that takes three weeks instead of one, and the decision that gets silently reversed because nobody recorded why it was made. The curse of knowledge is the reason [code shows the what but rarely the why](/blog/self-documenting-code): the person writing it could see the reasoning so clearly that writing it down felt redundant.

![Chart showing that as expertise rises, the ability to imagine a beginner's perspective falls, and the gap between what an expert writes and what a reader needs widens](/blog/curse-of-knowledge/expertise-empathy-gap.svg)

## How to break the curse of knowledge

You cannot un-know what you know. The tapper cannot make the melody stop. What you can do is build habits that route around your own blind spot, because the fix is never "try to remember what it was like to be a beginner." You will fail at that. The fix is to get the missing perspective from outside your own head.

1. **Run the beginner test.** Before you call a doc done, hand it to someone who does not already know the answer, and watch where they get stuck. Their confusion is the data. Do not explain it away in the room; write down the step they tripped on and fix the doc. When you cannot borrow a beginner, [explaining the work out loud to no one in particular](/blog/rubber-duck-debugging) is the next best thing, because saying each step forces the assumption you were silently skipping into the open.
2. **Expand every acronym and define every term the first time.** If a word is load-bearing and specific to your system, it needs one sentence of definition. This feels patronizing to write and is invaluable to read.
3. **Write the why, not just the what.** For any non-obvious decision, record the reasoning and the constraint that forced it. The [reasoning behind a decision](/blog/chestertons-fence) is exactly the part your future readers cannot reconstruct from the result alone.
4. **Name the prerequisites out loud.** Access, tools, permissions, prior steps. If a reader needs something before step one, step zero should say so.
5. **Assume the reader has none of your context, not all of it.** When in doubt, over-specify the setup and under-specify nothing that matters. A reader who already knows can skim past a paragraph. A reader who does not cannot invent the paragraph that isn't there.

None of this requires more talent. It requires treating your own fluency as a liability during writing, not an asset. It also helps to remember the mirror image on the reader's side: [a reader can feel they understand a page they could not reconstruct a line of](/blog/illusion-of-explanatory-depth), so the test that protects them is the same one that protects you, producing the explanation instead of nodding along to it.

## A worked example: the mystery config value

Say you are documenting a service and you write: "Set `RETRY_BUDGET` appropriately for the environment." To you that sentence is complete, because you know the budget trades off latency against transient failures and that production runs hot. To the reader it is a dead end. Appropriately how? Compared to what?

Here is the same line rewritten against the curse. "Set `RETRY_BUDGET` to the number of retries a request may make before failing. Staging uses 3. Production uses 8, because the downstream billing API has a documented cold-start delay that 3 retries does not cover. If you lower it in production, expect intermittent failures during low-traffic periods." The second version is longer, and every extra word closes a gap the first version left the reader to fall into. The only reason the first version felt sufficient is that the author could already hear the whole melody.

## The trap: do not overcorrect into noise

Breaking the curse is not a license to explain everything to everyone forever. A doc that defines "database" for a team of database engineers has swung past the reader and into condescension, and nobody reads a page that treats them like they know nothing.

The bias to avoid on the other side is a cousin of the curse, not its opposite: over-explaining because you *imagine* the reader knows less than they do. The target is not maximum detail. It is calibration to a real reader, which is why the beginner test beats introspection every time. You are not trying to write for an infant. You are trying to write for the specific person who will actually open this doc next, and the only way to know what they need is to find one and watch.

## Why writing it down is the only real fix

The curse of knowledge would not matter much if the knowledge stayed in the expert's head and the expert stayed forever. It matters because neither is true. People rotate off projects, forget their own reasoning, and leave. When the only copy of *why* a system works the way it does lives in one person's memory, you do not have documentation, you have a [bus factor of one](/blog/bus-factor) wearing a lanyard.

And even the knowledge that does get written down decays. The curse makes writers omit the context that dates a decision, so a doc that was merely terse on the day it was written becomes actively misleading a year later, once the constraint it silently assumed has changed. This is the same failure behind [outdated documentation](/blog/outdated-documentation) and the broader problem of [notes going stale](/blog/knowledge-decay): the reasoning expired, but nobody wrote the reasoning down, so nobody can tell. Capturing the why the moment you know it, in an [internal documentation](/blog/internal-documentation) habit rather than a heroic annual cleanup, is what turns a tapper's private melody into something a listener can actually hear.

[Scribelet](https://scribelet.app) is built for that gap. When you capture the reasoning behind a decision or a setup step as you make it, that note becomes the context the curse of knowledge would otherwise strip out. The discipline is small and specific: write the constraint that forced the choice, not just the choice, and write it in a durable place rather than a Slack thread that scrolls away by next week. Background agents then re-check what you wrote against reality on a schedule, so when the constraint that justified a config value changes, you get a diff instead of a doc that quietly lies to the next person who reads it. The point is not to write more. It is to write the one sentence your own expertise keeps telling you is too obvious to bother with, because that sentence is the whole melody the reader cannot hear.

## Getting started

The next time something feels too obvious to write down, treat that feeling as the warning sign it is. That is the curse of knowledge telling you the reader will need exactly the thing you are about to skip. Write the why, name the prerequisite, define the term, and hand it to someone who does not already know. [Try Scribelet free](https://scribelet.app) and give the reasoning behind your work somewhere durable to live, before the person who understood it moves on and takes the melody with them.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>curse-of-knowledge</category>
            <category>documentation</category>
            <category>knowledge-management</category>
            <category>engineering</category>
            <category>communication</category>
        </item>
        <item>
            <title><![CDATA[A Second Brain for the Parts of Life That Aren't Work]]></title>
            <link>https://scribelet.app/blog/second-brain-for-personal-life</link>
            <guid isPermaLink="false">https://scribelet.app/blog/second-brain-for-personal-life</guid>
            <pubDate>Mon, 14 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[You built a second brain for work and left the rest of your life in screenshots and browser tabs. How to organize your life outside the office. Try it free.]]></description>
            <content:encoded><![CDATA[
Look at how carefully you organize work. There is a project structure, a naming convention, a weekly review, maybe a whole tagging system you have opinions about. Now look at the rest of your life. The recipe you loved is a screenshot buried three months deep in your camera roll. The washing machine manual is a PDF in an email you will never find again. Trip ideas are split across four apps, the plumber's number is in a text from 2023, and you have re-bought the same lightbulb twice because you could not remember the fitting.

Most people build a second brain for the eight hours that pay them and leave the other sixteen in chaos. This is about the other sixteen: how to organize your life outside of work, and where a notes app helps versus where it quietly gets in the way.

## What a second brain is, and why it stops at the office door

A second brain is an external system that holds what your head cannot: a trusted place to capture, organize, and find information so you are not relying on memory. Tiago Forte popularized the term, but the idea is older than the name, and by now most knowledge workers have some version of it for their job.

The strange part is where it stops. The same person who keeps an immaculate work wiki will manage their entire home, health, and family life out of memory, a messy notes app, and their inbox. Not because the personal stuff matters less. Usually because it never got a system at all. Work forced one on you. Nobody ever sat you down and said "here is the structure for your warranties." So the [personal knowledge management](/blog/personal-knowledge-management) habits you take for granted at work simply never crossed the threshold into the rest of your life.

That threshold is worth crossing, because the friction on the personal side is real even if it is quieter. It rarely shows up as a crisis. It shows up as ten minutes lost hunting for a document, a warranty that lapsed the month before the thing broke, a recommendation you know someone gave you and cannot retrieve. A second brain built with something like [Scribelet](https://scribelet.app) is usually pointed at work first, but nothing about the idea is work-specific. The method is the same; only the shelves are empty.

## The parts of life that never get a system

Once you look for them, the ungoverned collections are everywhere. Each one is a pile of information you accumulate for years and organize never:

- **Home:** appliance manuals, warranty dates, paint colors, the WiFi password, which filter the fridge takes, who fixed the boiler last time.
- **Health:** past prescriptions, test results, the specialist's name, what dose worked, questions you meant to ask at the next appointment.
- **The kitchen:** recipes you actually liked, what you cooked last week, what is in the freezer, the grocery list that lives half in your head and half on a receipt.
- **Travel:** places people recommended, the hotel that worked last time, passport expiry dates, the packing list you rebuild from scratch every trip.
- **Family and money:** birthdays and gift ideas, subscriptions you meant to cancel, the accountant's email, where the important documents actually are.

None of these is complicated on its own. The problem is that they are scattered across screenshots, tabs, texts, and three different apps, and they go stale while you are not looking. This is the same [collect-and-forget trap](/blog/commonplace-book) that swallows work notes, just aimed at your kitchen instead of your codebase. When one of those piles is a real collection you keep adding to (books, records, the recipes you actually use), the fix is to [catalogue it with notes](/blog/how-to-catalogue-a-collection) so you can search what you own instead of guessing at it.

## Why the work playbook does not transfer cleanly

Here is the trap people fall into: they discover the second-brain idea, get excited, and try to shove all of it into one notes app. It half works, then falls apart, and they conclude they are just disorganized. They are not. Personal information behaves differently from work notes in two ways that matter.

First, a lot of it needs *doing*, not just storing. A work note is usually reference: you write it, you read it later, done. But a recipe is not reference. To be useful it has to scale to six people, merge its ingredients with six other recipes, and turn into a grocery list sorted by aisle. A warranty is not reference either. It needs to turn into a reminder before it expires. A generic notes app is a shoebox: brilliant at holding things, useless at acting on them.

Second, personal life is shared and bursty. Your partner needs the grocery list too. The whole family needs the trip plan. And it arrives in floods (a house move, a new baby, a holiday) rather than a steady trickle. A system built for solo, steady work capture strains under both.

The honest conclusion is not "try harder to make one app do everything." It is that some parts of your life have outgrown a note and deserve a tool built for them.

![Diagram showing a second brain fully systematized for work but scattered across home, health, kitchen, and travel domains outside of work](/blog/second-brain-for-personal-life/life-domains.svg)

## Match the tool to the collection

The useful principle is boring and it works: keep the reference stuff in a notes app, and give the domains that need *doing* a purpose-built tool. You already accept this at work. You do not track sprint work in a plain text file when a proper board exists, and you do not keep the company finances in the same app as your meeting notes.

Apply the same judgment at home. Reference material that just needs to be captured and found later (manuals, medical history, that running list of gift ideas) is exactly what a notes app is for, and a maintenance-aware one keeps it from rotting. But the domains with real workflows deserve dedicated software. The kitchen is the clearest case. Recipes plus meal planning plus a shared, self-merging grocery list is a genuine little application, not a note, which is why a tool like [Origano](https://origano.app/blog/en/) treats meal planning and a recipe collection as its entire job rather than a folder inside a general app. The test is simple: if a collection mostly needs to be *found*, a note is fine; if it needs to be *acted on*, reach for the tool built for that action.

| Personal domain | Mostly needs to be | Right home |
|---|---|---|
| Manuals, warranties, passwords | found later | a notes app, with a reminder on the ones that expire |
| Medical history, doses, questions | found later | a notes app |
| Recipes, meal plans, grocery lists | acted on (scaled, merged, shared) | a dedicated meal-planning app |
| Calendar, bills, subscriptions | acted on (scheduled, cancelled) | a calendar and a money app |
| Gift ideas, recommendations, trip notes | found later | a notes app |

Take the kitchen concretely. In a notes app, a recipe is just text: you can read it, but to cook from seven of them next week you still copy every ingredient out by hand, merge the duplicates, and sort the result by aisle. A tool built for the job does that in one step and syncs the list to whoever is actually at the store. That gap, between holding a recipe and doing something with it, is the whole reason a purpose-built app beats a folder of notes for that one domain. The rest of your reference material has no such gap, so it stays where reference belongs.

## The maintenance problem follows you home

There is one more reason your personal second brain decays, and it is the same reason your work notes do. Capturing is the easy half. Keeping what you captured *true* is the half everyone skips.

A saved recipe links to a page that gets taken down. A warranty quietly expires. An address, a dose, a price, a phone number: all of them were correct the day you wrote them and drift out of date while the note sits there looking confident. This is [knowledge decay](/blog/knowledge-decay), and it is not a work-only phenomenon. A personal archive nobody tends is not an asset, it is a pile of things that used to be true. Whatever system you build for the rest of your life needs an answer to "how does this stay current," not just "where do I put it," which is the whole point of a [weekly maintenance pass](/blog/keep-notes-up-to-date) small enough to actually do.

This is the part Scribelet is built to carry. Its background agents re-check what you have written against reality on a schedule and hand you a diff when something no longer holds, so the reference half of your personal second brain does not silently rot between the Sundays you remember to review it. Maintenance is the difference between a system you trust and one you eventually abandon, and it is the step almost every personal setup skips.

## A lightweight second brain for the rest of your life

You do not need to become a productivity hobbyist to fix this. A workable personal system has four moving parts:

1. **One capture inbox.** A single place everything lands first, so nothing starts its life as a screenshot you will never find. Sort it later; just stop scattering it.
2. **A handful of domains, not forty.** Home, health, kitchen, travel, money, people. Five or six buckets cover almost everything, and a light structure like [PARA](/blog/para-method-with-ai) keeps them from turning back into one big pile.
3. **Purpose-built tools where doing matters.** The kitchen, calendars, and money each earn their own app. Everything that is pure reference stays in your notes.
4. **A recurring review.** Fifteen minutes on a Sunday to clear the inbox and catch the things that have gone stale. This is the step that separates a second brain from a graveyard, and the one an [AI-assisted setup](/blog/ai-second-brain-setup) can increasingly carry for you.

The point is not maximal organization. It is that the effort you already spend organizing work is quietly available to the rest of your life, and the parts of it that never got a system are usually the parts causing the most low-grade friction.

What this looks like a month in is not a beautiful dashboard you show people. It is the absence of small failures. You stop re-buying the lightbulb. The recipe you liked is one search away instead of lost in the camera roll. The warranty reminder arrives before the appliance dies, not after. Nobody re-plans the same trip from scratch, and nobody buys the milk twice because the grocery list lives in one place both of you can see. None of these are dramatic wins. Added up across a year, they are most of the mental overhead you currently carry for the parts of life that aren't work, and the reason it feels like there is never quite enough room in your head. A second brain does not make you a different person. It just stops your own life from being the thing you keep forgetting.

Start small and let it earn its place. Systematizing one annoying domain well beats a grand reorganization you abandon in three weeks, and each domain you fix makes the next one obvious.

## Getting started

Pick the single domain that annoys you most this week (for a lot of people it is the kitchen or the pile of household admin) and give it a real home instead of a screenshot. Use a dedicated tool where the collection needs *doing*, and keep the reference material somewhere that will not let it quietly rot. [Try Scribelet free](https://scribelet.app) for the notes-and-reference half of your second brain, and let the parts of life that aren't work finally get the same system the office already has.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>second-brain</category>
            <category>personal-knowledge-management</category>
            <category>life-admin</category>
            <category>pkm</category>
            <category>organization</category>
        </item>
        <item>
            <title><![CDATA[Chesterton's Fence: Don't Remove What You Don't Understand]]></title>
            <link>https://scribelet.app/blog/chestertons-fence</link>
            <guid isPermaLink="false">https://scribelet.app/blog/chestertons-fence</guid>
            <pubDate>Sat, 12 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Chesterton's fence says don't remove something until you know why it's there. What it means, real engineering examples, and when to break the rule. Try it free.]]></description>
            <content:encoded><![CDATA[
Someone on your team finds a `sleep(3)` call sitting inside a retry loop in the deploy script. No comment. No ticket reference. Nothing in the commit message but "fix flaky deploy." It looks like dead weight, so they delete it in the next cleanup pass. Three weeks later, deploys start failing intermittently in a way nobody can reproduce locally, and it takes a day of bisecting to find out that the sleep was there to dodge a race condition in a downstream service that still exists.

That is a fence removed by someone who never asked why it was built. The rule that would have stopped this has a name, and it is older than software: Chesterton's fence.

## What is Chesterton's fence?

Chesterton's fence is the idea that you should not remove a rule, structure, or restriction until you understand why someone put it there in the first place. It comes from G.K. Chesterton's 1929 essay collection *The Thing*, in a passage about a reformer who wants to tear down a fence blocking a road:

> "There exists in such a case a certain institution or law; let us say, for the sake of simplicity, a fence or gate erected across a road. The more modern type of reformer goes gaily up to it and says, 'I don't see the use of this; let us clear it away.' To which the more intelligent type of reformer will do well to answer: 'If you don't see the use of it, I certainly won't let you clear it away. Go away and think. Then, when you can come back and tell me that you do see the use of it, I may allow you to destroy it.'"

Chesterton was not arguing that fences should stay forever. He was arguing that not understanding a thing is not evidence that it is useless, and it is exactly the wrong basis for a decision to remove it. The reasoning behind a fence almost never gets written down at the moment it matters, which is the same gap [Scribelet](https://scribelet.app) exists to close, and a thread we come back to at the end.

## The parable, restated for people who build things

The fence in the essay is a stand-in for any inherited constraint: a law, a custom, a rule nobody remembers writing. The reasoning transfers cleanly to anything you did not build yourself and don't fully understand, which for most engineers is most of the codebase they work in on any given day.

The failure mode Chesterton describes has two matching versions. One is tearing the fence down blind, the retry-loop story above. The other is refusing to touch anything that looks old or strange, on the theory that it must be there for a reason, which is really just superstition wearing the same coat. Chesterton's actual position sits between them: go find out, then decide.

## Chesterton's fence in software engineering

Codebases accumulate fences constantly, and almost none of them come with a sign explaining why they exist. A few shapes show up often enough to be worth naming:

- **A retry, timeout, or sleep with no comment.** Someone hit a specific failure once, patched around it under deadline pressure, and never wrote down what the failure was. The code still runs fine, so nobody revisits it until someone "cleans it up."
- **A feature flag or config value nobody remembers flipping.** It defaults to something odd. Removing it feels safe because nothing visibly breaks in staging, right up until it breaks in the one account still depending on the old behavior in production.
- **A branch condition that special-cases one customer, one region, or one legacy data format.** It reads like leftover cruft. It is often the only thing standing between a clean release and a very expensive support ticket.
- **A "do not touch" comment with no explanation attached.** The instruction survived; the reasoning did not. Whoever wrote it assumed the context would stay obvious. It never does.
- **An index, a lock, or an ordering guarantee that looks redundant.** Databases and concurrent systems are full of constraints that exist to prevent a specific class of bug that only shows up under load nobody sees in development.

Every one of these looks removable from the outside. That is the trap. The cost of investigating first is a few minutes or a few hours. The cost of guessing wrong is a production incident, and usually one that takes far longer to diagnose than it would have taken to just ask.

## When to tear the fence down, and when to stop and dig first

Chesterton's fence is not a blanket instruction to leave everything alone. It is a filter for deciding which changes need investigation before they need action.

| Signal | What it tells you |
|---|---|
| You can find the commit, PR, or ticket that added it, and the reasoning still applies | Safe to remove once you've confirmed the reasoning is actually gone, not just old |
| Tests fail immediately when you remove it | The fence is load-bearing; you found the reason the hard way instead of the easy way |
| Nobody currently on the team wrote it, and there's no comment, ADR, or doc referencing it | Stop. This is the highest-risk case, because the reasoning may be gone for good |
| It only affects a code path you can't fully exercise locally (a specific customer, region, or scale) | Stop. Absence of a visible effect in your environment is not absence of an effect |
| The person who wrote it is reachable and remembers why | Ask before you touch it, even if you're fairly sure you already know |
| It duplicates logic that exists somewhere else in a cleaner form | Probably safe, but verify the duplication is actually redundant and not handling an edge case the clean version misses |

The pattern underneath the table: the less evidence you have about *why* something exists, the more investigation it earns before you act on it. A fence with a clear, current, still-valid reason attached is not really a Chesterton's fence problem anymore. It is a fence with a sign on it.

![Decision flowchart: found something you don't understand, then two paths, one investigating first when the reason is unknown and one proceeding when the reason is documented and still valid](/blog/chestertons-fence/fence-decision-flow.svg)

## How to find out why the fence is there

Before you remove anything you don't understand, run through the cheap checks first:

1. **Check git blame and the commit history.** The commit message and the diff around it often name the bug or the customer, even when the code comment doesn't.
2. **Search the PR or issue tracker for the file or function name.** Reviews and linked tickets frequently carry context that never made it into the code itself.
3. **Check for an ADR, design doc, or runbook that references the area.** A decision this consequential sometimes got written down properly, even if the code comment is silent. [Architecture decision records](/blog/architecture-decision-record-examples) exist precisely so this search has somewhere to land.
4. **Ask the person who wrote it, if they're still around.** This is the fastest path when it works, and it fails more often than teams expect, because people rotate off projects faster than institutional memory transfers.
5. **Time-box the investigation, then decide.** Chesterton's fence is not permission to research forever. Give it thirty minutes to an hour. If you still can't find a reason after a genuine search, that itself is a data point, not a green light: proceed carefully, behind a flag, with a fast rollback path.

None of this is exotic. It is the difference between deleting code and doing archaeology on it first, and the second one is almost always faster than the incident that follows skipping it.

## A worked example: the mystery timeout

Say you inherit a service with a hardcoded 45-second timeout on an outbound HTTP call, where every other call in the codebase uses the default 10 seconds. It looks like a typo, or a lazy fix someone never revisited. Here is what investigating first actually looks like in practice.

`git blame` points to a commit from over a year ago titled "bump timeout for vendor API." The commit message alone tells you something happened, but not what. The PR it belongs to links a support ticket: the vendor's API has a documented cold-start delay after periods of low traffic, and 10 seconds wasn't enough to cover it without dropping legitimate requests. Nothing in the code says any of this. Without the PR link, you'd have deleted the fix for a problem you never knew existed.

Now you have a decision to make, and it isn't "restore the default." It's "check whether the vendor's cold-start problem is still real." A quick message to the team, or a look at the vendor's current status page and changelog, tells you whether that constraint from a year ago still holds. If the vendor fixed their cold-start issue in the meantime, the 45-second timeout is now dead weight and safe to shorten. If they didn't, you just avoided reintroducing a bug that took someone a support escalation to diagnose the first time.

The point is not that the timeout should stay forever. It's that the ten minutes spent finding the PR turned a guess into a decision.

## The trap: don't let it become "we've always done it this way"

Chesterton's fence gets misquoted into its opposite more often than almost any other mental model. The reformer's critics in the essay were not arguing to keep the fence forever; they were arguing to understand it first. Turning that into "never remove anything old" is exactly the failure Chesterton was warning against, just aimed the other direction. It is a close cousin of [reflexively rejecting new evidence because it contradicts the established way](/blog/semmelweis-reflex): one defends the old by refusing to examine it, the other dismisses the new by refusing to examine it, and both skip the step where you actually look.

A codebase where every team member cites Chesterton's fence to block every change is a codebase where the fence has become an excuse instead of a filter. The rule only works if the investigation actually happens and actually concludes something. If the answer keeps coming back "we don't know, so let's not touch it," that is not caution, it is unaddressed technical debt with a philosophy quote attached. The same trap keeps stale dashboards alive: [a measure that hardened into a target](/blog/goodharts-law) long ago, defended now only because no one remembers what it was ever a proxy for, is a fence worth investigating rather than saluting.

## Write down why the fence is there, so nobody has to guess again

The entire premise of Chesterton's fence, that removing something you don't understand is risky, only exists because the reasoning behind decisions doesn't travel with the decision. Someone knew why the retry loop was there. They just didn't write it anywhere durable, and eighteen months later that knowledge is gone even though the code is still running.

This is the same gap that shows up across engineering documentation generally: the code shows you *what* happens, but [rarely why it happens](/blog/self-documenting-code), and the people who could explain the why eventually leave, forget, or move teams, which is really a [bus factor problem](/blog/bus-factor) wearing a different hat. Every fence in your system is a decision someone made under specific constraints that may or may not still hold, and constraints have a way of quietly expiring while the code that encodes them keeps running unchanged. The worst fences are the ones with no real reasoning to recover at all, because the decision was never truly made, just [backed into by a group that each assumed the others wanted it](/blog/abilene-paradox). Architectural boundaries have the same problem at a larger scale; a seam that made sense under [the org structure that drew it](/blog/conways-law) can outlive the org chart that justified it. Treating "why is this here" as a first-class question, the same way a good [decision-making framework](/blog/decision-making-framework) forces you to record the reasoning up front, is what turns archaeology into a habit instead of a fire drill.

Scribelet exists for exactly this gap. When you capture the reasoning behind a workaround, a config value, or a "don't touch this" the moment you write it, not months later when someone else is staring at it confused, that note becomes the fence's sign. Background agents then re-check what you wrote against reality on a schedule, so if the downstream service that needed the retry gets fixed, or the customer special-case gets migrated off the old format, you get a diff instead of a fence nobody can explain anymore. The boundaries in your system don't have to stay opaque just because the people who understood them moved on.

## Getting started

Next time you're about to delete something you don't fully understand, stop for the thirty minutes it takes to find out why it's there. If you can't find a reason after a genuine search, at least write that down too, so the next person doesn't repeat the same investigation from zero. [Try Scribelet free](https://scribelet.app) and give the reasoning behind your fences somewhere durable to live, before the next person has to learn why the hard way.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>chestertons-fence</category>
            <category>decision-making</category>
            <category>engineering</category>
            <category>mental-models</category>
            <category>code-quality</category>
        </item>
        <item>
            <title><![CDATA[The Cone of Uncertainty: Why Your Estimates Stay Wrong]]></title>
            <link>https://scribelet.app/blog/cone-of-uncertainty</link>
            <guid isPermaLink="false">https://scribelet.app/blog/cone-of-uncertainty</guid>
            <pubDate>Fri, 11 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The cone of uncertainty shows why early estimates are wide ranges, not numbers, and why the cone only narrows if you actively resolve unknowns. Try Scribelet free.]]></description>
            <content:encoded><![CDATA[
You were asked how long a feature would take, and you gave a number. Two weeks. You believed it when you said it. The feature shipped in five, and at no point could you have pointed at the moment it went wrong, because nothing went wrong in a single dramatic way. The estimate was just made at the worst possible time to make one: the beginning, when you knew the least about the work you were promising.

That is the idea behind the cone of uncertainty, and it is both more useful and more misunderstood than the one-line version every article gives you. The cone does not say your estimates are bad. It says there is a hard ceiling on how accurate any estimate can be at a given moment, and that ceiling is set by how much you still do not know. Early on, the range of honest outcomes is enormous. It narrows as you learn. The mistake almost everyone makes is assuming the narrowing happens automatically, on a calendar, just because time passed. It does not. You have to earn it.

## What is the cone of uncertainty?

The [cone of uncertainty](https://en.wikipedia.org/wiki/Cone_of_uncertainty) describes how the range of possible outcomes for a project estimate shrinks as the project progresses and unknowns get resolved. Plotted over time, the best-case estimate and the worst-case estimate start far apart and converge toward the actual result as you approach completion. The shape is a cone: wide at the start, narrow at the end. Barry Boehm introduced the underlying data in his 1981 book *Software Engineering Economics*, and Steve McConnell popularized the "cone" name and refined the figures in his work at Construx.

(If you searched this term during hurricane season, there is a second, unrelated cone of uncertainty used in weather forecasting to show a storm's probable track. This article is about the software and project estimation concept, not the meteorological one.)

The number that makes people sit up is the spread at the very beginning. According to the figures Boehm and McConnell document, an estimate made at the initial-concept stage can land anywhere from a quarter of the eventual effort to four times it. A "two week" feature that is really a careful guess made on day one is honestly somewhere between three days and eight weeks, and you have no way to know which until you do some of the work. That is not incompetence. It is the math of estimating something you have not started.

If you keep your estimates and their eventual outcomes in one place, [Scribelet](https://scribelet.app) can hold the original number next to what actually happened, which is the raw material you need to see your own cone instead of guessing at it.

## How wide is the cone, really?

The value of the cone is that it puts numbers on "we are not sure yet." Here is the variance at each phase, drawn from the estimation research Boehm and McConnell published. The multipliers are the range around a correct estimate, so a 4x high end means the real effort could be four times your figure.

![The cone of uncertainty: estimate variance starts at roughly a quarter to four times the real effort at initial concept and narrows toward one times as the project reaches completion](/blog/cone-of-uncertainty/cone-of-uncertainty.svg)

| Project phase | Low end | High end | What you have actually learned |
|---|---|---|---|
| Initial concept | 0.25x | 4x | Almost nothing. You are estimating a sentence, not a design |
| Approved product definition | 0.5x | 2x | What you are building and roughly for whom |
| Requirements complete | 0.67x | 1.5x | The specifics of what the thing must do |
| Design complete | 0.8x | 1.25x | How you will build it, and where the hard parts are |
| Detailed design complete | 0.9x | 1.15x | The real shape of the work, edge cases included |
| Code complete | ~1x | ~1x | Everything. The estimate is now a measurement |

Read down the "what you have learned" column and the cone stops being mysterious. The range does not shrink because the calendar advanced. It shrinks because each phase resolves a category of unknown. You cannot estimate the integration accurately until you have looked at the API you are integrating with. You cannot price the edge cases until the requirements name them. The accuracy is downstream of the knowledge, always.

This is why a demand for a precise estimate on day one is a demand to invent a number. The cone tells you the most honest answer is a range, and the range is wide. A team that commits to a single figure at initial concept is not being more confident. It is being less truthful about what it knows.

## The part every definition leaves out: it is a best case, not a promise

Here is the distinction that separates people who understand the cone from people who have only seen the picture. The cone describes the **best** accuracy you can possibly have at each stage. It is a ceiling, not a forecast. McConnell is explicit about this at [Construx](https://www.construx.com/books/the-cone-of-uncertainty/): the cone represents the best case it is possible to achieve, and you only reach that best case if you are actively doing the work that removes uncertainty.

Skip that work and the cone does not narrow. You get a cloud. The project progresses, time passes, the calendar fills up, and your estimate is exactly as uncertain in week six as it was in week one, because nobody resolved anything. Requirements stayed vague. The risky integration got deferred instead of investigated. The "we will figure it out later" items were never figured out. The cone is a promise about what is *possible*, conditional on you earning it. It is not a guarantee that accuracy arrives on schedule.

This reframes the whole tool. The cone is not a passive prediction you watch come true. It is a to-do list in disguise. Every phase that narrows the cone corresponds to an act of uncertainty reduction: writing the [technical spec](/blog/technical-spec) so the requirements stop shifting, prototyping the scary part, pinning down the interface in a [design document](/blog/software-design-document) before you commit to a date. If your estimates are not getting more accurate as the project runs, the cone is telling you something specific and useful: you are not learning fast enough, and the deadline is arriving before the knowledge does.

## Why your cone is not narrowing

When a project stays uncertain deep into its timeline, it is almost never a mystery. It is one of a handful of specific failures, and each one has a fix aimed at the unknown it leaves open.

| Why the cone stays wide | What it looks like | What narrows it |
|---|---|---|
| Requirements never stabilized | The target keeps moving, so every estimate measures a thing that changed | Freeze scope in writing before estimating, and re-estimate explicitly when it moves |
| The risky work got deferred | The one genuinely uncertain piece is scheduled last, so the big unknown survives to the end | Do the scariest, least-understood task first; it carries the most uncertainty to resolve |
| No re-estimation | The day-one number is treated as a commitment and never revised as you learn | Re-estimate at each phase boundary; the cone is made of those revisions |
| Optimism instead of evidence | Each estimate is a hope about the best case, not a read on actual progress | Estimate from what comparable work really took, not from the happy path |
| Scope quietly expanding | The work grows as you build, re-widening a cone that was starting to close | Watch for [feature creep](/blog/feature-creep); each small addition re-opens the range |
| Assumptions never written down | You cannot tell whether you estimated badly or reality changed, so you learn nothing | Record what each estimate assumed, so a miss teaches you which assumption broke |

The through-line is that narrowing the cone is active work, and most of it is the unglamorous work of resolving ambiguity before it becomes a surprise. A team that does this looks, from the outside, like it is "just planning." What it is really doing is buying down risk one unknown at a time, which is the only thing that has ever made an estimate more accurate. The most direct version of this on a build is to [front-load the risky integration](/blog/walking-skeleton) with a thin end-to-end slice, resolving the biggest unknown in the first days rather than the last.

## How to actually narrow it: re-estimate on a cadence

The practical move the cone implies is simple and almost nobody does it: re-estimate at every phase boundary, and write down both the new number and what changed to justify it. A single estimate made on day one is a guess. A series of estimates, each made with more information than the last, is a cone you can actually see closing, and each revision is a checkpoint where you can raise the alarm early if it is not.

Keep a short record per estimate. It costs a minute at each phase boundary and it is the only thing that turns the cone from a diagram into a skill.

```
Task/project: what you are estimating
Phase: concept | definition | requirements | design | build
Estimate: range (low to high), not a single number
Basis: what you now know that you did not know last time
Assumptions: the facts you are treating as fixed (libraries, APIs, people, scope)
Biggest remaining unknown: the one thing that would move the estimate most
Actual (when known): what it really took
```

The "biggest remaining unknown" line is the one that does the work. It names the widest part of your current cone, which tells you exactly what to investigate next to narrow it. Chase that unknown down before the next phase and the range closes on evidence instead of hope. This is the same discipline behind [second-order thinking](/blog/second-order-thinking): an estimate is a prediction, and a prediction is only worth making if you can later check it against what happened and adjust.

## The assumptions behind an estimate decay

There is a deeper reason the written record matters, and it is the reason most estimation advice quietly stops working a few weeks in. An estimate is a bet on a set of assumptions, and those assumptions expire.

When you estimated the work, you were assuming specific facts: this library behaves the way it did last quarter, this API is stable, this teammate is free, this requirement is final. Each of those can change between the estimate and the work, and when one does, your number is wrong for a reason that has nothing to do with your estimating skill. If you never recorded *why* you believed the estimate, you cannot tell later whether you misjudged the work or the ground moved under you. The estimate decays, and the reasoning behind it decays faster. This is the same [knowledge decay](/blog/knowledge-decay) that rots every other kind of working knowledge, and it is how a plan ends up [quietly out of date](/blog/outdated-documentation) while everyone still trusts it: the number survives, but the assumptions it was built on are gone.

This is where [Scribelet](https://scribelet.app) fits. Its background agents re-check your notes and records against reality on a schedule and surface a diff when something no longer holds, so the assumptions behind an estimate do not silently expire while you are looking the other way. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. Keeping the reasoning attached to the estimate is what lets the cone teach you something that carries to the next project. It is not a coincidence that the projects that blow up are the famous ones run by experienced teams. Research by Oxford's Bent Flyvbjerg found that [one in six IT projects](https://hbr.org/2011/09/why-your-it-project-may-be-riskier-than-you-think) ran 200% over budget and nearly 70% over schedule, and that the damage clusters in a fat tail of catastrophic overruns. Those teams were not short on expertise. They were short on a closing cone, committing to numbers that the work had not yet earned. It is [Hofstadter's Law](/blog/hofstadters-law) at the scale of a whole project: the work takes longer than you expect, even when you expect it to, because the cone never closed enough to catch the overrun in time.

## Getting started

The cone of uncertainty is not a problem to solve. It is the permanent shape of estimating things you have not finished, and the goal is to work with it instead of pretending you are above it.

Do three things. Give ranges, not single numbers, and make the range honest: early on it should be wide, because the cone says it has to be. Re-estimate at every phase boundary and treat the narrowing as a result you earned by resolving unknowns, not a gift the calendar hands you. And write down the assumptions behind each estimate, because the estimate that misses almost always misses on an assumption that quietly stopped being true. [Try Scribelet free](https://scribelet.app) and let it keep the reasoning behind your plans current, so each estimate inherits what the last one learned instead of starting the cone over from scratch.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>cone-of-uncertainty</category>
            <category>estimation</category>
            <category>project-planning</category>
            <category>software-engineering</category>
            <category>agile</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Hofstadter's Law: Why Software Always Takes Longer]]></title>
            <link>https://scribelet.app/blog/hofstadters-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/hofstadters-law</guid>
            <pubDate>Thu, 10 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Hofstadter's Law says work always takes longer than you expect, even when you plan for it. Why estimates fail and how to fix them. Try Scribelet free.]]></description>
            <content:encoded><![CDATA[
You already know you run late, so you padded the estimate. The honest guess was two weeks, and because you have been burned before, you doubled it to a month and called that safe. The task shipped in six weeks. Not because anything went catastrophically wrong, but because a dependency needed updating, then the update broke a test, then the person who understood the test was on leave, then the "quick" migration turned out to touch three services. Every delay had a reason. None of them was in the plan. And the padding you added, the buffer that was supposed to absorb exactly this, got eaten in the first ten days.

That is Hofstadter's Law, and the cruel part is baked into its own wording: it always takes longer than you expect, even when you take into account Hofstadter's Law. It anticipates your padding and beats it anyway. Every productivity blog will give you the one-line definition and a shrug about optimism bias. What none of them gives you is the thing you actually need the next time you have to put a number on a plan: why the padding fails, which estimation methods survive contact with a real project, and a way to turn "everything runs late" from a running joke into a number you can actually calibrate.

## What is Hofstadter's law?

[Hofstadter's law](https://en.wikipedia.org/wiki/Hofstadter%27s_law) states that a task always takes longer than you expect, even when you account for the fact that tasks take longer than you expect. Cognitive scientist Douglas Hofstadter coined it in his 1979 book *Gödel, Escher, Bach: An Eternal Golden Braid*, while discussing how chess programmers kept predicting a computer would beat the world champion "in ten years," a prediction that stayed ten years away for decades. The law is self-referential on purpose. It does not just say you underestimate. It says the underestimation survives your attempt to correct for it.

That recursion is what makes it more than a complaint. A normal estimating error you can fix by padding: add 50%, move on. Hofstadter's Law is the observation that padding does not work the way you think, because the same optimism that produced the original estimate also produces the buffer. You pad against the risks you can imagine. The project runs late on the risks you could not.

It is cited most often in software, and for a reason software people will recognize immediately. Writing code is not the slow part. The slow part is everything the estimate assumed would go smoothly: the integration that has one undocumented quirk, the review that surfaces a design problem, the environment that behaves differently in staging, the requirement that was clear until someone actually used the feature. Any one of those can open into [a cascade of prerequisite fixes](/blog/yak-shaving) that pulls you further and further from the task you were trying to estimate, the pattern known as yak shaving. If you keep your plans and their outcomes in one place, [Scribelet](https://scribelet.app) can hold the estimate next to what actually happened, which is the only raw material you have for getting better at this.

## Why your estimates blow up, even when you pad them

![Bar chart of one task estimated three ways: an honest two-week estimate, a padded four-week estimate, and a six-week actual that overruns even the padded buffer](/blog/hofstadters-law/estimate-vs-actual.svg)

Hofstadter's Law is a symptom. Underneath it are a handful of specific forces, and once you can name them you can aim a fix at each one instead of just adding a bigger buffer and hoping. The buffer is not the fix, because the buffer is subject to the same forces as the estimate.

| Why the estimate is wrong | What it looks like in practice | What actually helps |
|---|---|---|
| The planning fallacy | You picture the happy path and estimate that, ignoring how similar tasks actually went | Estimate from the outside view: pull the real duration of the last five similar tasks |
| Hidden complexity | The work reveals dependencies and edge cases only once you are inside it | Break the task down until each piece is a day or less; the pieces you cannot break down are where the risk hides |
| The recursive trap | You add a buffer, and the work quietly expands to consume it | Track estimate against actual so the buffer is calibrated from data, not guessed from optimism |
| Scope creep | The target moves while you build, so the estimate is measuring a thing that no longer exists | Fix the scope in writing before you estimate, and re-estimate explicitly when it changes |
| Coordination cost | Adding people to a late task adds communication overhead faster than it adds output | Do not staff your way out of a slip; Brooks's Law says it makes the slip worse |
| Optimism as default | The estimate is really a wish about the best case, stated as a prediction | Ask for the estimate you would bet your own money on, not the one you hope for |

The through-line is that most of these are invisible at estimate time. You cannot list the dependency you have not discovered yet, so you do not budget for it, so the plan is optimistic by construction. This is the same dynamic that drives [feature creep](/blog/feature-creep): each individual addition looks reasonable, and the total is a schedule nobody signed up for. The difference is that feature creep moves the target, while Hofstadter's Law says even a fixed target comes in late.

## The estimation techniques that actually help

You cannot beat Hofstadter's Law, but you can stop being surprised by it. Different methods fit different kinds of uncertainty, and the common mistake is using a precise-looking technique on work too novel to support it. Match the method to what you actually know.

| Technique | Best for | How it works | Where it fails |
|---|---|---|---|
| Gut estimate plus a multiplier | Small, familiar, low-stakes tasks | Take your honest guess, apply your known personal or team multiplier | The multiplier is a fiction until you have tracked real ratios |
| Three-point (PERT) | Tasks with a known shape but real variance | Average optimistic, likely, and pessimistic as (O + 4L + P) / 6 | Garbage in, garbage out if all three numbers are optimistic |
| Historical velocity | Teams with a track record on similar work | Estimate against how much comparable work the team actually finished per week | Breaks when the new work is unlike the history |
| Reference-class forecasting | Large, novel, or high-stakes projects | Compare the project to the real distribution of outcomes for similar past projects | Requires honest data about how comparable projects actually went |
| Relative sizing | Early, coarse planning across many items | Size items against each other rather than in absolute hours | Tells you relative effort, not a calendar date |

The single highest-leverage move is the one the [planning fallacy](https://en.wikipedia.org/wiki/Planning_fallacy) research keeps confirming: switch from the inside view to the outside view. The inside view builds an estimate from the specific steps you imagine. The outside view asks how long this kind of thing has actually taken before, and it is consistently more accurate, because it captures the delays you cannot yet name. Reference-class forecasting is just the disciplined version of that instinct, and it works because it borrows from projects that already hit the walls you have not seen. It also explains why an honest early estimate is [a wide range rather than a single number](/blog/cone-of-uncertainty): before you start, the walls you have not seen are exactly the ones that set the outer edge of the range.

## What Hofstadter's law looks like at scale

The law is funny on a two-week ticket and sobering on a budget. The pattern is identical, only the units change. These are not obscure cases; they are among the most studied schedule overruns on record.

| Project | Planned | Actual | Overrun |
|---|---|---|---|
| Sydney Opera House | $7M, open 1963 | $102M, open 1973 | ~14x cost, 10 years late |
| Denver Airport automated baggage | ~16 months | Scrapped after delaying the airport ~16 months | Abandoned, hundreds of millions lost |
| Berlin Brandenburg Airport | Open 2011, ~€2B | Open 2020, ~€7B | 9 years late, ~3.5x cost |
| Windows Longhorn / Vista | Ship ~2003 | Reset in 2004, shipped 2007 | Roughly 4 years, a full development restart |

None of these was run by amateurs. The teams were experienced, the budgets were real, and the estimates were made by people who knew the work was hard. That is the point. Research by Oxford's Bent Flyvbjerg found that [one in six IT projects](https://hbr.org/2011/09/why-your-it-project-may-be-riskier-than-you-think) had a cost overrun of 200% and a schedule overrun of nearly 70%, and that the risk is not evenly spread: a small share of projects blow up catastrophically, which is exactly the fat tail Hofstadter's Law predicts. The lesson is not that these teams were careless. It is that expertise does not exempt you, and the confidence that comes with expertise can make the estimate worse, the same way it fuels the [second-system effect](/blog/second-system-effect) when a team rebuilds a product it now feels it understands.

## Track the estimate against the actual

Here is the practice that turns the law from a shrug into a skill. Almost nobody records their estimates, so almost nobody learns their own error rate. You feel like you always run late, but "feel like" is not a multiplier. Write the estimate down, write the actual down next to it, and after a dozen tasks you will have something no amount of intuition gives you: your real ratio.

Keep a running log with one entry per task. It costs a minute and pays for itself the first time you can answer "how long will this take" with data instead of hope.

```
Task: what you are estimating
Estimated: hours or days, and the date you estimated
Assumptions: the happy path you pictured when you gave the number
Actual: hours or days it really took
Ratio: actual divided by estimate
What I missed: the dependency, review, or complexity that ate the time
Next time: the specific adjustment for this kind of work
```

The "what I missed" line is the one that compounds. After ten entries you stop seeing random bad luck and start seeing patterns: integrations always take twice as long, anything touching auth needs a review buffer, the first estimate after a context switch is always low. Those patterns are your personal reference class, and they are worth more than any generic multiplier because they are built from your actual work. An estimate is a [prediction, and predictions have downstream consequences](/blog/second-order-thinking) you can only grade if you wrote the prediction down.

## The part nobody keeps: your estimates are predictions that decay

There is a reason the log matters beyond arithmetic, and it is the reason most estimation advice quietly fails. An estimate is a bet on a set of assumptions, and those assumptions expire.

When you estimated two weeks, you were assuming a specific set of facts: this library works the way it did last quarter, this API is stable, this teammate is available, this requirement is final. Every one of those can change between the estimate and the work, and when it does, the estimate is wrong for a reason that has nothing to do with your math. If you never wrote down *why* you thought two weeks, you cannot tell, later, whether you estimated badly or the ground moved under you. The number decays, and so does the reasoning behind it. This is the same [knowledge decay](/blog/knowledge-decay) that rots every other kind of working knowledge: the estimate outlives the assumptions it was built on, and nobody notices until the plan is already late.

This is where [Scribelet](https://scribelet.app) fits. Its background agents re-check your notes and records against reality on a schedule and surface a diff when something no longer holds, so the assumptions behind a plan do not silently expire while you are looking away. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. Keeping the reasoning attached to the estimate, the way you would attach the rationale to a [technical spec](/blog/technical-spec) or a [design document](/blog/software-design-document), is what lets next quarter's estimate learn from this quarter's instead of repeating it. A plan whose assumptions have [gone stale without anyone noticing](/blog/outdated-documentation) is a plan that will run late for reasons you will never diagnose, because the record of what you were betting on is gone.

## Getting started

Hofstadter's Law is not a problem you solve. It is a property of doing hard things, and the goal is not to eliminate the overrun but to stop being blindsided by it. You do that by replacing optimism with data.

Do three things. Estimate from the outside view: before you guess, pull how long the last few similar tasks actually took, and start there instead of from the happy path. Keep an estimate-versus-actual log so your padding is calibrated from your real error rate rather than your hopes. And write down the assumptions behind each estimate, because the estimate that runs late usually does so when one of those assumptions quietly stopped being true. [Try Scribelet free](https://scribelet.app) and let it keep the reasoning behind your plans current, so the next estimate inherits what the last one learned instead of repeating the same surprise at a bigger scale.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>hofstadters-law</category>
            <category>estimation</category>
            <category>project-planning</category>
            <category>software-engineering</category>
            <category>productivity</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[The Second-System Effect: Why Rewrites Balloon]]></title>
            <link>https://scribelet.app/blog/second-system-effect</link>
            <guid isPermaLink="false">https://scribelet.app/blog/second-system-effect</guid>
            <pubDate>Wed, 09 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The second-system effect is why a lean first release begets a bloated rewrite. What it is, why experience makes it worse, and how to avoid it. Try it free.]]></description>
            <content:encoded><![CDATA[
The first version shipped in four months and it was a little ugly and it worked. You cut the reporting module, you hardcoded the thing that should have been configurable, you shipped one integration instead of the five people asked for. Every corner you cut, you cut because you were not sure you would make it, and you noted each one with a quiet promise: next time, we do it right. Now the product is a success, you know the domain cold, and the rewrite is greenlit. This is the one you build properly. Every deferred idea goes back in. The config system will be fully general this time. All five integrations. A plugin architecture so you never have to cut a corner again. Eighteen months later the rewrite is late, twice the size, slower than the thing it replaced, and the team that shipped the scrappy first version in four months cannot get the "proper" one out the door.

That is the second-system effect, and it is one of the oldest traps in software. It is not a skill problem, which is the unsettling part. The team is more experienced than it was the first time, the requirements are better understood, and the effect gets them anyway, precisely *because* they now feel competent enough to build everything they once had the humility to skip. Every roundup will give you Fred Brooks's one-line definition and move on. What it will not give you is the thing you actually need at the moment the rewrite is being scoped: a way to tell the disciplined second system from the bloated one before you have spent a year finding out. Here is what the second-system effect is, why experience makes it worse rather than better, the real examples worth learning from, and a decision you can run before you commit to the rewrite that eats your year.

## What is the second-system effect?

The [second-system effect](https://en.wikipedia.org/wiki/Second-system_effect) is the tendency to over-engineer the successor to a small, successful system by piling in every feature, generalization, and edge case that the lean first version left out. Fred Brooks named it in his 1975 book *The Mythical Man-Month*, after watching clean early designs at IBM get followed by bloated, late, over-ambitious replacements. His formulation is precise: an architect's first system tends to be "spare and clean" because the designer is cautious and unsure; the second one is where all the restraint goes to die.

The mechanism is a confidence trap. On the first system you do not know what you are doing, so you keep the design small and defensible out of a healthy fear of failure. The first system succeeds. Now you have proof you are good at this, plus a list of everything you wished you had done, and the next project looks like the chance to do all of it. The restraint that made the first system work was never a principle you held. It was a side effect of not being sure, and success removes it exactly when the scope gets bigger and the restraint matters most.

It is also called the second-system syndrome, and the symptoms are consistent: a schedule that slips for quarters, a feature list far longer than the first release, a pile of generalizations added for hypothetical future needs, and a finished product that is slower and more complex while being no better at the core job. An input layer rebuilt to accept every conceivable format, generous to a fault, is one common form of it: [the robustness principle stretched past its limit](/blog/postels-law) into an interface nobody can reason about. A second system running slower than the lean one it replaced is [software slowing down faster than hardware speeds up](/blog/wirths-law), the deferred features and general abstractions spending every gain the newer hardware was meant to deliver. The tell that separates it from ordinary ambition is the phrase "while we're at it." A second system is not one big wrong decision. It is a hundred "while we're in here anyway" additions, each defensible, landing on a project that was sold as a clean rewrite.

## Why experience makes it worse

Most engineering mistakes get rarer as a team gets better. The second-system effect runs the other way, and understanding why is what lets you catch it. Three forces push a confident team toward a bloated second system, and all three get stronger with success, not weaker.

| Force | What it sounds like in the room | Why experience amplifies it |
|---|---|---|
| Deferred-wish backlog | "We finally get to build it the right way" | The more you shipped around the first time, the longer the list of corners you are itching to uncut |
| Overconfidence from the win | "We know this domain now, we can handle the scope" | The first success is read as proof the bigger scope is safe, when it only proved the smaller one was |
| Generalization fever | "Let's make it configurable so we never hit this wall again" | Experience shows you every wall you hit, and tempts you to build a general system to avoid all of them at once |

Notice that none of these is stupid. Each is a reasonable response to a real lesson from the first system. The deferred features *were* real gaps. The domain knowledge *is* real. The walls you hit *were* annoying. The second-system effect is what happens when every reasonable lesson is acted on at once, in the same release, by a team whose fear of failure has been replaced by the memory of a win. This is the same dynamic behind [feature creep](/blog/feature-creep), with one difference: feature creep accretes slowly across a live product's life, while the second-system effect front-loads the whole accumulation into a single planned rewrite. The rewrite is where a team commits, in one decision, to carrying everything it ever wished it had.

If you are staffing or scoping a rewrite right now, the single cheapest safeguard is a written boundary you can point back to when "while we're at it" starts. [Try Scribelet free](https://scribelet.app) and keep the "what this rewrite is and is not" note somewhere it stays true.

## Second-system effect examples

The effect is easiest to see in systems you already know. The pattern is identical each time: a lean, successful first version, a rewrite scoped to fix everything, and a successor that arrived late and heavy.

| First system | Second system | What specifically ballooned |
|---|---|---|
| IBM 7000-series operating systems (small, clean) | OS/360 | A single system meant to span all hardware and every use case; late, enormous, and the case Brooks wrote the book about |
| Windows XP (stable, widely loved) | Windows Vista | An ambitious rewrite of the driver model, security, and graphics stack at once; slow, incompatible at launch, widely skipped |
| AngularJS (simple, popular) | Angular 2 | A total framework rewrite with a new language and mental model; broke existing apps and sent many developers to simpler options |
| Python 2 (pragmatic, ubiquitous) | Python 3 | A correctness-driven redesign whose migration cost stretched the transition across more than a decade |

Every one of these was built by capable people who had earned their confidence on the first system. None of them failed for lack of talent. They over-reached because the first win made a much larger second scope feel safe, and because the rewrite was the moment every deferred idea could finally be let in. Some of these systems eventually became good. The point is not that a second system is doomed; it is that the cost of the balloon was enormous and mostly avoidable, and the teams that paid it did not see it coming while they were scoping.

The related trap worth naming is "[things you should never do](https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/)," Joel Spolsky's argument that a full rewrite throws away the hard-won knowledge baked into the messy first version. It is the same warning [Gall's law](/blog/galls-law) makes about building from scratch: a complex system rebuilt whole from a clean design usually fails, because the working system it replaced had evolved into shape for reasons the rewrite cannot see. That knowledge is the hidden cost the second system pays twice: once to rebuild what the first system already did, and again to rediscover the reasons the first system was shaped the way it was.

## How to avoid the second-system effect: the rewrite decision

The useful move is not "never rewrite." Sometimes the first system genuinely cannot carry the load and a rebuild is correct. The move is to decide deliberately between the options instead of defaulting to the total rewrite because it is the most satisfying one. Most "we need to rewrite" situations are better served by a narrower choice, and naming them side by side makes the second-system risk visible before you commit.

| Approach | What it is | Best when | Second-system risk |
|---|---|---|---|
| Refactor in place | Improve the existing system incrementally, keeping it running | The architecture is sound and the pain is local | Low: you cannot balloon what you are not rebuilding |
| Strangler pattern | Build the new system around the old one, route traffic piece by piece, retire the old gradually | You need a new design but cannot afford a big-bang cutover | Moderate: scope is bounded one slice at a time, which is the point |
| Incremental rewrite behind a stable interface | Replace internals module by module while the outside stays fixed | The interface is good but the implementation rots | Moderate: the fixed interface caps the scope |
| Full rewrite from scratch | Rebuild the whole thing on a clean design | The core model is genuinely wrong and nothing else works | High: this is the one the second-system effect targets |

The full-rewrite row carries a trap the table cannot show: "the core model is wrong" is a judgment about the documented interface, but callers were never only depending on that. They were depending on every observable quirk of the old implementation, which is [Hyrum's law](/blog/hyrums-law) showing up as the reason a supposedly clean rewrite still breaks half its integrations on launch day. When the honest answer is a full rewrite, the discipline is to treat it with the same fear you brought to the first system, not the confidence you earned from it. The [Martin Fowler strangler-fig approach](https://martinfowler.com/bliki/StranglerFigApplication.html) exists precisely because it forces the bounded-scope discipline the second-system effect erodes: you cannot balloon a system you are replacing one route at a time. When the rewrite does start fresh, the same restraint says to [begin with one thread that walks end to end](/blog/walking-skeleton) and thicken it, rather than rebuilding every layer at full width before anything runs.

## Warning signs you are building a second system

The effect is cheap to catch early and expensive to catch late, so the leverage is in the warning signs. If several of these are true about a rewrite you are scoping, you are in second-system territory and the scope needs a hard look before another week goes in.

| Warning sign | What it looks like |
|---|---|
| The "while we're at it" list is growing | Every planning meeting adds a deferred feature, and none get cut |
| The scope is justified by the future, not the present | Features exist for users and loads you do not have yet and cannot name |
| Generality is a goal in itself | "Make it configurable / pluggable / generic" appears with no concrete second use case |
| The new version is already bigger than the old one | More modules, more config, more surface, before it does anything the old one did |
| The timeline has slipped with nothing shipped | Quarters pass and there is no running, usable slice in production |
| Nobody can state what is out of scope | There is an in-scope list and no out-of-scope list |

The last row is the one that matters most, because it is both the surest sign and the cheapest fix. A second system balloons when no one wrote down what it is *not* for. A [technical spec](/blog/technical-spec) with an explicit non-goals section, or a [design document](/blog/software-design-document) whose "what we are not building" list is longer than its feature list, is the single most effective counterweight to the effect. The boundary has to exist in writing before the confidence arrives, because once "we know this domain now" takes hold, every addition will sound reasonable.

![The second-system effect: a lean, constrained first system succeeds, confidence rises, and the second system balloons with deferred features unless a written scope boundary holds the line](/blog/second-system-effect/second-system-curve.svg)

The curve is the whole story. The first system stays lean because constraint is forced on it by uncertainty. Success lifts confidence, and confidence removes the constraint right as the scope grows. The second system balloons not because the team got worse but because the thing that was quietly keeping the first one honest, the fear of failing, is gone. A written boundary is how you replace a feeling you have lost with a rule you can point at. This is a [decision worth making with a framework](/blog/decision-making-framework) rather than by whoever is most excited about the clean-slate rewrite.

## The part nobody maintains: the reasons behind the first system decay

Here is the deeper reason a full rewrite is so dangerous, and it is the part the textbook definition misses. When you rebuild from scratch, you do not just re-type the code. You throw away every undocumented reason the first system was shaped the way it was, and those reasons are almost never written down.

Think about what the messy first system actually contains. That odd retry count, the field that is nullable for one weird customer, the validation that looks redundant until you remember the incident that caused it, the module boundary that seems arbitrary until you recall the team that owned each side. Each of those is a decision someone made for a real reason, and the reason lived in a head, a Slack thread, or a ticket nobody will find. The code records *what* the first system does. It almost never records *why*, and the why is exactly what a rewrite needs and cannot see. So the second system re-solves, at great cost, problems the first system had already quietly solved, and it re-learns the same lessons by re-suffering the same incidents. This is the second-system effect's secret engine, and it is the same [knowledge decay](/blog/knowledge-decay) that rots every other kind of working knowledge, hitting a rewrite at the worst possible moment.

This is the problem Scribelet is built for. Its background agents re-check your notes and decision records against reality on a schedule and surface a diff when something no longer holds, so the reasoning behind a constraint stays attached to the constraint instead of evaporating by the time someone proposes rebuilding around it. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. Capturing the *why* the way you would an [architecture decision record](/blog/architecture-decision-record-examples) is what lets a second system keep the hard-won judgment of the first instead of paying to rediscover it. A first system whose reasoning has [silently gone out of date](/blog/outdated-documentation) is one you will feel forced to rewrite, because you can no longer tell which of its oddities are scars and which are mistakes. And when the reasons live in only one or two people's heads, you have a [bus factor](/blog/bus-factor) problem feeding directly into your second-system one: the rewrite looks safe precisely because the people scoping it cannot see what they are about to discard.

## Getting started

The second-system effect is not cured by being smarter, because it is caused by being confident. The first system is lean because you are afraid; the second balloons because you are not. The fix is to manufacture, on purpose, the discipline that uncertainty used to provide for free.

Do three things before you commit to a rewrite. Write down what the new system is *not* for, and make that list longer than the feature list. Decide honestly between refactoring, a strangler migration, and a full rebuild, rather than defaulting to the rewrite because it is the most fun. And capture the reasons behind the first system's strange choices before you throw the first system away, because those reasons are the asset, not the code. [Try Scribelet free](https://scribelet.app) and let it keep the reasoning behind your system current, so your second system inherits the first one's hard-won judgment instead of repeating its mistakes at twice the size.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>second-system-effect</category>
            <category>rewrites</category>
            <category>engineering</category>
            <category>software-design</category>
            <category>scope</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Self-Documenting Code Has a Blind Spot: the Why]]></title>
            <link>https://scribelet.app/blog/self-documenting-code</link>
            <guid isPermaLink="false">https://scribelet.app/blog/self-documenting-code</guid>
            <pubDate>Tue, 08 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Self-documenting code handles what the code does. It cannot capture why. Where a comment earns its place, and where the reasoning actually belongs. Try it free.]]></description>
            <content:encoded><![CDATA[
You open a file you wrote six months ago. The functions are named well. The variables read like plain English. There are no clever one-liners, no cryptic abbreviations, no dead code. By every standard you were taught, this is good, self-documenting code, and you are proud of it. Then you hit one function that does something slightly strange. It retries a call three times, then falls back to a cached value that is allowed to be up to an hour stale. The names are perfect. You can see exactly what it does. And you cannot for the life of you remember why. Why three retries and not five? Why is an hour of staleness acceptable here when it would be a bug anywhere else? You wrote this. The code told you everything except the one thing you needed.

That gap is the whole argument. "Self-documenting code" is one of the most reliable ways to start a fight among engineers, and both sides are usually arguing about the wrong thing. One camp says good names and clean structure make comments unnecessary. The other says comments are essential and anyone who skips them is lazy. They are both talking about how to document *what the code does*. Almost nobody is talking about the thing code genuinely cannot document, which is *why the code is the way it is*. Get that distinction straight and the entire debate resolves into something useful. Here is what self-documenting code actually is, what it can and cannot carry, and where the reasoning has to live instead. ([Scribelet](https://scribelet.app) is built to keep that reasoning from going missing, but the discipline matters whatever tool you use.)

## What is self-documenting code?

Self-documenting code is code written so that its purpose and behavior are clear from the code itself, primarily through descriptive names, small focused functions, clear control flow, and expressive types, with minimal reliance on comments to explain what is happening. The idea, associated with the [Clean Code](https://en.wikipedia.org/wiki/Self-documenting_code) tradition and decades of practice before it, is that a comment explaining what a line does is a symptom: if the line needed the comment, the line was not clear enough. Rename the variable, extract the function, and the comment becomes redundant.

This is real and it is worth doing. A function called `calculateTax(order)` tells you more at a glance than `process(x)` with a comment that says "calculates tax." A name that honestly predicts its behavior is one application of [the principle of least surprise](/blog/principle-of-least-astonishment): make the code behave the way whoever reads the name already expects. Code that reads top to bottom without surprises is genuinely easier to maintain than code padded with narration. The self-documenting instinct is correct about a large and important category of comments: the ones that restate the mechanics. Those comments rot, they drift out of sync with the code they describe, and they are noise. If your only defense of comments is "explain what each line does," the self-documenting camp is right and you should write better names instead.

The mistake is treating that win as the whole game. Naming and structure document the *what*. They are silent, by construction, about the *why*, and the why is usually the part you actually come back for.

## The two things code has to explain, and only one is in the code

Every piece of nontrivial code answers two separate questions, and they are not the same question.

The first is **what does this do**. What is the input, what is the output, what is the sequence of steps. This is mechanical, it is fully present in the source, and good naming and structure express it well. If you cannot tell what a function does from reading it, that is a code-quality problem, and self-documenting code is the right fix. And when clear code still hides a bug, [explaining it line by line to a rubber duck](/blog/rubber-duck-debugging) usually surfaces it, because asserting each step out loud catches the assumption your eyes kept skimming past.

The second is **why is it like this**. Why this approach and not the obvious alternative. What constraint forced the ugly branch. What you tried first that did not work. What will break if someone "simplifies" it later. A parser deliberately made [liberal in what it accepts](/blog/postels-law) is the sharpest case: the code plainly shows that it tolerates a malformed input, and says nothing about which partner it was forgiving or when the leniency can finally be removed. This information is not in the code, and it cannot be, because the rejected alternatives are not in the code. The three-retry loop does not contain the incident that taught you the downstream service flaps for exactly two retries under load. The one-hour staleness does not contain the product decision that this screen tolerates stale data and the billing screen does not. The code is the answer; the why is the question it was answering, and the question is gone. It usually goes unwritten for a specific reason: to the person who made the call, the reasoning felt too obvious to record, which is [the curse of knowledge](/blog/curse-of-knowledge) doing its quiet damage. The stakes are highest for a line that looks wasteful but is quietly guarding speed: delete the cache or the deliberately un-abstracted hot path because nothing records why it exists, and you [reopen the performance gap a lean system fought to close](/blog/wirths-law).

| Question | Lives in the code? | Best expressed by |
|---|---|---|
| What does this do? | Yes | Names, structure, types, small functions |
| What are the steps, in order? | Yes | Control flow, function decomposition |
| Why this approach over the obvious one? | No | A recorded decision (comment, commit, ADR, spec) |
| What did we try that failed? | No | A decision log or postmortem |
| What breaks if you "clean this up"? | No | A comment at the site, or a linked decision record |
| What constraint or deadline shaped it? | No | Context outside the code entirely |

Read that table and the debate dissolves. The self-documenting camp is right about the top rows and wrong to generalize to the bottom ones. The pro-comment camp is right that something has to carry the bottom rows and wrong to reach for line-by-line narration to do it. Clean names are necessary. They are not sufficient.

![Two panels. On the left in green, what lives in the code: names, structure, and types, all handled by self-documenting code. On the right in amber, what is not in the code: why three retries not five, what was tried and dropped, and what breaks if you simplify it, which must live in a comment, an ADR, or a spec. A strip below notes the why decays because nothing tests a comment.](/blog/self-documenting-code/what-vs-why.svg)

## A function that documents itself perfectly and still tells you nothing

Here is the retry example, written as well as I know how. Every name is honest, the structure is flat, there is nothing to rename.

```javascript
async function getExchangeRate(currencyPair) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const rate = await rateProvider.fetch(currencyPair);
    if (rate.isFresh) return rate;
  }
  return rateCache.get(currencyPair, { maxStalenessMinutes: 60 });
}
```

You can read every line. You know exactly what it does. Now answer the questions that matter in a review or an incident at 2 a.m.: Why three attempts? Why is a stale rate acceptable at all in a function about money? Why sixty minutes and not five? The code is mute, and no amount of renaming will make it speak, because the answers are facts about the world outside the function. The honest version needs one thing the self-documenting version cannot provide:

```javascript
async function getExchangeRate(currencyPair) {
  // Provider flaps under load and recovers within 2 retries (INC-4412).
  // A third attempt is cheap insurance; a fourth never helped in the data.
  for (let attempt = 0; attempt < 3; attempt++) {
    const rate = await rateProvider.fetch(currencyPair);
    if (rate.isFresh) return rate;
  }
  // Display-only surface: a <1h stale rate is a product-approved tradeoff
  // (see pricing spec). Do NOT copy this fallback into billing.
  return rateCache.get(currencyPair, { maxStalenessMinutes: 60 });
}
```

Those comments do not explain what the code does. The code already did that. They explain why it does it, and they point at the incident and the spec where the full reasoning lives. That is the category of comment self-documenting code should never delete, because there is no name you can give a variable that encodes "we learned this from INC-4412."

## When a comment earns its place

Not every comment is worth keeping, and the self-documenting instinct is a good filter. The test is simple: a comment that restates the code is noise and should be deleted in favor of a better name; a comment that supplies something the code cannot contain is signal and should be kept and maintained. Use this to decide what to do with any given comment.

| The comment says... | Do this instead |
|---|---|
| What a line mechanically does ("increment the counter") | Delete it. Rename the variable or extract the function so the code says it. |
| What a block does, because the block is a mess | Extract the block into a well-named function. The name replaces the comment. |
| Why this approach was chosen over an obvious alternative | Keep it. This is the why; code cannot hold it. |
| What non-obvious constraint or bug shaped the code | Keep it, and link the incident or ticket. |
| What will break if someone changes this | Keep it. It is a warning to the next person, including future you. |
| A whole subsystem's design and tradeoffs | Move it out of the comment and into a durable record: a [design document](/blog/software-design-document) or an [architecture decision record](/blog/architecture-decision-record-examples). |

The pattern is that the *what* gets pushed into the code through naming and extraction, and the *why* gets pulled out of the code into a comment or, when it is bigger than a comment, into a document. Self-documenting code and good documentation are not opponents. They divide the labor.

## Where the "why" actually belongs

Once you accept that the why has to live somewhere, the next question is where. A comment at the code site is the right home for a local, small reason. A larger reason, one that spans files or explains a whole design, outgrows the comment and needs a real record. These channels are not interchangeable, and picking the wrong one is why reasoning gets lost.

| Channel | Good for | Fails at |
|---|---|---|
| Names and structure | What the code does | Anything about why |
| Inline comment | A local why, right where it applies | Design-level reasoning; gets buried, one reader at a time |
| Docstring / API doc | Contract of a function or module for callers | The reasoning behind the contract |
| Commit message | Why this specific change happened | Discoverability later; nobody greps git log during a review |
| Architecture decision record (ADR) | A durable, discoverable design decision and its rejected alternatives | Tiny local quirks (overkill) |
| [Technical spec](/blog/technical-spec) or design doc | The reasoning for a whole feature before it is built | Line-level detail after the fact |

Most teams already have some of these. The failure is rarely that the channels do not exist; it is that the why never gets written into any of them, so it stays in one person's head. That is how a well-named codebase still ends up with a [bus factor](/blog/bus-factor) of one, and how the next engineer inherits code they can read perfectly and cannot safely change, which is [Chesterton's fence](/blog/chestertons-fence) in its purest form: a fence with no sign, and no way to tell if it is load-bearing without testing it the hard way. There is a second, subtler cost to leaving the why unwritten: without a recorded contract for what a function actually promises, its callers infer the contract from watching it run, and eventually depend on whatever it happens to do rather than what you meant it to do. That is [Hyrum's law](/blog/hyrums-law), and a docstring that states the intended contract explicitly is one of the few things that keeps an implicit interface from silently becoming the real one. If keeping that reasoning attached to your work sounds like a chore worth automating, [that is the problem Scribelet exists for](https://scribelet.app).

## The part nobody maintains: your reasons decay too

Here is the failure mode underneath the whole debate. Suppose you do the right thing. You write self-documenting code for the what, and you record the why in a comment or an ADR. You are still not safe, because the why does not stay true on its own. The retry comment that said "provider flaps within 2 retries, INC-4412" was accurate the day you wrote it. Then the provider fixed their infrastructure, or you migrated to a new one, and now the comment describes a world that no longer exists. It reads with total authority, it points at a real incident, and it is wrong. A confidently wrong comment is worse than no comment, because the next engineer trusts it and designs around a constraint that was lifted a year ago.

This is [knowledge decay](/blog/knowledge-decay), and it hits the *why* far harder than the *what*, for a simple reason: the code's behavior is checked constantly by tests and by production, so a false claim about what the code does gets caught. A claim about why is never executed. Nothing tests a comment. So the reasoning quietly [goes out of date](/blog/outdated-documentation) while the code keeps running, and the gap between what the comment says and what is actually true widens with every month nobody rereads it. Self-documenting code cannot save you here either, because the thing that rotted was never in the code to begin with.

The problem is getting sharper, not softer, because of how code is written now. [Agentic coding](/blog/agentic-coding) tools produce clean, well-named, genuinely self-documenting code faster than any human, and they strip the why completely. The agent that chose three retries had a reason in its context window, and that reason evaporates the moment the session ends. You are left with immaculate code and zero record of the tradeoffs behind it, which is the self-documenting blind spot at machine scale. The more of your codebase is written by something that cannot remember why, the more the why has to be captured deliberately and kept current, or it is gone.

This is what Scribelet is built for. Its background agents re-check the notes, decisions, and docs you keep against reality on a schedule and show you a diff when a claim no longer holds, so the "why" behind a piece of code does not silently drift into fiction. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. The reasoning behind your code is [internal documentation](/blog/internal-documentation) like any other, and it is worth keeping honest.

## Getting started

Stop arguing about whether to write comments. Split the question instead. For the *what*, write self-documenting code: good names, small functions, clear flow, and delete every comment that just narrates the mechanics. For the *why*, do the opposite of what the self-documenting purists preach: write it down deliberately, right where it applies for a local reason and in a durable record for a design-level one, because the code cannot hold it and your memory will not either.

Then maintain the why the way you maintain the code, because it decays the same way and nothing tests it for you. [Try Scribelet free](https://scribelet.app) and let it keep the reasoning behind your code honest as the code, and the world it runs in, keep changing. The best-named function in your codebase still cannot tell the next person why. That part is on you to write down, and to keep true.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>self-documenting-code</category>
            <category>code-comments</category>
            <category>documentation</category>
            <category>engineering</category>
            <category>knowledge-decay</category>
            <category>code-quality</category>
        </item>
        <item>
            <title><![CDATA[Definition of Done: A Practical Guide with Examples]]></title>
            <link>https://scribelet.app/blog/definition-of-done</link>
            <guid isPermaLink="false">https://scribelet.app/blog/definition-of-done</guid>
            <pubDate>Mon, 07 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A definition of done is the shared checklist that decides when work is actually finished. What it is, what goes in it, and how to keep it honest. Try it free.]]></description>
            <content:encoded><![CDATA[
Ask three people on a team when a task is done and you will get three answers. The developer says done means the code is written and merged. The tester says done means it passed QA. The product owner says done means a customer can use it in production. Everyone is telling the truth, and everyone is talking about a different finish line. So the ticket gets dragged to the "Done" column, the sprint closes, and two days later the thing that was done turns out to need tests, a migration, a docs update, and a release nobody scheduled. The work was never actually finished. It was finished according to whoever moved the card.

A definition of done is the fix for that. It is a single, written, agreed list of what "finished" means, applied to every piece of work the same way, so "done" stops being a matter of opinion. A fixed finish line also keeps a single task from sprawling: without one, it is easy to [keep fixing prerequisite after prerequisite](/blog/yak-shaving) until the item you actually set out to finish is lost, the trap of yak shaving. It is one of the cheapest quality tools a team can adopt and one of the most commonly faked, because a list that everyone nods at and nobody enforces is worse than none. Here is what a definition of done actually is, what belongs in one, how it differs from the two things it gets confused with, and the failure mode that quietly kills most of them.

## What is a definition of done?

A [definition of done](https://en.wikipedia.org/wiki/Definition_of_done) (often shortened to DoD) is a shared, explicit set of criteria that a piece of work must meet before the team agrees it is complete. It is not a description of the feature and it is not a to-do list for one task. It is the standard, the same for every item, that separates "someone stopped working on it" from "it is genuinely finished and can be trusted."

The concept comes from Scrum, where the [Scrum Guide](https://scrumguides.org/scrum-guide.html) calls the definition of done a formal description of the state of the increment when it meets the quality measures required for the product. But you do not need Scrum, sprints, or any agile ceremony to use one. Any team that hands work between people, or ships work to users, benefits from writing down what "done" means once instead of relitigating it per ticket. A solo developer benefits too, because the version of you that starts a task and the version that wants to call it finished are, effectively, two different people who disagree about the finish line.

The value is not the list itself. It is that the list is agreed and visible before the work starts. When "done" is defined up front, "is this done?" becomes a question you can answer by reading, not by arguing. That is the whole point: it moves the finish line out of individual heads and into a place the team can point at. With the line written down, a reviewer cannot quietly [move the goalposts after the work has already met the bar](/blog/moving-the-goalposts), because the standard everyone agreed to is on record. If your team's shared understanding of "finished" lives only in memory and hallway conversations, [writing it down somewhere it stays current](https://scribelet.app) is the first improvement worth making.

## Definition of done vs definition of ready vs acceptance criteria

Three terms get used interchangeably and mean genuinely different things. Confusing them is the single most common mistake teams make with a DoD, and it shows up in every "DoR vs DoD" thread. The distinction is worth holding precisely, because each answers a different question at a different moment.

| | Definition of Ready | Definition of Done | Acceptance Criteria |
|---|---|---|---|
| **Answers** | Can we start this work? | Is any work truly finished? | Does this specific item do what was asked? |
| **Scope** | The same for every item | The same for every item | Different for each item |
| **Timing** | Before work begins | Before work is called complete | Written with the item, checked at the end |
| **Example** | "Has clear acceptance criteria, is estimated, has no blockers" | "Code reviewed, tests pass, docs updated, deployed to staging" | "User can reset their password and receives a confirmation email" |

The definition of ready and the definition of done are both team-wide standards, one guarding the entrance and one guarding the exit. Acceptance criteria are per-item: they describe what this particular story must do. A story is *done* only when it satisfies both its own acceptance criteria (the feature works as specified) and the team's definition of done (it was built to the team's quality bar). You need both. Acceptance criteria without a definition of done gives you features that work and code nobody can maintain. A definition of done without acceptance criteria gives you well-tested work that solves the wrong problem.

Want the difference to stick? Keep all three where the team can see them, not buried in three different tools. [Try Scribelet free](https://scribelet.app) and keep your standards next to the work they govern.

## What goes in a definition of done

A good definition of done is short, specific, and binary. Every item is something a reasonable person can check and answer yes or no to, with no interpretation. "Code is clean" is not a DoD item, because two people will disagree about clean. "Code passed review and the linter reports no errors" is, because there is nothing to argue about.

It also helps to recognize that "done" exists at more than one level. What is done for a single task is not the same as what is done for a release. Splitting the DoD by level keeps each one honest instead of cramming release concerns into every ticket.

Here is a starting template you can copy and adapt. Delete what does not apply to your team and add what does; the goal is the shortest list that actually protects quality.

```
Definition of Done

Story / task level (every work item):
- [ ] Code written and self-reviewed
- [ ] Peer reviewed and approved (PR merged)
- [ ] Automated tests written and passing
- [ ] Linter and type checks pass, no new warnings
- [ ] Acceptance criteria for the item all met
- [ ] Relevant docs / comments updated
- [ ] No known defects left open

Sprint / increment level (the batch of work):
- [ ] All included stories meet the story-level DoD
- [ ] Integrated and passing on the main branch
- [ ] Deployed to a staging / test environment
- [ ] Product owner has reviewed and accepted

Release level (shipping to users):
- [ ] Passed QA / regression on staging
- [ ] Monitoring and alerts in place for new behavior
- [ ] Rollback plan documented
- [ ] User-facing docs / changelog updated
- [ ] Stakeholders notified
```

The three functions a definition of done performs, once it exists, are worth naming because they are what you lose without it: it creates a **shared understanding** of quality so handoffs stop breaking, it makes work **transparent** so "done" means the same thing on every card, and it protects the increment's **quality** by making the bar automatic instead of a per-ticket negotiation. Who prepares it? The whole team, not a manager handing one down. A DoD imposed from above gets ignored; one the developers, testers, and product owner wrote together gets used, because they agreed to it. It typically lives wherever the team already keeps its [internal documentation](/blog/internal-documentation), and it is often enforced right at the [pull request template](/blog/pull-request-template) so the checklist meets the code at merge time.

## Definition of done examples

The right definition of done depends on what kind of work you are finishing. A one-size-fits-all list forces bug fixes through release-level ceremony and lets risky changes through with a story-level rubber stamp. These examples show how the bar shifts by work type.

| Work type | What "done" needs to include |
|---|---|
| New feature | Reviewed, tested, acceptance criteria met, docs updated, behind a flag or deployed to staging, product owner accepted |
| Bug fix | Root cause identified, regression test added so it cannot recur silently, fix verified against the original report, no new failures |
| Spike / research | Question answered in writing, findings recorded where the team will find them, a recommendation or decision captured, next step defined |
| Infrastructure change | Change reviewed, applied to staging first, rollback path documented, monitoring updated, no manual step left undocumented |
| Documentation-only | Reviewed for accuracy against the current system, links checked, dated, owner assigned for the next review |

Notice that every row ends with something being written down and something being verifiable later. That is not an accident. A definition of done is, underneath, a promise that the next person can trust the work without re-checking it, and that trust only holds if the evidence outlives the moment. A spike whose findings live in someone's head is not done, no matter how much was learned, because the moment that person forgets or leaves, the work has to be redone. This is the same reasoning behind capturing a decision as an [architecture decision record](/blog/architecture-decision-record-examples): finished means legible to someone who was not there.

![Three roles (developer, tester, product owner) each holding a different idea of done, all passing their work item through a single shared Definition of Done checklist, which produces one agreed Done](/blog/definition-of-done/definition-of-done-gate.svg)

The diagram is the whole idea in one picture. Three people arrive with three private finish lines. The definition of done is the single gate they all pass through, and only work that clears every criterion comes out the other side as genuinely, agreed-upon done. Without the gate, each person's "done" is valid and they never match. With it, "done" is one thing, checkable by anyone.

## The part nobody maintains: your definition of done rots too

Here is the failure mode that kills most definitions of done, and it is not the one people expect. Teams assume the risk is not having a DoD. The bigger risk is having one that has quietly stopped being true.

A definition of done is written once, in a burst of good intentions, usually in a wiki page or a Confluence doc during a team offsite. Then the world moves. The team adopts a new CI system, so "runs the old test suite" is now meaningless. A deployment step gets automated, so a manual checklist item is now a lie. A quality bar that mattered two years ago no longer does, and a new one that matters a lot is not on the list because the list has not been opened since it was written. Every checkbox still gets ticked, because ticking boxes is easy, but the boxes no longer describe reality. This is checkbox theater: the ritual of a definition of done with none of the protection, and it is arguably worse than having no DoD at all, because the team still trusts the ritual while it silently passes work that is not done.

The root cause is that the *reasons* behind each criterion decay faster than the criteria themselves. Somebody added "deploy to staging" because of a specific production incident, and once the memory of that incident fades, the item looks like bureaucracy and gets skipped or deleted. The checklist survives; the argument for it does not, and a criterion you can no longer justify is one that will not survive the next person who finds it annoying. This is the same [knowledge decay](/blog/knowledge-decay) that hits every kind of working agreement, and it hits a DoD especially hard because it is exactly the kind of document teams write once and never revisit. When only one or two people remember why the definition of done is shaped the way it is, you also have a [bus factor](/blog/bus-factor) problem sitting under your quality one.

This is the problem Scribelet is built for. Its background agents re-check your notes and docs against reality on a schedule and show you a diff when something no longer holds, so a definition of done that has drifted from how the team actually ships gets flagged instead of silently rotting. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. A quality checklist that has [gone quietly out of date](/blog/outdated-documentation) does more damage than an honest absence, because the green checkmarks keep the team confident while the bar erodes. Keeping the *why* attached to each criterion is what turns a one-time offsite exercise into a standard that still means something a year later, the same discipline that keeps a [technical spec](/blog/technical-spec) honest as the system it describes changes underneath it.

## Getting started

A definition of done is not scrum overhead and it is not a document you write to satisfy an auditor. It is the difference between "someone stopped working on this" and "this is finished and you can trust it," made explicit so nobody has to guess. The teams that get value from one treat it as a living agreement, not a plaque.

Start small. Get the team in a room and write down, in binary and checkable terms, what has to be true before any work is called done. Keep it to the shortest list that actually protects quality, put it where the work happens rather than in a wiki nobody opens, and schedule a look at it every few months to cut what no longer applies and add what now does. [Try Scribelet free](https://scribelet.app) and let it keep your definition of done honest as the way you build keeps changing. A finish line only works if everyone can see it and it still marks the right spot.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>definition-of-done</category>
            <category>agile</category>
            <category>engineering</category>
            <category>scrum</category>
            <category>documentation</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Feature Creep: Why Products Bloat and How to Stop It]]></title>
            <link>https://scribelet.app/blog/feature-creep</link>
            <guid isPermaLink="false">https://scribelet.app/blog/feature-creep</guid>
            <pubDate>Sun, 06 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Feature creep is how a focused product slowly turns into a cluttered one. What it is, why it happens, and how to stop it before it ships. Try it free.]]></description>
            <content:encoded><![CDATA[
The app started as one screen. You typed a thing, it saved the thing, done. Then someone wanted tags, so tags went in. Then a customer asked for folders, and folders were reasonable, so folders went in too. A big account needed a permissions model, and you were not going to lose the account, so that went in. Two years later the settings page has forty toggles, the onboarding takes six screens, and a new user opens the thing that used to do one job and cannot find where to type. Nobody decided to build that product. It accreted, one reasonable yes at a time.

That accretion has a name. Feature creep is the slow, uncontrolled growth of a product past the job it was built to do, and it is almost never the result of a bad decision. It is the result of a hundred individually defensible ones, made by people who could not see the sum. The dangerous part is exactly that each step looks fine in isolation. You cannot fight feature creep by making better single decisions, because the single decisions were already fine. You fight it by keeping the shape of the whole in view while you make them. Here is what feature creep actually is, why it happens even to careful teams, and the specific practices that keep a product from bloating into something nobody meant to build.

## What is feature creep?

[Feature creep](https://en.wikipedia.org/wiki/Feature_creep) is the continuous, incremental addition of features to a product beyond its original scope, to the point where the additions start to undermine the product rather than improve it. Each new feature arrives with a real reason: a customer request, a competitor's checkbox, an internal idea nobody wanted to say no to. The problem is not any one feature. The problem is the cumulative weight of all of them landing on a product that was designed to carry less.

It shows up as a specific set of symptoms. The interface grows more surface area than a new user can learn. The codebase grows more paths than the team can test. The roadmap grows more commitments than the release can hold, so ship dates slip. And the original thing the product did well gets harder to find under everything layered on top of it. The classic shorthand is the software that tried to please everyone and ended up serving no one particularly well. The same accretion carries a hidden performance cost, the product growing heavier as it grows wider, which is exactly what [Wirth's law](/blog/wirths-law) describes: software slowing down about as fast as hardware speeds up.

Feature creep is close kin to scope creep, and the two are often used interchangeably, but the distinction is worth holding. Scope creep is a project-management problem: the agreed boundaries of a piece of work expand while it is in flight. Feature creep is a product problem: the product itself grows past the coherent thing it was meant to be, release after release, often across years and multiple teams. Scope creep blows a deadline: every mid-flight addition [re-opens an estimate range that was starting to close](/blog/cone-of-uncertainty), so the plan is measuring a target that keeps moving. Feature creep blows the identity of the product. Both differ again from [a bar for "done" that rises only after you clear it](/blog/moving-the-goalposts), which moves the standard the work is judged against rather than the list of features it contains. The same pull compressed into a single afternoon, where one prerequisite task spawns the next until you have lost the thread of what you sat down to do, is [yak shaving](/blog/yak-shaving). If your notes about what the product is *for* have drifted out of date, you are already most of the way there, and [keeping that kind of reasoning current](https://scribelet.app) is a problem worth solving on purpose.

## Why feature creep happens even to careful teams

Feature creep is not a discipline failure. It is the default outcome of forces that push in one direction, and almost nothing pushes back. Adding is visible, additive, and easy to justify in a single meeting. Not adding is invisible, feels like loss, and requires an argument nobody has time to make. Left alone, a product only grows.

The pressure comes from a few recurring sources, and naming them is the first step to resisting them.

| Where the pressure comes from | Why it is hard to refuse |
|---|---|
| A big customer's request | Saying no risks the account, so the feature ships even when it fits nobody else |
| A competitor's feature list | "They have it and we don't" reads as a gap, even when the feature is dead weight for both of you |
| An internal idea with a champion | Someone senior wants it, and the cost of arguing exceeds the cost of building it |
| The urge to out-build the last version | The [second-system effect](/blog/second-system-effect): the follow-up to a lean first release tends to accumulate every feature the first one left out |
| The sunk-cost of a half-built thing | It is nearly done, so it ships, even though "nearly done" is where scope goes to hide |
| A vague original spec | With no clear line for what is in and out, every request looks equally in-scope |

Notice what every row has in common: the reason to add is loud and immediate, and the reason to hold the line is quiet and long-term. Each feature is a small decision with a clear upside and a diffuse, deferred cost, which is exactly the shape of decision humans make badly. This is where [second-order thinking](/blog/second-order-thinking) earns its place: the first-order effect of a feature is "the customer is happy," and the second- and third-order effects are the added test surface, the slower onboarding, the maintenance nobody budgeted, and the next feature that now has to be compatible with this one. Judge only the first order and you will say yes every time.

Want your product's scope to survive its own success? Start with a written boundary you can point back to. [Try Scribelet free](https://scribelet.app) and keep the "what this is for" note somewhere it stays true.

## Feature creep examples

Feature creep is easiest to recognize in products you already know. The pattern repeats across every category of software.

| Situation | What feature creep produced |
|---|---|
| A simple utility app adds "just one more" mode each release | A settings screen with dozens of toggles most users never touch and cannot understand |
| A messaging tool bolts on tasks, calendars, and docs | A slower app that does five jobs adequately and its original job worse than before |
| A B2B product says yes to every enterprise deal | A configuration surface so large that no two customers run the same product, and support cannot reproduce bugs |
| A game keeps adding systems during development | A release date that slips for years while the core loop stays unfinished under the new systems |
| An API grows a parameter for every edge case | A signature no one can call correctly without reading the whole changelog |

The shape in every row is the same. The feature that caused each problem was, on the day it shipped, a defensible call. The damage is only visible in aggregate, which is why it is so rarely caught by the person approving the individual feature. Read any single decision and it looks fine. Read the sum and the product has lost its center.

## Feature creep vs. healthy growth: how to tell them apart

The hard part is that not all growth is creep. Products should add features. The skill is telling a feature that deepens the product from one that dilutes it, and that judgment can be made deliberately instead of by gut. Run each proposed addition through the same questions, and the difference gets sharp fast.

| Question | Healthy growth | Feature creep |
|---|---|---|
| Who is it for? | A core user you already serve, doing the job the product exists for | A single account, or "someone," or a hypothetical user nobody can name |
| Does it deepen the core or widen it? | Makes the main job better or faster | Adds a new, unrelated job the product now half-does |
| What is the real cost? | Understood and accepted, including maintenance | Estimated as build time only, with the ongoing cost ignored |
| What does it displace? | A conscious tradeoff against something less valuable | Nothing named, because "we can do both" was assumed |
| Would you build it if it were not free? | Yes, it earns its place against alternatives | Only because refusing felt worse than building |

A feature that answers the left column is worth adding even though it grows the product. A feature that answers the right column is creep wearing the costume of progress. The bias to protect is the one the whole [keep-it-simple principle](https://en.wikipedia.org/wiki/KISS_principle) was written to defend: when two designs solve the same problem, the smaller one is usually the better product.

![A curve of product value against features added over time: it rises while each feature deepens the core, peaks at the line of coherent scope, then falls as each further feature dilutes the product](/blog/feature-creep/feature-value-curve.svg)

The peak is the point worth naming. Before it, every feature you add makes the product better at its job. After it, every feature you add makes the product worse at its job even though each one, in isolation, still looks like an improvement. Feature creep is simply the failure to notice you have crossed the peak, and you cross it one reasonable yes at a time. The questions matter more than any single answer, because they force the diffuse cost into the open where it can lose to a better use of the same effort. This is a [decision worth making with a framework](/blog/decision-making-framework) rather than by whoever asked most recently or most loudly.

## How to prevent feature creep

Preventing feature creep is not about saying no to everything. It is about making the cost of "yes" visible at the moment of decision, so the easy add has to earn its place against the quiet long-term price. A few practices do most of the work.

**Write the scope down before you build, and name what is out.** A product or [design document](/blog/software-design-document) that states the job the release is for gives every later request a line to be measured against. The out-of-scope list matters more than the in-scope one, because it is the thing you will be tempted to quietly violate. A [technical spec](/blog/technical-spec) with an explicit "what we are not building" section is the cheapest anti-creep tool there is.

**Record every feature decision, including the noes.** The reasons a feature was rejected are the first thing a team forgets, and a forgotten no becomes a yes the next time someone asks. Capturing the decision the way you would an [architecture decision record](/blog/architecture-decision-record-examples), with the rationale attached, means the second request for the same feature meets the first answer instead of starting fresh.

**Make someone accountable for subtraction.** Addition has a hundred champions; removal has none unless you assign it. A product owner whose job explicitly includes cutting and simplifying, not only shipping, is the counterweight the default is missing.

**Budget the ongoing cost, not just the build.** Every feature is a permanent liability: it has to be tested, documented, supported, and kept compatible with everything that comes after. Estimate that recurring cost when you approve the feature, and a surprising number of "quick wins" stop looking cheap.

Use a short, standing record for each request so the decision and its reasons survive the meeting. Something this simple is enough:

| Field | What to capture |
|---|---|
| Request | The feature, in one line, and who asked |
| Job it serves | The core user and the job, or "none identified" |
| Real cost | Build plus the ongoing test, support, and maintenance burden |
| Decision | In, out, or deferred, with the date |
| Why | The one-sentence reason, so the next person who asks meets it |
| Revisit | When this should be re-examined, if ever |

The point of writing it down is not bureaucracy. It is that the reasoning is the thing that decays, and a decision you can no longer explain is one you cannot defend when the same request comes back.

## The part nobody maintains: your scope decays too

Here is the failure mode underneath all of this. Feature creep is usually framed as a willpower problem, as if teams just need to say no more often. That framing misses why careful teams still bloat their products. The real cause is that the *reasons* behind the product's boundaries go stale, and once the reasons are gone, the boundary is indefensible.

Think about what actually happens. On the day you decided not to build calendar integration, you had good reasons: it served a user you were not targeting, the maintenance cost was high, it pulled focus from the core. Those reasons lived in someone's head, or in a Slack thread, or in a spec nobody has opened since. A year later a new PM gets the same request, cannot find the reasoning, and cannot see any reason *not* to build it. So it ships. The boundary did not fall because anyone disagreed with it. It fell because the argument for it decayed and left the boundary standing there naked, and a boundary you can no longer explain is a boundary you will eventually cross.

This is the same rot that hits every kind of working knowledge, and it hits scope decisions especially hard because they are rarely written down as decisions in the first place. This is the problem Scribelet is built for. Its background agents re-check your notes and docs against reality on a schedule and show you a diff when something no longer holds, so the reasoning behind a "no" stays attached to the "no" instead of evaporating. Your keys, your model, your data: the agents run on the provider you choose, and you see exactly what changed and why. A product scope document that has [quietly gone out of date](/blog/outdated-documentation) is worse than none, because the team still trusts it while it silently permits the next feature. Keeping the *why* current is what turns a one-time decision into a boundary that actually holds, and it is the same discipline that fights [knowledge decay](/blog/knowledge-decay) everywhere else in your work. When only one or two people remember why the product is shaped the way it is, you also have a [bus factor problem](/blog/bus-factor) sitting on top of your feature-creep one.

## Getting started

Feature creep is not a moral failing and it is not solved by heroic restraint. It is the predictable result of a system where adding is easy and remembering why you said no is hard. Fix the second half and the first takes care of itself.

Start with one document: write down what your product is for and, more importantly, what it is not for. Then record each feature decision against it, the noes as carefully as the yeses, with the reasoning attached. The reasoning is the part that decays, so it is the part worth maintaining. [Try Scribelet free](https://scribelet.app) and let it keep your scope notes honest as the requests keep coming. A product stays focused not because its team never adds anything, but because it can still explain, a year later, why it drew the line where it did.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>feature-creep</category>
            <category>product-development</category>
            <category>engineering</category>
            <category>scope</category>
            <category>knowledge-decay</category>
            <category>documentation</category>
        </item>
        <item>
            <title><![CDATA[Second-Order Thinking: See the Consequences of Consequences]]></title>
            <link>https://scribelet.app/blog/second-order-thinking</link>
            <guid isPermaLink="false">https://scribelet.app/blog/second-order-thinking</guid>
            <pubDate>Sat, 05 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Second-order thinking traces the effects of your effects. This guide shows a worked three-order trace, when it is worth the effort, and how to catch it when you are wrong. Try it free.]]></description>
            <content:encoded><![CDATA[
Britain's colonial government in Delhi had a cobra problem, so it offered a bounty for dead cobras. First-order thinking: pay for dead snakes, get fewer snakes. Then people started breeding cobras to collect the bounty, the government scrapped the program, the breeders released their now-worthless snakes, and Delhi ended up with more cobras than before it started. That is the [cobra effect](https://en.wikipedia.org/wiki/Cobra_effect), and it is what first-order thinking looks like from one step downstream. It is also the textbook case of [Goodhart's law](/blog/goodharts-law): the bounty turned dead cobras into a target, and the moment a measure becomes a target, people optimize the measure instead of the thing it was supposed to stand for. When the stakes on that measure climb high enough, [the damage spreads to the underlying activity and not just the number](/blog/campbells-law).

Second-order thinking is the habit of not stopping at the first consequence. Every roundup will define it for you in a sentence and hand you the "and then what?" prompt, and that is where they all stop. Two things are missing from that version. The first is a worked trace you can actually copy, run three orders deep on a real decision, because the skill lives in the doing and not the definition. The second is quieter and more expensive: second-order effects arrive *later*, sometimes years later, which means the only way to know whether your reasoning was any good is to have written the prediction down and gone back to check it. This guide covers both, including how a [note that fights its own decay](https://scribelet.app) turns that second half from a chore into something automatic.

## What is second-order thinking?

Second-order thinking is a mental model for tracing the downstream effects of a decision instead of stopping at the immediate one. First-order thinking answers "what happens if I do this?" Second-order thinking asks the follow-up that separates good judgment from fast judgment: "and then what?" You keep asking it, one link at a time, until the chain of consequences stops teaching you anything new.

The idea has two well-known homes. Shane Parrish's [Farnam Street essay](https://fs.blog/second-order-thinking/) frames it as the thing that separates careful decision-makers from everyone chasing the obvious win, and the investor Howard Marks built a career on what he calls "second-level thinking," the observation in [his Oaktree memo "It's Not Easy"](https://www.oaktreecapital.com/insights/memo/it-s-not-easy) that you cannot beat the average by making the average, first-order forecast. Both are pointing at the same move: the first consequence is usually visible to everyone, so it is already priced into the situation. The edge is in the second and third. A first-order read of a single aggregate is a classic version of the trap, because [a pooled number can reverse the moment you split it by group](/blog/simpsons-paradox). It is cousin to [the habit of hunting for answers where the light is good instead of where you actually dropped them](/blog/streetlight-effect), which quietly decides what evidence you ever put in front of yourself.

It helps to name the orders explicitly:

- **First-order thinking** is the immediate, obvious result. "If I cut the price, we sell more units." Fast, cheap, and often right about the short term.
- **Second-order thinking** is the effect of that effect. "We sell more units, so a competitor matches the cut, so we are both selling more for less and the margin is gone."
- **Third-order thinking** is the next link. "Margins compress across the category, a smaller rival cannot survive it, and we end up with one fewer competitor and a price war we cannot easily exit."

Almost nobody needs a fourth order in practice. The value is almost entirely in getting past the first.

## First-order versus second-order thinking

The difference is not intelligence, it is where you let yourself stop. First-order thinking is not wrong; it is incomplete, and it is incomplete in a way that feels complete, which is exactly what makes it dangerous.

| | First-order thinking | Second-order thinking |
|---|---|---|
| The question | "What happens if I do this?" | "And then what happens?" |
| Time horizon | Immediate, obvious | Delayed, often hidden |
| Effort | Instant, feels like the whole answer | Deliberate, requires walking the chain |
| Typical failure | Solving the visible problem, creating an invisible one | Overthinking a decision you could just reverse |
| Who does it by default | Everyone | Almost no one |

The trap is that first-order thinking is *usually fine*. Most of the day is made of two-way doors where the immediate answer is the whole answer. The skill is not applying second-order thinking to everything. It is recognizing the small number of decisions where the second order is where all the cost lives, and slowing down for exactly those.

## A worked example: trace it three orders deep

Here is the part the definitions skip. Pick a real decision and walk it, one column at a time, writing down the consequence at each order before you judge any of them. The point of putting it in a table is that it forces you to keep going after the first cell, which is the cell you would have stopped at.

Say you are a team lead and you decide to let one strong engineer skip code review to move faster on a deadline.

| Order | Consequence | What it feels like at the time |
|---|---|---|
| First | That engineer ships the feature two days early | A clear win, exactly what you wanted |
| Second | Two other engineers ask for the same exemption, because the rule now visibly bends for output | Reasonable, they are strong too |
| Third | Review stops being a norm and becomes a negotiation; the one place shared context was passed around quietly disappears | Nobody notices, because nothing breaks yet |
| Fourth | Six months on, the engineer who never gets reviewed leaves, and their code is a [bus factor of one](https://scribelet.app/blog/bus-factor) that no one else understands | The original deadline is long forgotten |

The first-order effect was real and good. The decision was still a bad one, and you could only see that by refusing to stop at column one. Notice also that the damage compounds through a *system*, not through a single line of cause and effect. Second-order effects love to travel along the structure of an organization, which is why [Conway's Law](https://scribelet.app/blog/conways-law) shows up here: change how a team communicates and you have quietly changed what it can build, whether you meant to or not.

Run this table on any decision where reversing it would be expensive. You do not need every cell to be certain. You need the habit of asking "and then what?" enough times that the non-obvious consequence has a chance to show up before you commit, not after.

## When second-order thinking is worth the effort

Second-order thinking has a real cost: it is slow, and applied everywhere it curdles into analysis paralysis. The move is to spend it only where the downstream matters, and the cleanest way to sort for that is the one Amazon uses. In [Jeff Bezos's 2015 shareholder letter](https://www.aboutamazon.com/news/company-news/2016-letter-to-shareholders), a two-way door is a decision you can walk back cheaply, so you should make it fast; a one-way door is expensive or impossible to reverse, so it earns the slow, deliberate treatment.

| The decision | Reversible? | Second-order thinking? |
|---|---|---|
| A choice you can undo in an afternoon | Yes | Skip it. Decide and move; the reversal *is* your safety net |
| A recurring policy or incentive | Usually not, once people adapt to it | Yes. Incentives are [where cobra effects breed](/blog/perverse-incentive) |
| A one-way door: a hire, a migration, a public commitment | No | Yes, and slowly. This is the whole reason the skill exists |
| Anything involving other people reacting to your move | Rarely | Yes. Their reaction is the second order you cannot see from your desk |

If you already run decisions through a [decision-making framework](https://scribelet.app/blog/decision-making-framework), second-order thinking is not a competing method; it is the step you add to the high-stakes branch, after you have sorted the decision by reversibility and before you commit. The reversible calls do not need it. The irreversible ones cannot be made responsibly without it.

## How to practice it: the "and then what?" template

You do not need a tool for this. You need a prompt you actually run, and a place to write the answers so they do not evaporate. The prompt is four questions, and the fourth is the one that gets skipped:

```
Decision: what I am about to do
And then what? (2nd order): how will people, systems, or markets react to it?
And then what? (3rd order): what does that reaction cause in turn?
Who else adapts? the effect you cannot see from your own seat
Prediction + revisit date: what I expect to be true by [date], so I can check
```

Two things make this work. First, force at least two rounds of "and then what?" before you allow yourself to judge any consequence as good or bad; the instinct is to evaluate the first-order effect and quit, and that instinct is the entire problem. Second, and this is the field nobody includes, write down what you actually expect to happen and when you will check. Second-order effects are predictions, and a prediction is [a map of a territory you have not reached yet](/blog/the-map-is-not-the-territory): one you never revisit teaches you nothing.

## Where second-order thinking goes wrong

The skill has its own failure modes, and most of them are the result of applying it with more enthusiasm than judgment. One runs deeper than the table below: a consequence trace is only as sound as your grasp of the system, and [a trace built on an understanding you only felt you had](/blog/illusion-of-explanatory-depth) is fiction dressed as foresight.

| Failure | What it looks like | The fix |
|---|---|---|
| Analysis paralysis | Running a four-order trace on a reversible, low-stakes call | Sort for reversibility first; only slow down for one-way doors |
| Infinite regress | Chasing consequences to the tenth order until every option looks equally doomed | Stop when the next link stops changing the decision |
| Spurious precision | Assigning confident probabilities to consequences that are genuine guesses | Write the assumption next to the guess, then flag it as a guess |
| Hindsight theater | "Trace" written after the outcome is known, to look wise | Record the prediction *before* the result, with a date |
| Never checking | Tracing consequences beautifully and never going back to see who was right | A revisit trigger, honored |

The last two are the same mistake wearing different clothes, and they are why the next section matters more than the table above.

## The part every guide skips: second-order effects unfold over time

Here is what the "and then what?" advice quietly assumes and never says: the second-order effect is in the *future*. That is the entire point. The immediate consequence is visible now; the one worth predicting shows up in three months or three years. Which means your second-order reasoning is a bet on the future, and a bet you never settle is not reasoning, it is a feeling you had once.

![Diagram showing a decision branching into first, second, and third-order consequences over time, with the largest effect arriving furthest downstream where it is hardest to trace back to the original choice](/blog/second-order-thinking/consequences-tree.svg)

This is the same half-life problem that sits under every written artifact. A prediction you made about the second-order effects of a decision is [knowledge with a shelf life](https://scribelet.app/blog/knowledge-decay): it was your best reasoning at the time, and time is precisely the thing that will prove it right or wrong. If you do not record it, you get the worst of both worlds. You never learn whether your second-order thinking was any good, so it never improves, and the confident story you told yourself about the consequences hardens into [a belief that has quietly gone stale](https://scribelet.app/blog/outdated-documentation) while everyone keeps acting on it.

The fix is not a better mental model. It is a recorded prediction with a revisit date, the same instinct engineers formalize when they [record the assumptions behind a decision](https://scribelet.app/blog/architecture-decision-record-examples) and note what should trigger a re-check. Capture the "and then what?" while you still know why you believed it. If you [write predictions down as the decision happens](https://scribelet.app/blog/interstitial-journaling) rather than reconstructing them at review time, the reasoning is still honest, because you had not yet seen how it turned out.

That is the problem Scribelet is built around. A note is not a place you record a prediction and forget it; it is something that fights its own decay, holding the assumptions you wrote down and telling you when a decision or a document you are still relying on has drifted out of date since anyone last checked. You can [try it free](https://scribelet.app) and keep your second-order predictions somewhere they get re-read against what actually happened, which is the only way the thinking ever gets better.

## The whole discipline, in three moves

Second-order thinking is not a trick for looking clever in meetings. It is three habits stacked on each other. Sort the decision first, so you only spend the effort on the one-way doors where the second order carries the cost. Then trace it, at least two rounds of "and then what?" past the obvious answer, paying special attention to how other people and systems will adapt to your move. Then, and this is the move almost everyone drops, write the prediction down with a date, and go back to read it. The first two habits improve the decision in front of you. Only the third improves the decisions you have not made yet.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>second-order-thinking</category>
            <category>mental-models</category>
            <category>decision-making</category>
            <category>knowledge-decay</category>
            <category>productivity</category>
        </item>
        <item>
            <title><![CDATA[Conway's Law: Why Your Architecture Mirrors Your Org Chart]]></title>
            <link>https://scribelet.app/blog/conways-law</link>
            <guid isPermaLink="false">https://scribelet.app/blog/conways-law</guid>
            <pubDate>Fri, 04 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Conway's law says your system will copy your org chart, whether you meant it to or not. What it is, examples, and how to use it on purpose. Try it free.]]></description>
            <content:encoded><![CDATA[
A codebase crosses my desk with four services. Not because anyone sat down and decided the domain split four ways, but because the company had four teams, and each team shipped the piece it owned. The seams between the services fall exactly where the seams between the teams fall. Where two teams talk often, the services have a clean, well-documented interface. Where two teams barely talk, there is a brittle nightly job nobody wants to touch. Nobody designed it this way. It grew this way, and it grew this way because of a rule that was written down in 1968.

That rule is Conway's law, and once you have seen it you cannot unsee it. It is not a productivity tip or a management fad. It is a structural observation about how software actually gets built, and it holds whether you know about it or not. The useful part is not the observation itself, which most engineers half-know already. The useful part is what you do with it: you can let the law shape your system by accident, or you can point it at the architecture you actually want. Here is what the law says, what it looks like in real systems, and how to run it forward on purpose instead of discovering it in a post-mortem.

## What is Conway's law?

Conway's law states that any organization that designs a system will produce a design whose structure copies the organization's communication structure. Melvin Conway published it in 1968 in a paper called ["How Do Committees Invent?"](http://www.melconway.com/Home/Committees_Paper.html), and the one-line version has outlived almost everything else from that era of computing: "Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations."

The mechanism is not mystical. For two pieces of software to talk to each other cleanly, the people building them have to agree on the interface between them. That agreement is a conversation, and it can go wrong in a quiet way: if each team assumes the other has already signed off, the interface ossifies around [a decision everyone nodded along to and no one actually wanted](/blog/abilene-paradox). If two teams talk constantly, they negotiate a good interface and keep it in sync. If two teams sit in different buildings, different time zones, or different reporting chains, the interface between their components ossifies into whatever they agreed on once and never revisited. The software boundary becomes a fossil of the org boundary. Once that boundary exists, the consuming team stops reading the interface as documented and starts depending on whatever it actually does, which is [Hyrum's law](/blog/hyrums-law) arriving through the org chart: a cross-team interface is exactly the setting where an accidental behavior becomes a contract fastest, because the other team is watching what your service does, not what your spec says it does. One practical defense against that fossilization is to build the receiving side of a cross-team interface to be forgiving of what the other team sends rather than brittle about it, which is the durable half of [Postel's law](/blog/postels-law).

The law is symmetrical, which is the part people miss. As [Martin Fowler puts it](https://martinfowler.com/bliki/ConwaysLaw.html), the law is not a lament but a leverage point: it does not only say "your teams shape your system," it also says that if you want a particular system shape, you may have to change your teams to get it. That symmetry is where the law stops being trivia and starts being a tool. It is also why the reasoning behind your boundaries is worth keeping somewhere it will stay current, which is a thread we pick up at the end, and the problem [Scribelet](https://scribelet.app) exists to fix.

## Why your architecture ends up shaped like your org chart

The pressure Conway described is not something a good architect can simply overrule. It comes from three forces that operate on every team, every day, whether or not anyone is paying attention.

The first is communication cost. Coordinating a design decision across a team boundary is expensive: it needs meetings, documents, sign-off, and follow-up. Coordinating inside a team is cheap: someone turns their chair around. So teams naturally push complexity toward the interfaces they control and away from the interfaces they share, which means the cheap-to-change boundaries end up inside teams and the expensive-to-change boundaries end up between them.

The second is ownership. Code that one team owns gets refactored, documented, and kept current, because someone is accountable for it. Code that spans two teams belongs to nobody, so it drifts. Over a year, the well-owned parts become clean modules and the shared parts become the integration layer everyone is afraid of.

The third is Conway's own point about copies. When a team splits into two, the code they were jointly maintaining tends to split with them, along the line where the people separated. When two teams merge, their services start to fuse. The system is not tracking the domain. It is tracking the people.

Put the three together and the outcome is not a tendency, it is close to a law:

| Your org structure | The architecture it produces |
|---|---|
| Three teams by feature area | Three services split along feature lines |
| One team owns everything | A monolith, coherent but hard to scale past the team |
| A separate database team | A schema layer everyone routes through and nobody can change fast |
| Front end and back end in different orgs | A rigid, over-negotiated API contract between them |
| An offshore team six time zones away | A batch integration with that component, not a live one |

![Diagram showing three teams that communicate frequently producing three services whose interfaces mirror the team communication paths, illustrating Conway's law](/blog/conways-law/team-to-architecture.svg)

None of these are failures of engineering skill. They are the predictable shadow of the reporting lines, cast onto the code.

## Conway's law examples

The cleanest historical example is the one Conway's contemporaries loved to quote: a project staffed with four teams to build a compiler shipped a four-pass compiler. The number of passes matched the number of teams, not the requirements of the language. Whether or not that specific story is apocryphal, every engineer who has worked at scale has their own version of it.

Here are the ones that recur, and the shape each leaves behind.

| Situation | What Conway's law produced |
|---|---|
| A startup with one small team | A monolith. Fast to build, coherent, and eventually the thing they blame for everything even though it served them well. |
| A monolith broken up by reorg | Microservices split along team lines, not domain lines, so a single user action now touches five services owned by five teams. |
| A "platform" team created mid-flight | Every product team routing through the platform team's API, and the platform team becoming the bottleneck for all of them. |
| Security bolted on by a separate org | A security layer that wraps the system from outside instead of being built into each service, because that is the only boundary the security team controlled. |
| Two companies after an acquisition | Two parallel stacks with a fragile bridge between them, mirroring two engineering orgs that never actually merged. |

The pattern in every row is the same: the architecture is legible only once you overlay the org chart. Read the code alone and the boundaries look arbitrary. Read the code with the reporting lines drawn on top and every seam has a reason.

## The inverse Conway maneuver: design teams to get the architecture you want

Because the law is symmetrical, you can run it in reverse. Instead of accepting whatever architecture your current org produces, you decide on the architecture you want first, then reshape the teams so their communication structure matches it. Skelton and Pais named this the "inverse Conway maneuver" in [*Team Topologies*](https://teamtopologies.com/book), and it is the single most practical thing to take from all of this.

The move looks like this. You want three loosely coupled services with clean interfaces. Conway's law says you will only get and keep that shape if you have three loosely coupled teams with clean interfaces of their own. So you organize the teams first: give each one clear ownership of one service, minimize the standing coordination they need with the others, and make the interfaces between teams explicit and stable. The architecture then grows into the shape you set up, because the cheap-communication boundaries now sit where you want the module boundaries.

A few rules make the maneuver work in practice rather than on a slide.

- **Draw the target architecture before you draw the org.** If you cannot describe the system boundaries you want, you cannot align teams to them, and you will get whatever the current chart produces by default. This is the same discipline as writing the design down before you build; a short [design document](/blog/software-design-document) that names the intended boundaries gives the reorg something to aim at.
- **Give each team a boundary it can own end to end.** A team that owns a service but depends on another team for its database or its deploy has not been given a real boundary; it has been given a coordination tax.
- **Make the between-team interfaces explicit and few.** Every standing cross-team dependency is a place the architecture will fuse. Fewer, sharper interfaces between teams produce fewer, sharper interfaces in the code.
- **Write the architectural intent down where it will be found.** The reasoning behind a boundary is exactly the kind of decision that evaporates once the person who made it moves on. Capturing it in an [architecture decision record](/blog/architecture-decision-record-examples) is what lets the next reorg preserve the boundary on purpose instead of erasing it by accident.

## How to spot Conway's law in your own system

You do not need a consultant to find Conway's law in your codebase. You need to lay two diagrams side by side and look for where they line up. Run through this checklist.

- **Overlay the org chart on the architecture diagram.** If the boundaries match, Conway's law is already running your design. That is not automatically bad, but it should be a choice, not a surprise.
- **Find the components nobody owns.** The service that sits between two teams, that both blame and neither refactors, is a Conway boundary that fell on a communication gap, not [anyone's deliberate neglect](/blog/hanlons-razor). It will keep rotting until one team clearly owns it. These seams are also where a system surprises its users most, because an interface built by two teams that never synced astonishes anyone who assumed one mind was behind it, which is where [a surprise becomes a defect worth fixing](/blog/principle-of-least-astonishment).
- **Watch what happens after a reorg.** If a team split last quarter and a once-clean module has started growing a seam down the middle, that is the law acting in real time. Name it before the seam hardens.
- **Look for interfaces that are more rigid than the domain requires.** An over-negotiated, change-averse API between two components usually marks a place where two orgs, not two domains, had to agree.
- **Ask why each boundary exists.** For every major seam in the system, someone should be able to say whether it is there because the domain wanted it or because the org chart put it there. If the answer for most seams is "the org chart," your architecture is a byproduct, not a design.

The goal of the audit is not to eliminate Conway's law, which is impossible, but to make it deliberate. Every boundary should be one you would choose again.

## The part nobody documents: org charts change, architectures don't

Here is the failure mode that outlives every reorg. Conway's law is usually taught as a snapshot: your current org produces your current architecture. But orgs are not snapshots. Teams split, merge, get renamed, and get re-staffed every few quarters. The architecture they produced does not move with them. It freezes the communication structure that existed on the day it was built, and then that structure changes underneath it.

So a year after a reorg you have a system whose boundaries encode an org chart that no longer exists. The service split that made sense when two teams owned two halves now cuts straight through the one team that inherited both. And the documentation that explained who owns what, why the boundary is there, and which team to call when it breaks, is describing a company that has been reorganized twice since. The org chart in the wiki is wrong. The ownership table in the README points at a team that was dissolved. The architecture diagram still shows the old seams, so the new engineer trusts it, and gets lost.

This is the same rot that hits every kind of engineering knowledge, and it hits Conway's-law boundaries hardest because they were never written down as decisions in the first place; they just happened. The fix is to treat the reasoning behind each boundary as something that has to be maintained, not captured once and abandoned. Scribelet is built for exactly this problem. Its background agents re-check your notes and docs against reality on a schedule and show you a diff when something no longer holds, so the ownership map and the architectural why stay current instead of quietly describing a team that no longer exists. A boundary you can no longer explain is a boundary you can no longer safely change, which is [Chesterton's fence](/blog/chestertons-fence) showing up at the architecture level instead of the code level, and [internal documentation that has gone stale](/blog/internal-documentation) is worse than none, because people still trust it. When knowledge concentrates in the few people who remember the original org, you also have a [bus factor problem](/blog/bus-factor) sitting on top of your Conway's-law one.

## Getting started

Conway's law is not a problem to solve; it is a force to aim. Start with one diagram: overlay your current org chart on your current architecture and mark every boundary that exists because of the reporting lines rather than the domain. That single audit tells you which of your seams are chosen and which are accidents. From there, either accept each boundary on purpose or, where it matters enough, use the inverse maneuver to move the teams so the architecture follows. And let the shape grow rather than legislating it whole from day one, because a working complex system is almost always one that [evolved from a simple system that worked](/blog/galls-law), not one drawn complete on a whiteboard before any code ran.

The part that lasts is keeping the reasoning alive. Write down why each boundary is there, and keep those notes true as the org changes around them. [Try Scribelet free](https://scribelet.app) and let it watch your architecture notes for the day the org chart moves and the docs do not. Your system will always mirror your org. The only question is whether you can still read the mirror a year from now.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>conways-law</category>
            <category>engineering</category>
            <category>software-architecture</category>
            <category>team</category>
            <category>knowledge-decay</category>
            <category>documentation</category>
        </item>
        <item>
            <title><![CDATA[Decision-Making Frameworks: Which One to Use When]]></title>
            <link>https://scribelet.app/blog/decision-making-framework</link>
            <guid isPermaLink="false">https://scribelet.app/blog/decision-making-framework</guid>
            <pubDate>Thu, 03 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A decision-making framework tells you how to choose, not which one fits your decision or how to stop the reasoning rotting. This guide fixes both. Try it free.]]></description>
            <content:encoded><![CDATA[
You have a real decision to make, so you search for a decision-making framework and get handed ten acronyms. RAPID. SPADE. WRAP. The Eisenhower matrix. A 2x2 grid with "urgent" on one axis. Each one is presented as the answer, none of them tells you which decision it was built for, and by the third tab you are running a meta-decision about which decision framework to use before you have made the actual choice.

That is the first gap every roundup leaves open. A framework is only useful once it is matched to the shape of the decision in front of you, and the shape is what nobody sorts for you. The second gap is quieter and more expensive: the frameworks all help you *reach* a decision and then go silent about what happens to the reasoning afterward. You pick, you move on, and six months later nobody, including you, can say why. This guide closes both. It sorts the common frameworks by the decision each one actually fits, and it covers the step every framework skips, which is making the reasoning survive contact with next year.

## What is a decision-making framework?

A decision-making framework is a repeatable process for evaluating options and committing to one, designed to slow down the parts of judgment that go wrong on instinct. The good ones do three things: they reduce bias by forcing you to name your criteria before you see which option wins, they cut analysis paralysis by defining when the deliberation ends, and they make it clear who actually decides so the choice does not dissolve into a group that never quite commits.

That is the pitch, and it is real. The catch is that a framework built for a reversible solo call is the wrong tool for an irreversible one your whole team has to live with, and using the elaborate one on a small choice is its own kind of waste. So the first move is never "pick a framework." It is "read the decision."

## Match the framework to the decision

Before reaching for any named method, sort the decision on two axes: **how reversible is it**, and **who has to own it**. Almost everything else follows from those two answers. A reversible call you can make alone in five minutes does not need a committee; an irreversible one your team will inherit for years should not be made in five minutes by anyone.

Amazon calls the first axis one-way versus two-way doors. In [Jeff Bezos's 2015 shareholder letter](https://www.aboutamazon.com/news/company-news/2016-letter-to-shareholders), a two-way door is a decision you can walk back cheaply, so you should make it fast and let people decide without ceremony. A one-way door is expensive or impossible to reverse, so it earns the slow, deliberate treatment. Most teams get this exactly backward: they agonize over the reversible calls and rush the ones they cannot undo. That instinct has a name, [Sayre's law](/blog/sayres-law), which observes that the fiercest arguments cluster on the smallest, safest decisions while the expensive ones slip through unexamined.

Here is the sort, with the framework each cell rewards:

| The decision | Reversible? | Who owns it | Reach for | Watch out for |
|---|---|---|---|---|
| Small, undo-able, low stakes | Yes | You | Just decide. Set a review date and move. | Turning a two-way door into a meeting |
| Comparing options on known criteria | Usually | You or a pair | A weighted **decision matrix** or cost-benefit table | Inventing precise scores for guesses |
| Urgent-versus-important triage | Yes | You | The **Eisenhower matrix** (do, schedule, delegate, drop) | Treating "urgent" as a synonym for "important" |
| A team choice that needs buy-in | Sometimes | A group, one decider | **RAPID** or **SPADE** to fix roles and record the call | Consensus theater where nobody actually decides |
| High-stakes, hard to reverse | No | A group, one decider | **WRAP** plus a **pre-mortem** to widen options and surface risk | Confirming the option you already wanted |
| Time-horizon doubt ("will I regret this?") | Either | You | The **10/10/10** test: how you feel in 10 minutes, 10 months, 10 years | Over-weighting the 10-minute feeling |

A few of these deserve a name and a source. [Bain's RAPID framework](https://www.bain.com/insights/rapid-decision-making/) is not really about analysis at all; it is about assigning who Recommends, Agrees, Performs, gives Input, and Decides, because the failure mode of team decisions is ownership, not information. A subtler failure survives even when ownership is crystal clear: [a group agreeing to a plan no individual actually wanted](/blog/abilene-paradox), because each person assumes everyone else is in favor and no one says otherwise. WRAP, from the Heath brothers, is a debiasing checklist: Widen your options, Reality-test your assumptions, Attain distance before deciding, and Prepare to be wrong. A pre-mortem is the cheapest risk tool ever invented: before you commit, assume the decision failed and write down why, out loud, as a team. Each of these is a structured way to [trace a decision's second- and third-order effects](/blog/second-order-thinking) before you are living with them rather than after.

The point is not to memorize the acronyms. It is that the same decision run through the wrong-shaped framework produces a worse outcome than no framework at all, because it launders a rushed or biased call through a process that looks rigorous.

## A worked example

Say your team is choosing a database for a new service. Sort it first: this is close to a one-way door (migrating later is expensive), it is high-stakes, and several engineers have to own it. That puts you in the bottom rows, not the top ones, so a five-minute Slack poll is the wrong instrument.

Run it as a decision matrix for the comparison, then WRAP the result. List the options down the side (Postgres, DynamoDB, the thing one engineer is excited about) and the criteria across the top (operational familiarity, cost at expected scale, migration cost, query shape fit). Score each, but write one sentence next to every score explaining the number, because the sentence is the part you will need later and the number is the part you will forget. Then reality-test, because [the decision matrix is a map and not the territory](/blog/the-map-is-not-the-territory): the "cost at scale" row is a guess, so name the scale you assumed. Then run a two-minute pre-mortem: "It is a year from now and this was the wrong call. Why?" If the answer is "the scale assumption was off by 10x," you have just found the one thing to verify before committing.

You end with a choice and, more importantly, a short record: the options, the criteria, the scores, the assumptions each score rested on, and the one risk you flagged. That record is worth more than the decision, and it is the thing every framework forgets to tell you to keep.

## The step every framework skips: write the decision down

Every framework above ends at the moment you choose. None of them says what to do with the reasoning, and the reasoning is the asset. A decision without a record is a result with no explanation, which means the next person to question it (including future you) has to reconstruct the whole thing from memory or reopen it from scratch.

The fix is a lightweight decision record, the kind of entry [a standalone decision log](/blog/decision-log) collects. It does not need a tool or a template library. It needs five fields:

```
Decision: what was chosen
Date: when, and by whom
Context: what forced the choice now
Options considered: including the ones rejected, and why
Assumptions: the facts this decision depends on being true
Revisit: the date or trigger that should make us re-check it
```

Engineering teams already formalize this for architectural choices as an [architecture decision record](https://scribelet.app/blog/architecture-decision-record-examples), kept in the repository next to the code and never edited after acceptance. You do not need the ceremony of that format for a hiring call or a vendor choice, but you need its instinct: the options you rejected and the assumptions you relied on are the fields that make the record worth reading a year out. Capture it in whatever you already write in. If you [journal decisions as they happen](https://scribelet.app/blog/interstitial-journaling) rather than reconstructing them at review time, the "why" is still accurate, because you wrote it while you still knew it.

This is also the difference between a decision that raises your team's resilience and one that quietly lowers it. A choice that lives only in the decider's head is a [bus factor of one](https://scribelet.app/blog/bus-factor): when they leave, the decision stays in force but its reasoning walks out the door, so nobody left knows whether it still holds or why it was made.

## Why the reasoning decays, and how to catch it

![Diagram contrasting two decision lifecycles: without a record the assumptions drift from green to red and the decision stays trusted while quietly becoming wrong, while a recorded decision with a revisit date gets caught at review](/blog/decision-making-framework/decision-lifecycle.svg)

Here is the part no decision-making framework accounts for. A decision is a bet on a set of assumptions, and assumptions expire. You chose the database because the team knew Postgres and the scale was modest. Eighteen months later the team has turned over and the scale is 50x. The decision did not change. The world underneath it did, and the record, if you even kept one, still reads exactly as confident as the day you wrote it.

This is [the half-life problem that sits under every written artifact](https://scribelet.app/blog/knowledge-decay). Nobody edits a decision record to make it wrong; it goes wrong by standing still while its assumptions move. A [decision that has quietly gone stale is worse than one you never wrote down](https://scribelet.app/blog/outdated-documentation), because the written one gets trusted. People cite it, build on it, and defend it long after the reasoning underneath it stopped being true.

The honest version of "use a framework and write the decision down" has a second clause: give the writing a way to tell you when it has stopped being true. That is what the `Assumptions` and `Revisit` fields in the record above are for, and it is why the strongest decision practice is not a better framework but a review habit, the [decision journal that Shane Parrish popularized](https://fs.blog/decision-journal/), where you re-read old calls against what actually happened and grade your own judgment. Frameworks improve the decision you are making now. Reviewing recorded decisions is the only thing that improves the decisions you make next.

That is the problem Scribelet is built around. A note is not a place you record a decision and hope; it is something that fights its own decay, reading the assumptions you wrote down and telling you which of your team's decisions and docs have quietly gone out of date since anyone last looked. You can [try it free](https://scribelet.app) and keep the reasoning behind your decisions somewhere it gets re-checked instead of merely trusted.

## Common ways decision frameworks fail

Even the right framework, matched to the right decision, fails in predictable ways. Most of them are not about the framework at all. The deepest one is upstream of the framework entirely: if you let a single easy-to-measure number stand in for the outcome you care about, the option that best games that number wins the decision, which is what happens [when the measure becomes the target](/blog/goodharts-law). The flip side is just as dangerous: [ignoring the parts of the outcome you cannot put a number on](/blog/mcnamara-fallacy), so the decision gets made on a partial map that leaves out what matters most.

| Failure | What it looks like | The fix |
|---|---|---|
| Framework theater | An elaborate scoring grid built to justify the option someone already picked | Name the decision criteria *before* you look at the options |
| Analysis paralysis | The two-way door treated like a one-way door, deliberated for weeks | Sort for reversibility first; decide reversible calls fast |
| Consensus mush | A group "decides" but no single person owns the call | Assign the decider explicitly (this is the whole point of RAPID) |
| No record | A confident choice with no written reasoning | Five-field decision record, every time it matters |
| No review | Records kept, never re-read, so judgment never improves | A revisit date or trigger, and a habit of honoring it |

The pattern underneath all five is the same. A decision-making framework is a tool for the moment of choosing, and the moment of choosing is the easy part. The value compounds in what you do before (sorting the decision to its shape) and after (recording the reasoning and revisiting it when the ground shifts). Pick the framework that fits the decision in front of you, write down why you chose what you chose, and give that writing a way to flag itself when the world it assumed has moved on. That is the whole discipline, and it outlasts any acronym.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>decision-making</category>
            <category>frameworks</category>
            <category>knowledge-decay</category>
            <category>productivity</category>
            <category>teams</category>
        </item>
        <item>
            <title><![CDATA[Mermaid Diagrams: Syntax, Examples, and Diagrams as Code]]></title>
            <link>https://scribelet.app/blog/mermaid-diagrams</link>
            <guid isPermaLink="false">https://scribelet.app/blog/mermaid-diagrams</guid>
            <pubDate>Wed, 02 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A guide to Mermaid diagrams: the syntax, copy-paste examples for every type, where they render, and where they still go stale. Diagrams as code, explained. Try it free.]]></description>
            <content:encoded><![CDATA[
Somewhere in your team's wiki there is an architecture diagram that is wrong. Someone drew it in a diagramming tool two years ago, exported a PNG, and pasted the image into the page. The service it describes has since grown a queue, lost a cache, and swapped one database for another. The picture shows none of that, and nobody can fix it, because the editable source lives in a `.drawio` file on a laptop that was reimaged last spring. The diagram is now a confident, full-color lie, and everyone has learned to ignore it.

A Mermaid diagram fails differently. It is not an image; it is a few lines of text that a renderer turns into a picture. That difference sounds small and changes everything: the diagram lives in the same repository as the code, it changes through the same pull request, and anyone who can read Markdown can fix it in ten seconds. This guide covers the syntax, gives you a copy-paste example for every diagram type worth knowing, shows where Mermaid renders, and then names the one problem it does not solve.

## What is a Mermaid diagram?

A Mermaid diagram is a diagram generated from plain text. Mermaid is an open-source, JavaScript-based tool that reads a small, Markdown-inspired syntax and renders it into a flowchart, sequence diagram, class diagram, or one of a dozen other types. You write the diagram as code, the renderer draws it, and the text is the source of truth. The [Mermaid project](https://mermaid.js.org/) describes itself plainly: "Create diagrams and visualizations using text and code."

Here is the entire idea in five lines:

```mermaid
flowchart LR
    A[Write text] --> B[Mermaid renders it]
    B --> C[Diagram appears inline]
    C --> D[Edit the text, repeat]
```

That block is not a screenshot of a diagram. It *is* the diagram. Paste it into a GitHub pull request, an Obsidian note, or a Notion page and it draws itself. Because it is text, it diffs cleanly in review, it survives a copy-paste, and it never rots into an uneditable binary blob. If your team already treats [documentation as code that lives in the repo](/blog/docs-as-code), Mermaid is the missing piece that lets diagrams live there too. [Start free](https://scribelet.app) if you want a place to keep the diagrams and notes that do not belong in a code repo but still need to stay honest.

## Why diagrams as code beats a drawing tool

The pitch for Mermaid is not that it draws prettier boxes than a dedicated tool. It usually does not. The pitch is about what happens to the diagram after you make it.

A diagram drawn in a GUI tool is a binary file or an exported image. It cannot be reviewed in a pull request in any meaningful way (a reviewer sees "image changed," not what changed). It drifts on its own timeline, separate from the code. And when the one person who owns the source file leaves, the diagram freezes forever. That is a [single point of failure dressed up as a picture](/blog/bus-factor).

A Mermaid diagram is text, so it inherits every good habit your codebase already has:

- **It diffs.** A reviewer sees exactly which edge you added or which node you renamed, right next to the code change that motivated it.
- **It reviews.** The diagram change rides in the same pull request as the code, so a [pull request that people actually read](/blog/pull-request-template) catches a diagram that no longer matches reality.
- **It versions.** `git blame` works on a diagram. You can see when the flow changed and why, and roll it back if the change was wrong.
- **It renders anywhere.** No plugin, no license, no export step. The same fenced code block draws itself in every tool listed below.

This is why Mermaid shows up wherever engineers already write [architecture decision records](/blog/architecture-decision-record-examples), [design docs](/blog/software-design-document), and [technical specs](/blog/technical-spec). A design doc that embeds a Mermaid sequence diagram stays in sync with itself: change the flow in the text, and the picture changes in the same commit.

## Mermaid syntax basics

Every Mermaid diagram is a fenced code block that starts with a diagram type. In Markdown, you open a fence with the word `mermaid`:

````
```mermaid
flowchart TD
    Start --> Stop
```
````

Inside, the first token declares the type (`flowchart`, `sequenceDiagram`, `classDiagram`, and so on). For flowcharts, the second token sets direction: `TD` or `TB` (top-down), `LR` (left-right), `RL`, or `BT`. After that, you describe nodes and the connections between them.

Three rules cover most of what you will write day to day:

- **Nodes** get an ID and an optional shape. `A[Square]`, `B(Rounded)`, `C{Diamond}`, `D((Circle))`. Reuse the ID to refer to the same node again.
- **Edges** connect nodes. `A --> B` is a solid arrow, `A --- B` a plain line, `A -.-> B` dotted, `A ==> B` thick. Add a label with `A -->|yes| B`.
- **Comments** start with `%%` and are ignored by the renderer.

That is enough to draw the majority of diagrams that ever appear in an engineering doc. The rest is knowing which diagram type fits the job.

## Mermaid diagram examples: a copy-paste cheatsheet

Below is one working example of each diagram type you are most likely to need, with a one-line note on when to reach for it. Copy any block into a Mermaid-aware editor and it renders as-is.

**Flowchart** (a process, a decision, a pipeline):

```mermaid
flowchart TD
    A[Open pull request] --> B{CI passes?}
    B -->|yes| C[Request review]
    B -->|no| D[Fix and push]
    D --> B
    C --> E[Merge]
```

**Sequence diagram** (who calls whom, and in what order):

```mermaid
sequenceDiagram
    participant U as User
    participant API
    participant DB
    U->>API: POST /login
    API->>DB: check credentials
    DB-->>API: ok
    API-->>U: session token
```

**Class diagram** (data model, object relationships):

```mermaid
classDiagram
    class Note {
        +String title
        +String body
        +verify()
    }
    class Desk {
        +String name
    }
    Desk "1" --> "*" Note : contains
```

**Entity relationship diagram** (database schema):

```mermaid
erDiagram
    DESK ||--o{ NOTE : contains
    NOTE ||--o{ TAG : has
    NOTE {
        uuid id
        string title
        datetime updated_at
    }
```

**State diagram** (the lifecycle of a thing):

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> InReview: open PR
    InReview --> Draft: changes requested
    InReview --> Merged: approved
    Merged --> [*]
```

**Gantt chart** (a schedule or roadmap):

```mermaid
gantt
    title Release plan
    dateFormat YYYY-MM-DD
    section Build
    Spec        :done,    a1, 2026-09-01, 3d
    Implement   :active,  a2, after a1, 5d
    section Ship
    Review      :         a3, after a2, 2d
    Deploy      :         a4, after a3, 1d
```

**Mindmap** (branching notes, an outline):

```mermaid
mindmap
  root((Note taking))
    Capture
      Voice
      Web clips
    Organize
      Tags
      Links
    Maintain
      Verification
```

You will not memorize all of this, and you do not need to. Keep the block that matches your current job, and let the [official Mermaid syntax reference](https://mermaid.js.org/intro/) fill in the rest when a diagram gets complicated.

## Which Mermaid diagram type should you use?

Reaching for the wrong type is the most common Mermaid mistake. Here is the short version.

| You want to show | Use | Because |
|---|---|---|
| A process or decision | `flowchart` | Boxes and arrows with branching, the workhorse |
| Who calls whom, in order | `sequenceDiagram` | Time runs top to bottom; makes call order explicit |
| Data model / relationships | `classDiagram` | Fields, methods, and how objects relate |
| A database schema | `erDiagram` | Tables, keys, and cardinality (one-to-many) |
| The lifecycle of a thing | `stateDiagram-v2` | States and the events that move between them |
| A schedule or plan | `gantt` | Tasks over dates, with dependencies |
| Branching ideas | `mindmap` | An outline that fans out from a center |

If you cannot decide between a flowchart and a sequence diagram, ask whether *order in time* is the point. If it is, use a sequence diagram. If the point is branching and decisions, use a flowchart.

## Where Mermaid diagrams render

Mermaid's real advantage is reach. The same code block draws itself across most of the tools an engineer already uses, with no export step. [GitHub added native Mermaid support to Markdown](https://github.blog/developer-skills/github/include-diagrams-markdown-files-mermaid/) in 2022, and the rest of the ecosystem followed.

| Tool | Support | Notes |
|---|---|---|
| **GitHub** | Native | In Markdown files, issues, PRs, and comments |
| **GitLab** | Native | Markdown and wikis |
| **Obsidian** | Native | Renders in preview and reading mode |
| **Notion** | Native | Use the `/code` block, language `Mermaid` |
| **VS Code** | Extension | Markdown Preview Mermaid Support, plus many others |
| **MkDocs / Docusaurus** | Plugin | Standard for docs-as-code sites |
| **Mermaid Live Editor** | Web | Paste, render, export SVG or PNG |

The practical upshot: you write a diagram once, in text, and it shows up correctly in your repo, your notes app, and your published docs site without you touching it three times. That is the property a screenshot can never have.

## Where Mermaid diagrams still go stale

Here is the part the tutorials skip. Diagrams as code fixes *where* a diagram lives and *how* it changes. It does not fix *whether it is still true*.

![Diagrams as code lifecycle: a Mermaid diagram is text that renders inline and reviews in a pull request, but drifts silently when the system changes and no pull request touches the diagram](/blog/mermaid-diagrams/diagrams-as-code-lifecycle.svg)

A Mermaid diagram in a design doc is a claim about the system, the same way a sentence in the doc is a claim. When the code changes, the diagram can drift just like prose drifts. The pull request review catches drift only if the diagram happens to change in the same PR as the code it describes, and it often does not: someone adds a new service, wires it up, ships it, and never opens the doc where the old architecture diagram still smiles up at the next new hire. The text is version-controlled and reviewed and completely out of date. This is [documentation rot](/blog/outdated-documentation), and it does not care whether your diagram is a PNG or a fenced code block.

So diagrams as code is a real upgrade and only half the job. It makes a diagram *editable and reviewable*, which the old PNG never was. It does nothing on its own to tell you the diagram no longer matches the running system. That second half, keeping a diagram true after you draw it, is a maintenance problem, and maintenance is where [knowledge quietly decays](/blog/knowledge-decay) in every tool that stops at "we wrote it down."

That gap is what [Scribelet](https://scribelet.app) is built to close. Keep your diagrams and the notes around them in one place, and background agents watch the sources they depend on, so when the thing a diagram describes changes, you get a diff instead of a silent lie in the wiki two years from now. Mermaid gets the diagram into a form you can maintain. Scribelet is the part that actually maintains it.

## Mermaid diagram FAQ

**What is a Mermaid diagram?** A diagram generated from plain text using Mermaid, an open-source JavaScript tool. You write a few lines in a Markdown-inspired syntax and a renderer turns them into a flowchart, sequence diagram, or other type. The text is the source, so the diagram versions, diffs, and reviews like code.

**Can ChatGPT generate Mermaid diagrams?** Yes. Because Mermaid is text, any capable language model can produce a valid Mermaid block from a description, and you can paste the result straight into a renderer. It is worth checking the output: models occasionally invent syntax or mislabel edges, and a diagram that renders is not the same as a diagram that is correct.

**Is Mermaid free?** Yes. Mermaid is open source under the MIT license, and the [Mermaid repository on GitHub](https://github.com/mermaid-js/mermaid) is public. Some hosted editors and commercial products build on it, but the core tool and syntax cost nothing.

**Mermaid vs PlantUML?** Both render diagrams from text. Mermaid uses a lighter, Markdown-friendly syntax and renders natively in GitHub, GitLab, Obsidian, and Notion with no server. PlantUML supports more diagram types and finer control, at the cost of a heavier syntax and, often, a rendering server. For most engineering docs, Mermaid's native support wins.

## Getting started

Mermaid turns a diagram from a picture you cannot edit into text you can. Pick the diagram type that matches the job, write it in the fenced `mermaid` block, and let it render in the repo, the pull request, and the docs site from a single source. That alone removes an entire category of stale, uneditable diagrams from your documentation.

The half that Mermaid does not cover is keeping the diagram true once the system moves on. [Try Scribelet free](https://scribelet.app): keep your diagrams, notes, and their sources together, and let background verification tell you when the thing a diagram describes has changed, so the picture in your docs stops drifting into fiction.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>mermaid</category>
            <category>diagrams-as-code</category>
            <category>documentation</category>
            <category>markdown</category>
            <category>engineering</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[How to read a research paper (and keep what you learn)]]></title>
            <link>https://scribelet.app/blog/how-to-read-a-research-paper</link>
            <guid isPermaLink="false">https://scribelet.app/blog/how-to-read-a-research-paper</guid>
            <pubDate>Tue, 01 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[How to read a research paper with a three-pass method, a per-pass note template, and a worked example. Keep what you read instead of losing it. Try it free.]]></description>
            <content:encoded><![CDATA[
You read the paper. You highlighted half of it, nodded at the clever part in the results, and told yourself you would come back to the methods section. Three weeks later you need the one number that made the whole argument work, and you cannot find it. You remember that the paper was good. You do not remember why. So you open it again and read it a second time from the top, which is the most expensive way to read anything.

That is the real problem with reading a research paper, and none of the guides that rank for this query will name it. They tell you the order to read the sections in, which matters, and then stop. Reading order gets the paper into your head. It does nothing to keep it there, and a paper you cannot recall is a paper you have to read twice. This guide covers the order, and then the part that actually pays off: how to read a research paper so that one pass leaves you with something you can use a month later without opening the PDF again.

## Why you can't read a paper like a book

A book is written to be read front to back. A research paper is not. It is written to survive peer review, which means the authors front-load novelty, bury the caveats in the discussion, and put the load-bearing detail in figures and tables rather than prose. Reading it linearly means spending your freshest attention on the abstract's marketing and running out of focus before you reach the part that tells you whether to trust any of it.

The fix that every experienced reader converges on is to read in passes, each with a different question, from shallow to deep. The first pass decides whether the paper is worth your time at all. The second gets you the argument. The third, which most papers never earn, gets you the method in enough detail to build on or to challenge. You stop at whichever pass answers your question. Most papers deserve one pass. A few deserve all three. Deciding that quickly is the skill, and it compounds when every paper you read lands in one searchable place instead of a folder of PDFs you never reopen. That place is what [Scribelet](https://scribelet.app) is for.

## How to read a research paper: the three-pass method

The three-pass approach was described by S. Keshav in ["How to Read a Paper"](https://web.stanford.edu/class/ee384m/Handouts/HowtoReadPaper.pdf), a one-page note that has outlived most of the papers it was written to help people read. Here it is as a decision table, with what each pass is for, where you look, and roughly how long it takes.

| Pass | Your question | Where you read | Time | Stop here if |
|---|---|---|---|---|
| **1. Skim** | Is this worth my time? | Title, abstract, section headings, figures, conclusion | 5-10 min | It does not fit your goal, or the claim is weaker than the title implied |
| **2. Grasp** | What did they actually find, and should I believe it? | Introduction, figures and tables in full, discussion and limitations | 30-60 min | You understand the argument and only needed the finding, not the machinery |
| **3. Rebuild** | Could I reproduce or attack this? | Methods, assumptions, every equation, the supplementary material | 2-4 hrs | You never reach this pass for most papers, and that is correct |

Two things this table encodes that the plain advice leaves out. First, you read the conclusion during the *skim*, not at the end. The final paragraph of the introduction and the conclusion together tell you the gap the authors claim to fill and whether they claim to have filled it, which is the fastest way to decide if pass two is worth starting. Second, you can skip the methods section on the first two passes without guilt. Unless you plan to reproduce the study or you have a specific reason to distrust it, the dense methods prose is pass-three material. Skimming it early is how you burn your attention before you reach the discussion, where the authors admit what the study cannot show.

This also answers the two questions people actually type after the main one. To read a paper *quickly*, you are doing pass one and stopping: title, abstract, figures, conclusion, decision made in under ten minutes. To *analyze* a paper, you are doing pass two properly: reading the figures before the text that describes them, and treating the limitations section as the most honest part of the paper rather than a formality. If you want the version with more granularity, the NIH's ["Ten simple rules for reading a scientific paper"](https://pmc.ncbi.nlm.nih.gov/articles/PMC7392212/) breaks the same idea into a longer checklist.

![Diagram of the three-pass method for reading a research paper: a wide skim pass narrows to a grasp pass and a rare rebuild pass, each feeding a note-capture step that produces one durable literature note](/blog/how-to-read-a-research-paper/three-pass-reading.svg)

## What to capture on each pass

Here is the step that separates reading a paper from keeping it. At the end of each pass, before you close the tab, you write down a fixed set of things. Not a summary of the whole paper. A small, structured note built from the questions the pass was meant to answer. Do this and the paper becomes a durable [literature note](/blog/literature-notes) you can search and cite later, instead of a highlighted PDF you will never reopen.

Use a template so you are filling in fields, not staring at a blank page. This one takes two minutes and captures what you will actually want back:

```
Paper: [author, year, title]
Link / DOI: [so future-you can find it in one click]
Why I read it: [the question that sent you here]

Claim: [the one sentence the paper is really arguing]
Evidence: [what backs it: sample, method, effect size, the key figure]
My confidence: [high / medium / low, and one reason]

Limitations: [what the authors admit it cannot show]
For me: [how this changes what I think or what I will do]
Quote: ["one exact line worth keeping, with the page number"]
```

The fields matter more than the format. "Why I read it" stops you collecting papers you will never use. "Claim" forces you to state the argument in your own words, which is the single best test of whether you understood it. "My confidence" is the field almost nobody keeps, and it is the one that saves you later: a paper you filed at low confidence should not become a load-bearing citation six months on without a second look, because [the refutation tax on a claim you already trusted](/blog/brandolinis-law) is far higher than the cost of checking it now. Keeping the exact quote and page number means you can pull a citation without reopening the source.

If you have read about [how to take smart notes](/blog/how-to-take-smart-notes) or worked with [atomic notes](/blog/atomic-notes) before, this is that idea aimed squarely at papers: one paper, one self-contained note, written in your own words at the moment you understood it, not reconstructed later from highlights. The reading passes give you the material. The template gives it somewhere to live.

## A worked example: one paper, three passes

Say you are reading a paper on spaced repetition for a piece you are writing about study habits.

**Pass one, five minutes.** The title promises that spaced review beats massed review for long-term retention. The abstract confirms it and gives an effect size. You glance at the main figure: two retention curves, spaced clearly above massed at the 30-day mark. The conclusion says the effect held across three subject areas. That is enough to know the paper fits your question, so you go to pass two. If your question had been narrower, say whether spacing helps for *motor* skills specifically, the skim would have told you this study is about verbal recall and you would have stopped here and moved on.

**Pass two, forty minutes.** You read the introduction to see what gap they claim: prior work showed the effect in lab settings, this study tests it in a real classroom over a semester. You read the figures in full, including the one showing the effect shrinking for the lowest-performing students, which the abstract did not mention. The discussion admits the sample was a single university and the spacing intervals were fixed rather than adaptive. Now you write the note:

```
Paper: Rowsell et al., 2024, "Spaced review in a semester-long course"
Link / DOI: 10.xxxx/example
Why I read it: does spacing hold outside the lab, for my study-habits piece

Claim: spaced review beats massed review for retention in a real classroom, not just a lab.
Evidence: semester-long classroom study, ~200 students, retention +18% at 30 days vs massed. Fig 2.
My confidence: medium. Real setting is a plus; single university, fixed intervals is a limit.

Limitations: one institution; effect weaker for lowest-performing students (Fig 4); intervals not adaptive.
For me: use as the "it works in practice, not just the lab" citation. Note the weaker effect for struggling students.
Quote: "The advantage of distributed practice persisted across all three course subjects." (p. 7)
```

You never reached pass three, because you are not reproducing the study. Total time: under an hour, and you now have a note you can drop into a draft with the citation, the caveat, and the exact quote already in hand.

## Reading for a literature review vs. reading to stay current

Before you open anything, decide why you are reading, because the goal changes how deep you go and what you keep. These are the two goals most people are actually pursuing, and conflating them is why reading feels endless.

| | Reading for a literature review | Reading to stay current |
|---|---|---|
| Goal | Map a field: who found what, where they disagree, what is unsettled | Keep up with your area; catch what is new |
| Depth | Pass two on most, pass three on the few that anchor your argument | Pass one on most, pass two on the surprising ones |
| What you capture | The full note, plus how this paper relates to the others (agrees, contradicts, extends) | Claim and one line on why it matters; upgrade later if it becomes relevant |
| The trap | Summarizing papers one by one instead of grouping them by theme | Saving everything and reading nothing |

If you are building a literature review, the note's "how this relates to the others" line is the whole point, and it is what turns a stack of individual notes into a synthesis instead of an annotated list. Group your notes by claim or theme, not by author, and the review starts to write itself from the connections rather than from the papers. This is the same reason a [second brain that you actually maintain](/blog/living-notes-method) beats a folder of PDFs: the value is in the links between notes, not the notes alone.

## The part nobody mentions: the paper you read will change

Here is the assumption buried in every reading guide, including the good ones: that a paper, once read, stays read. It does not. The literature moves under you. A study you filed at high confidence gets a correction. A finding you built an argument on fails to replicate. Occasionally a paper is retracted outright, and according to [Retraction Watch](https://retractionwatch.com/) the rate of retractions has climbed sharply over the past two decades. Your careful note still cites it, your draft still leans on it, and nothing tells you until a reviewer or a colleague does.

This is knowledge decay, and it is not unique to research; it is just faster and higher-stakes there. We have written about [why your notes go stale](/blog/knowledge-decay) in general, and a cited paper is the sharpest version of the problem, because the cost of a stale citation is not inconvenience but a wrong claim in public. The reason the note template above keeps the DOI and your confidence level is exactly this: those two fields are what let you, or a tool, go back and check whether the ground has shifted.

That last part is what [Scribelet](https://scribelet.app) is built to do. It keeps your research notes and their sources in one place, and its background agents watch the sources you rely on, so when a paper you cited is updated, corrected, or retracted, you find out from a diff instead of from a reviewer. The reading method above gets a paper into a note you can trust today. Keeping that note true a year from now is a maintenance problem, and maintenance is the part every other guide leaves to you. You can even [ask questions across all your saved papers](/blog/ai-fact-checking-for-notes) and have the answers checked against the sources, rather than trusting a memory of what you read last spring.

## Getting started

Reading a research paper well is two habits, not one. Read in passes, stopping at the pass that answers your question, so you spend deep attention only where it pays. Then capture each paper in a short structured note at the moment you understood it, so one read is enough. Do both and your reading compounds instead of evaporating.

Scribelet gives those notes a home that stays current: keep your papers, notes, and sources together, and let background verification tell you when a source you cited has changed. [Try it free](https://scribelet.app) and turn the next paper you read into a note you can still trust next year.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>research</category>
            <category>note-taking</category>
            <category>literature-notes</category>
            <category>knowledge-decay</category>
            <category>pkm</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Bus Factor: How to Find and Raise It on Your Team]]></title>
            <link>https://scribelet.app/blog/bus-factor</link>
            <guid isPermaLink="false">https://scribelet.app/blog/bus-factor</guid>
            <pubDate>Mon, 31 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The bus factor is the number of people who could vanish before your project stalls. How to measure it, spot a bus factor of 1, and raise it. Try it free.]]></description>
            <content:encoded><![CDATA[
One person set up your deploy pipeline two years ago. They are the only one who knows why the staging cutover has that one manual step, and where the secret rotation actually lives. Last Tuesday they were out with the flu. A release that normally takes twenty minutes did not ship for two days, because the four engineers who tried could not find the thing that lived in one head, and that head was asleep with a fever.

That is a bus factor of one. Most teams have several, and cannot name a single one of them, because the knowledge that would let them notice is the same knowledge that is missing. The number stays invisible right up until the person who holds it is unreachable, and then it is the only number that matters. This is a measurable property of your team, not a vibe, and it is fixable. Here is how to find your real bus factor, what a bus factor of one looks like before it bites, and how to raise it in a way that lasts.

## What is the bus factor?

The bus factor is the number of people who would have to suddenly become unavailable, by quitting, going on leave, getting sick, or the morbid original framing, being hit by a bus, before a project stalls because the knowledge to keep it running left with them. It is also called the truck factor or the lottery factor, and it measures one thing: how well the critical knowledge on your team is distributed, which tends to track [the shape of your org chart](https://scribelet.app/blog/conways-law) more than anyone intends. [Wikipedia's definition](https://en.wikipedia.org/wiki/Bus_factor) puts it as the risk that comes from information and capability not being shared.

A bus factor of one is the dangerous case. One person holds knowledge nobody else has, so their absence stops the work. A high bus factor is the resilient case: the knowledge is spread across enough people that losing any single one is survivable. The goal is never a specific number. It is knowing your number for the things that matter, and making sure none of them sits at one.

Search the term and you get that definition, and then three lines of advice that show up on every page: write documentation, cross-train, do code reviews. All true, and all close to useless on their own, because none of them tells you your actual number or which thing to write down first. The two questions worth your time are the two nobody answers: how do you measure your bus factor, and how do you raise it without generating a pile of documents that rot?

![Diagram comparing a bus factor of 1, where three critical systems all depend on one person, against a bus factor of 3, where the same knowledge is captured as artifacts three people can read](/blog/bus-factor/bus-factor-concentration.svg)

## How to measure your bus factor

There is real academic work on computing a bus factor from commit history, assigning authorship of files to people and finding the smallest group whose loss would orphan a large share of the codebase. [The theory and practice of computing the bus factor](https://www.sciencedirect.com/science/article/pii/S0020025526002847) is a good survey if you want the algorithm. For a working team, you do not need it. Commit history also lies: the person who committed a file is often not the person who understands the system it belongs to, and plenty of critical knowledge (the deploy runes, the customer who must be called before a migration, the reason a config value is what it is) never touches the repository at all.

The fast version that actually reflects risk is a conversation and a table. List your critical systems and capabilities, the things that would hurt if they broke on a bad day. For each one, ask a concrete question: how many people could take this over tomorrow, with no ramp-up, if the current owner were unreachable? Count them. That count is the bus factor for that capability, and the lowest numbers are your exposure.

| System or capability | People who could own it tomorrow | Bus factor |
|---|---|---|
| Production deploy and rollback | 1 (Priya) | **1, critical** |
| Payment provider integration | 2 | 2 |
| Primary database schema and migrations | 1 (Sam) | **1, critical** |
| Customer data export and GDPR requests | 3 | 3 |
| The staging environment and its quirks | 1 (Priya) | **1, critical** |
| CI pipeline configuration | 2 | 2 |

Read the table and the work becomes obvious. You do not have "a bus factor." You have one per capability, and the number that can hurt you is the lowest one sitting under something important. Rank the rows by criticality multiplied by fragility, and the top of that list is where you spend your effort. In the example, Priya is a single point of failure for two critical systems and Sam for one; that is where you start, not with a blanket "write more docs" mandate that treats the deploy pipeline and the office coffee order as equally urgent.

## What a bus factor of 1 looks like

You do not have to wait for someone to leave to find your ones. A bus factor of one has a smell, and it is consistent across teams. The warning signs are worth learning because they show up months before the person actually disappears.

- **One name comes up in every incident.** When anything breaks in a given area, the same person gets paged, gets pulled into the thread, or gets a "quick question" on their day off. The team has quietly agreed that this is theirs.
- **A system nobody else will touch.** There is a service or a script that engineers route around. It works, so nobody has had to learn it, which means nobody has learned it. That avoidance is [Chesterton's fence](/blog/chestertons-fence) in reverse: the safest-looking move is leaving it alone forever, when the actual fix is figuring out why it works the way it does.
- **"Ask X" is the documentation.** The onboarding answer to a whole category of questions is a person's name, not a page. When the real documentation is a human, that human is a bus factor of one.
- **Onboarding means shadowing one senior for weeks.** If a new hire can only get productive by sitting next to a specific person, that person is carrying knowledge that exists nowhere else. Often they have not written it down because [they can no longer imagine not knowing it](/blog/curse-of-knowledge).
- **Vacations get interrupted.** The clearest signal of all. If someone cannot take a week off without a "sorry, one thing," their bus factor is one and everyone already knows it, including them.

As [Laws of Software Engineering puts it](https://lawsofsoftwareengineering.com/laws/bus-factor/), a bus factor of one means one person holds critical knowledge and the project is effectively doomed if they disappear. The uncomfortable part is that a bus factor of one is usually comfortable, right until it is not. The single owner is efficient. They are fast, they do not need to coordinate, they never have to write anything down. That efficiency is exactly what hides the risk, and it is why raising a bus factor always feels like slowing down before it feels like insurance.

## How to raise your bus factor

Here is where the generic advice fails hardest. "Write documentation" is advice nobody can act on, because it does not say which document. Dumping everything one person knows into a wiki page produces a wall of text that goes stale in a month and helps no one. Different kinds of knowledge need different artifacts, and each artifact has a shape and a home. Match the knowledge to the right one and you get something a second person can actually use.

| What lives in one head | The artifact that captures it | Where it lives |
|---|---|---|
| Why the system is built this way, the decisions and their tradeoffs | An [architecture decision record](https://scribelet.app/blog/architecture-decision-record-examples) | In the repo, next to the code |
| How to run an operational task or recover from an incident | A [runbook](https://scribelet.app/blog/runbook) | In the repo or team wiki, linked from alerts |
| How a whole system or a big change is designed | A [design doc](https://scribelet.app/blog/software-design-document) | In the repo before the work starts |
| The process, conventions, and setup a team runs on | [Internal documentation](https://scribelet.app/blog/internal-documentation) | The team wiki, kept short and current |
| Why a specific change was made | A [pull request description](https://scribelet.app/blog/pull-request-template) | On the PR, forever |

The point of the table is that "raise your bus factor" becomes a list of specific, small acts instead of one impossible one. Priya does not need to document the deploy pipeline in the abstract. She needs to write one runbook for the release procedure and one ADR for why the staging cutover has that manual step. Sam writes one design doc for the schema and one runbook for migrations. Each of those is an afternoon, not a quarter, and each one moves a bus factor from one to two the moment a second person reads it and can follow it.

Cross-training and pair working matter too, and they do something the artifacts cannot: they transfer the judgment that never fits on a page, the sense of when a procedure is about to go wrong. But person-to-person transfer has a bus factor of its own. If Priya trains Sam and they both leave, you are back where you started. An artifact moves knowledge from a person to a page, and a page does not quit, does not go on vacation, and does not forget. The strong teams do both: they pair to spread judgment, and they write to spread the facts. Keeping those artifacts [in version control and reviewed like code](https://scribelet.app/blog/docs-as-code) is what stops the writing from being a one-time event that decays the day after.

## The catch: documentation raises your bus factor only if it is true

This is the part the three-line advice never mentions, and it is the part that decides whether any of this works. Writing something down raises your bus factor only for as long as what you wrote stays true. The moment it drifts, it does the opposite of what you built it for.

A runbook that points at a database you decommissioned in the spring is not a bus factor of two. It is a bus factor of one with extra steps. The one person still knows the real procedure. Everyone else now has a page that confidently tells them the wrong thing, so they follow it, hit the wall, and page the one person anyway, having lost an hour first. [Stale documentation is worse than no documentation](https://scribelet.app/blog/outdated-documentation), because no documentation at least makes people ask. A wrong page makes them trust.

This is [the half-life problem that sits under every written artifact](https://scribelet.app/blog/knowledge-decay). Code changes. The runbook, the ADR, the onboarding doc all keep rendering exactly as they did the day they were written, describing a system that has moved on without them. Nobody edits a document to make it wrong; it goes wrong by standing still while the world moves. So the honest version of "write it down to raise your bus factor" has a second clause: and give the writing a way to tell you when it has stopped being true. A last-verified date that is separate from the last-edited date. A trigger that flags the page when the thing it describes changes. An assistant that reads what you wrote and checks it against the code or the system it points at, and surfaces the mismatch before an incident does.

That is the problem Scribelet is built around. A note is not a place you dump knowledge and hope; it is something that should fight its own decay, telling you which of your team's runbooks, decisions, and docs have quietly gone out of date since anyone last looked. You can [try it free](https://scribelet.app) and keep the knowledge that would otherwise live in one head somewhere it gets checked instead of merely trusted.

## Getting started

You can start this afternoon, and you should start small. Pull up your critical systems and score them the way the table above does: for each one, how many people could own it tomorrow. Find the lowest number sitting under something important. That is your most expensive bus factor, and it is the only one worth fixing first.

Then write the single artifact that captures what that one person knows, the runbook or the ADR or the design doc, whichever matches the kind of knowledge it is. Have a second person follow it, without the expert in the room, and fix everything they get stuck on. That act, done once, has already moved a bus factor from one to two. Do it again next month for the next-lowest number. And put a verification date on each one, because a bus factor you raised with a document you never re-check will quietly slide back to one while the page still looks fine.

The bus factor is not really about buses. It is about whether your team's ability to keep working depends on any single person staying reachable. You cannot make that risk zero, but you can find it, name it, and spread it, one artifact at a time, before the sick day that would have found it for you.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>bus-factor</category>
            <category>engineering</category>
            <category>documentation</category>
            <category>knowledge-decay</category>
            <category>team</category>
            <category>devops</category>
        </item>
        <item>
            <title><![CDATA[GitHub issue templates: the fields worth requiring]]></title>
            <link>https://scribelet.app/blog/github-issue-template</link>
            <guid isPermaLink="false">https://scribelet.app/blog/github-issue-template</guid>
            <pubDate>Sat, 29 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Most GitHub issue templates get skipped or filled with blanks. Copy a bug report template, a bug issue form, a feature form, and the fields to delete. Try it free.]]></description>
            <content:encoded><![CDATA[
Here is a bug report from a real repository. The issue template was added a year ago by someone who wanted better bug reports.

```markdown
## Describe the bug
It doesn't work

## Steps to reproduce
1. open the app
2. see error

## Expected behavior
it should work

## Environment
- OS:
- Version:
```

Every heading has an answer under it. The reporter filled in the form. And the maintainer still has to open a comment thread to ask the three questions that would let anyone reproduce this: which version, which OS, and what the error actually said.

This is the normal outcome. A project gets noisy issues, someone copies a GitHub issue template from a popular repo, and a year later the template is a wall of prompts that reporters skim past and maintainers still have to chase. The usual diagnosis is that people write lazy bug reports. The real cause is in the template: it asks open questions a hurried reporter answers with "it doesn't work," when it could have required the two or three fields that make an issue actionable.

A good issue template is not a longer form. It is a shorter one that refuses to submit without the parts triage cannot work without. That distinction is the whole difference between a template that survives and one that becomes decoration, and the rest of this post is how to build the first kind. If you would rather keep your team's own troubleshooting notes in a place an [AI assistant can actually read and check them](https://scribelet.app), Scribelet is built for exactly that, but the template comes first.

## What is a GitHub issue template?

A GitHub issue template is one or more files in your repository that pre-fill the body of a new issue, so every report arrives in the same shape. They live in a `.github/ISSUE_TEMPLATE/` directory, and GitHub reads them when someone clicks "New issue."

There are two formats, and choosing between them is the first real decision:

- A **Markdown template** (`.md`) drops a block of headings and prompts into the issue body. The reporter types over the prompts. Nothing is enforced; the whole thing is still a free-text box with some suggested structure. This is the same mechanism as a [pull request template](https://scribelet.app/blog/pull-request-template), just for issues instead of PRs, and it is [a markdown file in your repository](https://scribelet.app/blog/docs-as-code) that the platform reads at issue-creation time.
- A **YAML issue form** (`.yml`) renders real form fields: dropdowns, checkboxes, and text areas you can mark `required: true`. The reporter cannot submit until the required fields have content. This is the format that actually changes the quality of what you receive, because it can say no.

GitHub documents the mechanics of both well. [GitHub's own guide](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) covers where the files go and how the template chooser works, and the [issue forms syntax reference](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms) lists every field type. What none of that tells you is which fields to require and which to cut, and that is the question that decides whether the template earns its place.

## The template chooser most repos never set up

When you have more than one template, GitHub shows a chooser before the blank editor: a menu of "Bug report," "Feature request," and whatever else you define, plus links you control. Most repositories skip this and leave a single template plus the default blank-issue option, which means every reporter still starts from an empty box if they want to. Turning the chooser into an actual routing layer is a five-minute change with an outsized effect on triage.

![Diagram of a GitHub issue template chooser routing a new issue from the .github/ISSUE_TEMPLATE directory into a bug form, a feature form, or external contact links via config.yml](/blog/github-issue-template/issue-template-chooser.svg)

The routing is controlled by a single file, `.github/ISSUE_TEMPLATE/config.yml`, which most guides never mention. It does two things that matter: it can turn off the blank-issue escape hatch, and it can add contact links that send certain traffic somewhere other than your issue tracker.

```yaml
# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: Question or usage help
    url: https://github.com/your-org/your-repo/discussions
    about: Ask and answer usage questions in Discussions, not Issues.
  - name: Security vulnerability
    url: https://github.com/your-org/your-repo/security/advisories/new
    about: Report security issues privately, never in a public issue.
```

Setting `blank_issues_enabled: false` is the line that makes the whole template system work. Without it, every field you carefully marked required is optional, because the reporter can always click "Open a blank issue" and skip the form entirely. The contact links then divert the two kinds of traffic that should never be plain issues: support questions, which belong in Discussions, and security reports, which belong in a private channel. Both are answers to a "People Also Ask" question that comes up constantly, "how do I stop getting the wrong kind of issue," and neither is in the template itself.

## A bug report issue form worth copying

Here is a bug form that requires the three fields triage actually needs and asks for nothing it can infer. Save it as `.github/ISSUE_TEMPLATE/bug_report.yml`:

```yaml
name: Bug report
description: Something is broken or behaves incorrectly.
title: "[Bug]: "
labels: ["bug", "needs-triage"]
body:
  - type: textarea
    id: what-happened
    attributes:
      label: What happened, and what did you expect?
      description: One sentence each is fine.
    validations:
      required: true
  - type: textarea
    id: repro
    attributes:
      label: Steps to reproduce
      placeholder: |
        1. ...
        2. ...
        3. ...
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: Exact release or commit SHA. "latest" is not a version.
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Operating system
      options: [macOS, Windows, Linux, iOS, Android, Other]
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant logs or error output
      render: shell
    validations:
      required: false
```

Four required fields, one optional. The `version` field is `required: true` and its description refuses "latest," because a version you cannot pin is a bug you cannot close. The logs field uses `render: shell` so pasted output arrives as a formatted code block instead of mangled text. There is deliberately no "severity" dropdown and no "have you searched existing issues" checkbox, and the next section explains why.

## A feature request form, and where to stop

Feature requests fail in the opposite direction from bug reports. Bug templates ask too little; feature templates ask too much, demanding acceptance criteria and mockups from someone who just wanted to suggest an idea. Save this as `.github/ISSUE_TEMPLATE/feature_request.yml`:

```yaml
name: Feature request
description: Suggest an idea or improvement.
title: "[Feature]: "
labels: ["enhancement", "needs-triage"]
body:
  - type: textarea
    id: problem
    attributes:
      label: What problem would this solve?
      description: Describe the problem, not your proposed solution.
    validations:
      required: true
  - type: textarea
    id: proposal
    attributes:
      label: What would you like to happen?
    validations:
      required: false
```

One required field, and it asks for the problem rather than the solution, because the most useful thing a feature request can carry is a problem you had not heard framed that way. Everything downstream, the acceptance criteria and the scope, is your team's work once the idea is accepted, and asking a drive-by reporter to produce it up front just means fewer reports. That downstream work belongs in a [technical spec](https://scribelet.app/blog/technical-spec) or a [design document](https://scribelet.app/blog/software-design-document), not in the intake form.

## Markdown template or YAML issue form?

The two formats are not interchangeable, and the choice is not a matter of taste. Use this table to decide per template:

| Question | Markdown template (`.md`) | YAML issue form (`.yml`) |
|---|---|---|
| Can it require a field? | No, everything is optional | Yes, `required: true` blocks submit |
| Dropdowns and checkboxes? | No, plain text only | Yes |
| Reporter can delete the structure? | Yes, it is editable text | No, fields are fixed |
| Renders logs as code automatically? | No | Yes, with `render: shell` |
| Good for | A small internal repo where trust is high | Any public repo, or high issue volume |
| Setup effort | Lowest, one Markdown file | Slightly higher, YAML schema |

The short version: on a small team where everyone already writes good issues, a Markdown template is enough and costs the least to maintain. On a public repository, or anywhere the issue volume is high enough that triage is a chore, a YAML issue form is the only one that can actually enforce the fields, because it is the only one that can refuse to submit. The pattern is not unique to GitHub, either: GitLab offers the same idea as [description templates](https://docs.gitlab.com/user/project/description_templates/), so a team on either platform is making the same choice about what to require.

## A Markdown bug report template to copy

If the table points you at the Markdown route, here is a bug report template worth starting from. It drops the same structure the YAML form enforces into a plain, editable body, which is all a small, high-trust repo needs. Save it as `.github/ISSUE_TEMPLATE/bug_report.md`:

```markdown
---
name: Bug report
about: Something is broken or behaves incorrectly.
title: "[Bug]: "
labels: ["bug", "needs-triage"]
---

### What happened, and what did you expect?
One sentence each is fine.

### Steps to reproduce
1.
2.
3.

### Version
Exact release or commit SHA. "latest" is not a version.

### Operating system
macOS, Windows, Linux, iOS, Android, or Other.

### Relevant logs or error output
Paste any error output here.
```

The block at the top (name, about, title, labels) is the front matter GitHub reads to label the template and show it in the chooser; everything below it is the body the reporter types over. It asks for the same four things the issue form requires, but it cannot refuse a blank answer. That is the trade: a bug report template in Markdown costs nothing to maintain and enforces nothing, so reach for it only where you trust everyone to fill it in. Everywhere else, the issue form above is the version that holds the line.

## The fields to delete

The reason issue templates rot into decoration is that every field looks reasonable in isolation, so they accumulate. The discipline is subtractive. Delete these:

- **"Have you searched for existing issues?"** A checkbox everyone ticks and no one honors. It shifts blame to the reporter without preventing a single duplicate. Deduplication is triage's job, not the reporter's.
- **A "severity" dropdown.** Reporters rate almost everything as high. You will re-triage severity yourself the moment you read the issue, so requiring it up front adds a field and changes nothing.
- **"Additional context."** A polite way of saying "type more." If a field does not have a specific question, it collects filler.
- **A code-of-conduct acknowledgment.** It belongs in `CONTRIBUTING.md` and the repo's community health files, not stapled to every bug report.
- **Anything the platform already captures.** GitHub records who opened the issue and when. Do not ask for a name, a date, or a "reporter" field.

A template that asks four sharp questions gets four real answers. A template that asks twelve gets twelve half-answers and a reporter who resents the form. Fewer required fields, each one load-bearing, is the entire craft.

## What a good issue actually looks like

With the bug form above, the "it doesn't work" report from the opening becomes something a maintainer can act on without a single follow-up:

```markdown
### What happened, and what did you expect?
Exporting a note to PDF produces an empty file. Expected the note's contents.

### Steps to reproduce
1. Open any note with images
2. File > Export > PDF
3. Downloaded PDF is 0 bytes

### Version
2.4.1

### Operating system
macOS
```

Nothing here is longer than the broken report. It is not more effort for the reporter; the form simply pointed the same effort at the parts that matter. That is what a good issue template does. It does not extract more from people, it aims what they were already willing to give.

## Issue templates rot too

Here is the part almost no guide covers, and it is the reason to treat your templates as living files rather than set-and-forget config. An issue template is a small piece of [documentation about your own project](https://scribelet.app/blog/internal-documentation), and like every other piece, it drifts out of sync with the project it describes.

The `os` dropdown still lists a platform you dropped support for. The `config.yml` contact link points at a Discord server you migrated off a year ago, so reporters click it into a dead invite. A required "version" field references a versioning scheme you have since changed. The bug form auto-assigns `needs-triage` to a label your team renamed, so nothing gets triaged. None of this throws an error. The template keeps rendering, reporters keep filling it in, and it quietly routes issues to the wrong place. This is the same [slow decay that turns any repository artifact stale](https://scribelet.app/blog/outdated-documentation): the code moved and the file that describes it did not.

The fix is the same fix that works for [any documentation that lives beside your code](https://scribelet.app/blog/knowledge-decay). Put the templates in the review path. When a pull request renames a label, changes the supported platforms, or moves a community channel, the diff should also touch `.github/ISSUE_TEMPLATE/`, and a reviewer should be able to see that it did. Templates that are reviewed alongside the code they describe stay honest; templates that live in a folder nobody opens after the initial commit are the ones that rot.

This is also where an AI layer earns its place. A mechanical check can confirm the YAML parses and the links return a 200, but it cannot tell you that the platform you still list was deprecated two releases ago, or that the label you auto-assign no longer exists in the project. That kind of drift is a mismatch between the template and the world, and catching it means [checking the artifact against a live source of truth](https://scribelet.app/learn/ai/github-connector) rather than against its own syntax. Scribelet's approach to notes is the same idea pointed at your own knowledge: an assistant that reads what you wrote and flags where it has quietly gone out of date. You can [try it free](https://scribelet.app) and keep your team's triage notes, runbooks, and templates somewhere they get checked instead of trusted.

## Start with four fields

The temptation with any issue template is to add. Every maintainer who has been burned by a vague report wants to add one more required field to prevent the next one, and the sum of those additions is the wall of prompts nobody reads. Resist it. Start with a bug form that requires what happened, how to reproduce it, the exact version, and the operating system, and a feature form that requires only the problem. Turn off blank issues so the fields are real. Route questions and security reports out with `config.yml`. Then, every quarter, delete a field instead of adding one, and put the templates in front of a reviewer the same way you would any other file that describes how your project works.

A GitHub issue template cannot make people care. What it can do is take the care they already have and point it at the four things you cannot triage without, and refuse, politely, to accept anything less.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>github-issue-template</category>
            <category>issue-templates</category>
            <category>bug-report-template</category>
            <category>code-review</category>
            <category>engineering</category>
            <category>documentation</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Docs as Code: the workflow, the tools, and its limits]]></title>
            <link>https://scribelet.app/blog/docs-as-code</link>
            <guid isPermaLink="false">https://scribelet.app/blog/docs-as-code</guid>
            <pubDate>Fri, 28 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Docs as code puts docs in the repo, reviewed in pull requests and checked by CI. Here's the workflow, the tools, and the gap it can't close. Try it free.]]></description>
            <content:encoded><![CDATA[
A team I know did everything right. Their documentation lives in the same repository as the service it describes. Every change to it goes through a pull request. A reviewer signs off, a link checker runs in CI, the site rebuilds on merge. This is docs as code, textbook grade, and their onboarding guide still told a new engineer to point at a staging database that was decommissioned in the spring.

That is the thing nobody tells you when they sell you the workflow. Docs as code fixes *where documentation lives* and *how it changes*. It does not fix *whether it is still true*. Those are different problems, and the second one is the one that pages you at 2 a.m. Before we get to that gap, though, the workflow is worth doing well, because it removes an entire category of failure that the old wiki never could. Here is how it actually works, the toolchain that runs it, and the honest edge where it stops.

## What is docs as code?

Docs as code is the practice of writing and maintaining documentation using the same tools and process you use for source code: plain-text files, version control, code review, and continuous integration. Instead of a doc living in a separate wiki or a Google Doc that drifts on its own timeline, it lives in a repository as Markdown (or AsciiDoc, or reStructuredText), it changes through pull requests, and it ships through an automated build. The most-read example is a project's [README](https://scribelet.app/blog/how-to-write-a-readme), a Markdown file at the repository root that every reader opens first.

The [canonical definition from Write the Docs](https://www.writethedocs.org/guide/docs-as-code/) lists the ingredients: issue trackers, version control, plain-text markup, code reviews, and automated tests. The point of naming them together is that documentation stops being a special artifact handled by a special process. It becomes one more thing in the pipeline, subject to the same discipline as the code.

The appeal is obvious to anyone who has watched a wiki rot. When the doc and the code change in the same pull request, the diff is right there in review. A reviewer who notices the code changed but the doc did not can say so before the merge, not six months later. That single property, documentation reviewed *alongside* the change that affects it, is the whole pitch, and it is a good one.

## How docs as code works: the pull request pipeline

The workflow is a pipeline. A change to documentation moves through the same stages a code change does, and each stage has a tool and a specific failure it catches. This is the part most "what is docs as code" explainers wave at instead of laying out, so here is the pipeline stage by stage.

| Stage | What happens | Typical tool | What it catches |
|---|---|---|---|
| **Author** | Write the change in plain text, in the repo, in a branch | Any editor, Markdown/AsciiDoc | Nothing yet; this is the draft |
| **Propose** | Open a pull request with the doc change (ideally in the same PR as the code it describes) | GitHub / GitLab | Documentation that was never proposed for review at all |
| **Lint** | CI runs a style and prose linter on the changed files | Vale, markdownlint | Broken heading hierarchy, banned terms, passive-voice sprawl, style-guide drift |
| **Check links** | CI crawls internal and external links in the changed pages | lychee, htmltest | Dead links, moved pages, the 404 nobody clicks until on-call does |
| **Build** | CI builds the docs site from source; a build error fails the check | MkDocs, Sphinx, Docusaurus, Antora | Malformed syntax, missing includes, a broken code sample that no longer compiles |
| **Review** | A human reviews the diff next to the code diff | GitHub / GitLab review | The claim that is now wrong because the code in the same PR changed |
| **Merge & publish** | On merge, CI deploys the built site automatically | GitHub Actions, GitLab CI, Netlify | A published site that lags the merged source |

Read the table top to bottom and one thing stands out. Five of the seven stages are mechanical: a machine can decide pass or fail. Only two, authoring and review, need a human. That ratio is exactly why docs as code scales where a wiki does not. The mechanical checks never get tired, never skip a Friday, and never assume someone else already looked. If you want to see the review stage taken seriously as its own artifact, a good [pull request template that people actually fill in](https://scribelet.app/blog/pull-request-template) does for the human half what CI does for the mechanical half.

![The docs as code pipeline: author, pull request, CI checks, and merge plus publish, and the world-change that fires no CI check](/blog/docs-as-code/docs-as-code-pipeline.svg)

If your team has a wiki that everyone agrees is out of date and nobody will fix, moving to this pipeline is a real upgrade, and it is the cheapest reliability win in the whole documentation stack. [Start free](https://scribelet.app) if you want a place to keep the notes that do not belong in a repo but still need to stay honest.

## The docs as code tools

There are three tool decisions, and most of the noise online is people arguing about the third one while the first two matter more.

**The markup format** is the foundation. Markdown is the default and the right choice for most teams: everyone already knows it, and it renders everywhere. Reach for AsciiDoc when you need real structure (admonitions, includes, conditional content) that Markdown fakes badly, and for reStructuredText mainly when you are already in the Python and Sphinx world. Pick one and standardize; a repo with three markup dialects is a repo with three linters. Diagrams get the same treatment: write them as [Mermaid diagrams](https://scribelet.app/blog/mermaid-diagrams) in a fenced text block and they version, diff, and review alongside the prose instead of arriving as an uneditable PNG.

**The static site generator** turns your source files into a published site. This is the decision people obsess over, and honestly the differences matter less than the fact that you chose one and wired it into CI.

| Generator | Best when | Notes |
|---|---|---|
| **MkDocs** (Material) | You want a docs site running this afternoon | Markdown-native, the Material theme is excellent out of the box |
| **Docusaurus** | You want versioned docs and are comfortable in the React ecosystem | Strong for product docs with multiple released versions |
| **Sphinx** | You are documenting Python, or need reStructuredText's power | The origin of much of "docs as code" culture; steeper learning curve |
| **Antora** | You have docs spread across many repositories | Built for multi-repo documentation at organizational scale |

**Version control and CI** are the parts you already own. The docs live in Git next to the code, and the checks run in whatever CI you already use for the code. That is the whole reason the practice is cheap to adopt: you are not buying a documentation platform, you are pointing your existing platform at a folder of text.

The tell that a team has actually adopted docs as code, rather than just filing markdown in a repo, is the CI config. If nothing runs on a documentation pull request, you have version-controlled documents, not docs as code. The government engineering teams that publish their standards in the open, like the [UK Home Office engineering guidance](https://engineering.homeoffice.gov.uk/patterns/docs-as-code/), treat the pipeline, not the file location, as the practice.

## A repo layout that survives contact with a real team

Where the docs live inside the repo is a smaller decision than the format wars suggest, but getting it wrong invites drift. Two patterns dominate.

**Docs next to the code they describe** keeps a service's documentation in that service's repository, so the doc and the code share a pull request and a review:

```text
payment-service/
  src/
  tests/
  docs/
    index.md
    architecture.md      # the design decisions
    runbook.md           # what on-call does at 2 a.m.
    api.md
  mkdocs.yml
  .github/workflows/docs.yml
```

**A central docs repository** collects documentation that spans many services (a platform handbook, cross-cutting standards) in one place, usually built with a multi-repo tool like Antora. Most organizations end up with both: per-service docs in each service repo, and a central repo for the things that belong to no single service.

The rule that keeps either layout honest is proximity. The closer a claim sits to the code that makes it true, the more likely the person changing that code will change the claim in the same breath. A runbook in the service repo gets updated in the migration PR; the same runbook in a wiki three clicks away does not. This is the same failure that makes [runbooks go stale](https://scribelet.app/blog/runbook) the moment the command they call gets renamed, and the same instinct behind keeping [architecture decision records](https://scribelet.app/blog/architecture-decision-record-examples) in the repo as numbered files rather than in a decision-log wiki nobody opens.

## The CI checks that keep docs honest

The mechanical half of the pipeline is where docs as code earns its keep, and it is worth being specific about what to run, because "add CI" is not advice. Here is a minimal but real GitHub Actions job that lints prose, checks links, and fails the build on a broken site:

```yaml
name: docs
on:
  pull_request:
    paths: ['docs/**', 'mkdocs.yml']
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint prose
        uses: errata-ai/vale-action@reviewdog
      - name: Check links
        uses: lycheeverse/lychee-action@v2
        with:
          args: --no-progress './docs/**/*.md'
      - name: Build site (fail on warnings)
        run: |
          pip install mkdocs-material
          mkdocs build --strict
```

Three checks, three distinct failures. [Vale](https://vale.sh/) lints prose against a style guide you define, so "we always say pull request, never PR" becomes a rule a machine enforces instead of a habit reviewers forget. `lychee` crawls every link in the changed files and fails on a dead one, which is the single highest-value check because a dead link is the most common and most quietly damaging doc defect. And `mkdocs build --strict` fails on any warning, so a broken include or a reference to a page you deleted stops the merge instead of shipping.

Add one more if your docs contain code samples that are supposed to work: run them. A tested code block is the only kind that cannot silently rot, because the test fails the day the API it calls changes. Untested samples are the parts of your documentation most likely to be wrong, precisely because they look the most authoritative.

## What docs as code still can't do

Here is the honest edge. Every check in that pipeline verifies the documentation against *itself and its repo*: is the markup valid, do the internal links resolve, does the site build, does the prose match the style guide. Not one of them verifies the documentation against *the world*.

Go back to the onboarding guide pointing at the decommissioned database. The markup was valid. The internal links resolved. The site built cleanly. Vale had no complaints. Every check was green, and the doc was wrong, because the thing that changed was not in the diff. Someone decommissioned a database in an infrastructure repo the docs pipeline never watches, and nothing in a diff-based workflow fires when the world changes and the file does not. The tech writer Sarah Moir made this argument well in a post called [docs as code is a broken promise](https://idratherbewriting.com/blog/thoughts-on-docs-as-code-promise): the workflow gives you the *mechanism* to keep docs current and then quietly leaves the *deciding-to* entirely up to humans, who forget.

This is the same rot that catches every kind of engineering documentation, which is why it deserves [its own honest accounting](https://scribelet.app/blog/outdated-documentation) rather than a footnote. Docs as code makes documentation *maintainable*. It does not make it *accurate*. It moves the problem from "where does this doc live and how does it change" (solved, genuinely) to "who is going to read this against current reality and notice it is now false" (unsolved, still a person's forgettable job). The pipeline turned five human failures into machine checks and left the two that actually decide truth exactly where they were.

If you want the maintenance layer your repo is missing, the pattern is to give each claim a *last-verified* date separate from its *last-edited* date, and something other than a human's memory to do the re-checking. That is the [maintenance layer most wikis never build](https://scribelet.app/blog/internal-documentation), and it is the piece docs as code leaves for you.

## Docs as code with AI

The missing check is verification against reality, and that is the one an AI can now run. Instead of only asking "does this document build," you ask "is this document still true," and you point the question at a source of current truth: the code, the API, the live web.

This is the layer Scribelet adds on top of the docs-as-code instinct. Background agents periodically re-check the claims in your notes against the outside world and flag the ones that have gone stale, with a diff showing what changed and why, not a black-box verdict. Connect the [GitHub connector](https://scribelet.app/learn/ai/github-connector) and the check runs against your actual repository, so a doc that describes a function signature which changed gets flagged the way a broken link gets flagged in CI, except the source of truth is your code, not the doc's own markup. It is the same [AI verification](https://scribelet.app/learn/ai/ai-verification) idea CI already trained your team to expect, extended to the one axis CI cannot see.

None of this replaces the pipeline. Keep the version control, keep the reviews, keep Vale and lychee and the strict build. Add the check that watches for the change that never lands in your diff. Docs as code was always a bet that documentation should live in the same system as the truth it describes. Verification is what makes the bet pay, because [knowledge has a half-life](https://scribelet.app/blog/knowledge-decay) whether or not your linter noticed.

## Getting started

Adopting docs as code is not a migration project. Pick one service, move its docs into the repo as Markdown, add a three-line CI job that checks links and builds the site, and require doc changes to go through the same pull request as the code. That is a complete, working docs-as-code setup, and you can have it running before lunch.

Then be honest about the edge. The green checkmark means your documentation is well-formed and its links resolve. It does not mean the documentation is true. For that you need a last-verified date, a trigger for when to re-check, and something that does the checking on its own. [Start free](https://scribelet.app) and point the first check at the doc you trust least: the runbook, the onboarding guide, the integration page you have not read since you wrote it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>documentation</category>
            <category>docs-as-code</category>
            <category>engineering</category>
            <category>devops</category>
            <category>technical-writing</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Context rot: why long AI sessions get worse over time]]></title>
            <link>https://scribelet.app/blog/context-rot</link>
            <guid isPermaLink="false">https://scribelet.app/blog/context-rot</guid>
            <pubDate>Sat, 15 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Context rot is why a long AI chat degrades even inside a huge context window. How to spot it, when to compact vs reset, and what to keep. Try it free.]]></description>
            <content:encoded><![CDATA[
The session started sharp. You gave the agent a bug, it read the right files, made a clean fix, and moved on. Two hours and forty messages later it is a different collaborator: it re-suggests a change you already rejected, forgets a constraint you set at the start, and cites a file that got deleted an hour ago. You have not changed models or lowered your standards. The same assistant that felt reliable at message five feels unreliable at message forty, and the only thing that changed is how much it is now holding in its head.

That decline has a name, and it is not a bug in the model. It is context rot: the steady drop in an AI's accuracy and judgment as the text it is working from grows longer, even when that text still fits inside the window. The counterintuitive part is that a bigger context window does not fix it and often makes it worse, because the problem was never running out of room. The problem is that more text means less attention paid to any one part of it.

This piece is the practical version. What context rot is, why long context degrades even when it fits, how to tell rot apart from a plain bad prompt, when to compact a session versus reset it versus start over, what to keep and what to throw away, and the failure underneath all of it: the context you assemble is a document, and documents rot.

## What is context rot?

Context rot is the measurable degradation in a large language model's performance as its input grows longer: as you fill the context window, the model becomes worse at recalling facts, following instructions, and reasoning over what it was given, even though every token still technically fits. The term was coined by a developer in mid-2025 and pinned down by [Chroma's research](https://www.trychroma.com/research/context-rot), which tested state-of-the-art models and found that performance consistently degrades as input length increases, across every model they measured. Redis's write-up on [context rot](https://redis.io/blog/context-rot/) describes it the same way, as the performance drop that happens when a model has to process increasingly long input.

![Line chart showing model accuracy staying high for short inputs then declining as the context window fills toward its limit, with the reliable working region much smaller than the advertised window size](/blog/context-rot/degradation-curve.svg)

The distinction that trips people up is between the window and the rot. The [context window](https://www.ibm.com/think/topics/context-window) is the capacity: the total amount of text a model can take in at once, measured in tokens, covering your prompt, the system rules, the chat history, and the answer. Vendors advertise ever larger windows, 200,000 tokens, a million, two million. Context rot is what happens inside that capacity. A model with a two-million-token window does not reason as well over 1.5 million tokens as it does over five thousand. The window tells you what the model can hold. Context rot tells you what it can actually use well, and the second number is much smaller than the first.

This is also why "just paste in everything" is bad advice dressed up as thoroughness. Filling the window feels safe, like giving the model more to go on. In practice it dilutes the model's attention across a pile of text that is mostly irrelevant to the current step, and buries the few lines that matter.

## Why long context degrades

Three things happen as the input grows, and they stack.

**Attention dilution.** A transformer spreads its processing across every token it is given. Double the tokens and each one gets roughly half the focus. The model is not ignoring your instruction on purpose; it is spending a sliver of its attention on it because there are ten thousand other tokens competing for the same budget.

**Lost in the middle.** Models reliably use information at the very start and the very end of their input, and reliably miss things buried in the middle. A key instruction sitting halfway through a long thread is the single most likely thing to be dropped. This is not a quirk of one model; it shows up across the field.

**Accumulated clutter.** A long session collects debris: resolved tangents, abandoned approaches, full error logs from bugs that are already fixed, files you looked at once and no longer need. None of it is deleted, so all of it is still competing for attention and, worse, still available for the model to act on. It will happily revive a plan you killed twenty messages ago because that plan is still sitting in the context, reading as current.

![Diagram of a filling context window where useful signal stays a thin constant band while clutter, resolved tangents, stale files, and dead instructions, grows to crowd it out, with a note that pruning and resetting restore the signal's share](/blog/context-rot/signal-vs-clutter.svg)

The clutter point is the one people underestimate, because it is the one you create yourself. Attention dilution and lost-in-the-middle are properties of the model. Clutter is a property of how you run the session, which means it is the part you can actually fix.

## How to tell context rot from a bad prompt

Not every bad answer is context rot, and treating a prompt problem as a rot problem (or the reverse) wastes time. The tell is almost always *when* the answer went wrong and *how full the window was* when it did. Use the symptom to find the cause before you reach for a fix.

| Symptom | Likely cause | Quick test | Fix |
|---|---|---|---|
| Good early in the session, worse the longer it ran | Context rot | Start a fresh session with the same opening prompt; if the answer is good again, it was rot | Reset or compact the session |
| Wrong from the very first message | A bad prompt, not rot | The window was near-empty, so length cannot be the cause | Rewrite the prompt, or add a worked example |
| Fails the same way even in a short, clean session | Model limit or genuinely hard task | Retry on a stronger model with a near-empty window | Break the task into steps, or switch models |
| Confidently states something that used to be true | A stale source in the context | Find the line in the note, doc, or memory it is echoing | Fix the source, not the prompt |
| Ignores an instruction buried in a long middle | Lost in the middle | Move that instruction to the very end and retry | Restate the key instruction late, where attention is high |

The most valuable row is the fresh-session test. It costs thirty seconds and it cleanly separates the two most common cases: if the same first prompt produces a good answer in an empty window and a bad one deep in a long thread, the prompt is fine and the context is the problem. If it fails both ways, stop editing the session and fix the prompt or the task. A related technique when one prompt is trying to do too much is to [break it into a chain of smaller steps](https://scribelet.app/blog/prompt-chaining), each of which runs on a short, clean input instead of the whole accumulated thread.

## Compact, reset, or start fresh

Once you know it is rot, you have three moves, and picking the wrong one either loses state you needed or drags along the exact clutter that caused the problem. The choice comes down to how much of the current context is still worth keeping.

| Situation | Do this | Why |
|---|---|---|
| Long thread, most of it still relevant, you need continuity | Compact: summarize the thread, keep the summary, drop the raw history | Preserves the state, sheds the token weight that dilutes attention |
| The useful state is small enough to restate in a sentence or two | Start fresh | Cheaper and cleaner than carrying a long history for two facts |
| The task itself changed (new feature, new goal, different files) | Start fresh | The old context is now pure clutter that can only mislead |
| Degrading, but you cannot tell what is still needed | Reset and rebuild deliberately | Add back only what the current task needs, one piece at a time |
| One stale fact is poisoning the answers | Fix the source first, then reset | Compacting a wrong fact just carries it forward inside the summary |

Compaction is the default that tools reach for, and it is genuinely useful, but it has a catch worth naming: a summary is lossy, and it is generated by the same model that is already struggling with the long context. Compact too aggressively and you lose the detail the next step needed; compact a mistake and you launder it into an authoritative-looking summary that is harder to catch than the original. Reset is blunter and safer when you can afford to lose the history, which is more often than the sunk cost of a long thread makes it feel.

## What to keep and what to drop

Managing context rot is mostly a triage habit: at any moment, know what in the window is earning its place and what is just taking up attention. The rule of thumb is that the context should hold what the current step needs and almost nothing else.

| In the context | Keep or drop | Note |
|---|---|---|
| The current task and its goal | Keep, and place it late | Put it where attention is highest, near the end, not buried at the top |
| Files or code you are actively editing | Keep | The live working set is the point |
| Resolved tangents and abandoned approaches | Drop | Dead paths the model will otherwise revive as if current |
| Full error logs after the bug is fixed | Drop, keep the one-line lesson | The log is noise once resolved; the lesson is signal |
| A long doc you have already pulled what you need from | Drop it, keep the extract | Keep the three lines you used, not the thirty pages |
| A stale instruction that is no longer true | Drop and fix at the source | A confident false instruction is worse than no instruction |
| Standing rules that apply to every turn | Move to the [system prompt](https://scribelet.app/blog/system-prompt) | Durable rules do not belong in the churn of a thread |

The last row is the quiet win. Anything you find yourself re-pasting into session after session is not session context at all; it is a standing rule, and it belongs above the task where it is stated once and applied every turn. The same goes for facts the model needs to carry across sessions: those belong in [structured AI memory](https://scribelet.app/blog/ai-memory), not re-explained into every fresh thread, where they add to the very clutter you are trying to control.

## The context you assemble is an artifact that rots

Step back and the pattern is familiar. You assemble a context to work from: a system prompt, a spec, a pile of notes, a memory store, a few pasted docs. It works. So you keep it, and reuse it, because rebuilding it every time is tedious. That is the right instinct and the start of the problem, because everything you kept was true on the day you wrote it and nothing in the context has an expiry field.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), the same rot that turns a good runbook into a liability and a good note into a quiet lie, showing up one layer up in the material you feed an AI. Context rot inside a single session is the fast version: attention thins over the course of a long thread, and you fix it by pruning. But the assembled context you carry between sessions rots on a slower clock and does far more damage, because an agent reads it, trusts it, and acts on it without the raised eyebrow a human teammate would give a stale instruction. The parts that go stale fastest are the ones tied to something with its own schedule: a named file that gets renamed, an external fact that changes, a rule that was true for exactly one release. It is the same failure that makes an old prompt or chain quietly misfire and makes [the context an AI coding agent reads](https://scribelet.app/blog/agentic-coding) steer the next ten tasks wrong.

The fix is upstream. Pruning a session buys you a good afternoon; keeping the source material honest is what keeps every session built on it honest. That is the premise Scribelet is built on: the notes, facts, and instructions your AI works from are things you maintain, not just store. When the material an assistant draws from can be listed, checked, and corrected in one place, a fact that stopped being true gets caught and fixed at the source, instead of aging silently until it poisons a summary you will never think to re-read.

## Keep the window small on purpose

Context rot is not a flaw to wait out. Models will keep getting better at long context, and long context will keep getting worse than short context, because attention is finite and dilution is arithmetic. The habit that survives every model release is the same one: put in what the current step needs, place the important part where the model actually looks, and clear out the rest before it accumulates.

Treat the context you keep the way you would treat any note you rely on, as something that was true when you wrote it and deserves a look before you trust it again. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what it looks like when the material your AI works from is something that tells you when it has gone stale, instead of quietly rotting while every answer stays confident.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>context-rot</category>
            <category>ai</category>
            <category>llm</category>
            <category>context-window</category>
            <category>ai-memory</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Agentic coding: how to work with an AI coding agent]]></title>
            <link>https://scribelet.app/blog/agentic-coding</link>
            <guid isPermaLink="false">https://scribelet.app/blog/agentic-coding</guid>
            <pubDate>Fri, 14 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What agentic coding is, a workflow you can copy, when to delegate to an agent vs write it yourself, and why the context an agent reads quietly rots. Try it free.]]></description>
            <content:encoded><![CDATA[
The job changed and nobody sent a memo. A year ago, writing software meant typing it. Today a growing number of developers spend their day describing a task, watching an agent read files, run commands, and edit code for ten minutes on its own, and then reviewing what came back. The typing is increasingly the machine's job. The deciding, framing, and checking are yours.

That shift has a name. Agentic coding is the practice of handing a unit of work to an AI agent that can plan the steps, edit files, run tests, and iterate against the result, rather than autocompleting a line at a time or pasting snippets out of a chat window. It is the difference between an assistant that finishes your sentence and a colleague you can give a ticket to. The productivity stories are real, and so are the ways it goes quietly wrong.

This piece is the practical version: what agentic coding actually is, a workflow you can copy today, when to reach for an agent and when to keep your hands on the keyboard, where the approach breaks, and the failure almost nobody names, which is that the context you feed the agent decays the same way every other document does.

## What is agentic coding?

Agentic coding is a development approach where an autonomous AI agent takes an active role in writing, testing, and modifying software, using tools like reading and writing files, running shell commands, and searching the web, instead of only suggesting text for you to accept. IBM's write-up on [agentic coding](https://www.ibm.com/think/topics/agentic-coding) frames it the same way: coding agents combine the reasoning of a language model with access to real developer tools and the ability to execute.

The word doing the work is "agent." A plain code assistant predicts the next token. An agent runs a loop: it forms a plan, takes an action, observes the result, and decides the next action, repeating until the task is done or it gets stuck. That loop is why an agent can open a failing test, read the traceback, edit three files, rerun the test, and try again without you in the seat for each step.

It helps to place agentic coding against its neighbors, because the terms blur together in practice:

- **Autocomplete** finishes the line you are typing. You drive; the tool guesses ahead.
- **Chat-assisted coding** answers a question or writes a snippet you paste in. You are still the one editing files.
- **Agentic coding** takes a whole task and does the editing, running, and checking itself. You frame and review.
- **Vibe coding** is agentic coding with the review turned off: you accept whatever comes back without reading it, which is fine for a throwaway and a liability for anything that has to be correct.

The distinction that matters is where the human sits. In agentic coding you move up the stack, from writing the code to specifying and verifying it. Do that well and you get leverage. Do it carelessly and you get a large volume of plausible code nobody actually understands.

## A workflow you can copy

The single biggest predictor of whether agentic coding helps or hurts is how you hand off the work. A one-line prompt gets you a confident guess. A framed task gets you something you can check. Here is the loop that practitioners keep converging on, distilled from write-ups like Drew Breunig's [10 lessons for agentic coding](https://www.dbreunig.com/2026/05/04/10-lessons-for-agentic-coding.html) and Armin Ronacher's [agentic coding recommendations](https://lucumr.pocoo.org/2025/6/12/agentic-coding/).

![Diagram of the agentic coding loop: frame the task, let the agent plan then act and observe in a repeating cycle, then the developer reviews against the frame and either merges or sends it back](/blog/agentic-coding/agentic-loop.svg)

The frame is the part you write. Everything else is the agent's job, and your review is the gate at the end. A frame is not a paragraph; it is the set of decisions you do not want the agent making for you. Give it to the agent as the task:

```text
## Task
Add rate limiting to the public API.

## Context the agent should read first
- The middleware lives in src/server/middleware/.
- We already use Redis (see src/lib/redis.ts). Reuse that client.
- Follow the error format in src/server/errors.ts.

## What "done" means
- 100 requests per minute per API key, sliding window.
- Over the limit returns HTTP 429 with a Retry-After header.
- Unauthenticated requests are limited by IP, same numbers.

## Constraints
- Do NOT add a new dependency; use the existing Redis client.
- Do NOT change the public response shape of any existing endpoint.

## When you are done
- Add tests for: under limit, at limit, over limit, and IP fallback.
- Run the full test suite and show me the output before finishing.
```

Read what that frame prevents. The agent will not invent a new rate-limiting library, will not pick 60 requests instead of 100, and will not skip the IP fallback you care about, because each of those is now a line instead of a guess. The "context the agent should read first" section is doing quiet, heavy work: it points the agent at the code that already exists so it extends your system instead of building a parallel one. The "when you are done" section gives the agent something to check itself against, which is the part a bare prompt never has.

Two habits make the loop pay off. First, keep tasks small enough to review. An agent can write a thousand lines in a minute; you cannot honestly review a thousand lines in a minute, and the review is the whole point. Second, keep the agent's standing context in the repo, not in your head. Most coding agents read a project file (often named `AGENTS.md` or similar) on every run for durable rules like "run the linter before finishing" or "we use pnpm, not npm." That file is the agent's [system prompt](https://scribelet.app/blog/system-prompt) for your codebase, and it is where cross-cutting instructions belong so you do not repeat them in every task.

## When to reach for an agent, and when not to

Agentic coding is a tool, not a religion. Some work suits an agent perfectly; some is faster and safer by hand. The skill is telling them apart before you have burned twenty minutes finding out. This is the question the definitions skip, because the useful answer is a comparison.

| Situation | Reach for | Why |
|---|---|---|
| A well-scoped task with clear "done" criteria and existing patterns to follow | An agent | This is the sweet spot. Frame it, delegate, review the diff and the tests. |
| A one-character fix or something you can type faster than you can explain | Your keyboard | Framing the task costs more than the fix. Just do it. |
| Unfamiliar code you need to understand, not just change | Chat, then decide | Use the agent to explain and explore first. Delegating a change you cannot review is how bugs ship. |
| A large, cross-cutting change with real design questions | A [spec first](https://scribelet.app/blog/spec-driven-development), then an agent | Decide the shape yourself in a spec, then let the agent implement against it. |
| Anything touching security, money, or data you cannot easily undo | Your keyboard, or an agent on a very short leash | The cost of a confident wrong guess is too high. Review every line, or write it yourself. |

The pattern under the table: delegate when the work is well-defined and cheap to verify, keep your hands on it when the work is ambiguous or expensive to get wrong. An agent multiplies whatever clarity you bring. If the task is clear, it multiplies your speed. If the task is vague, it multiplies your confusion into a large, tidy-looking pull request.

The strongest version of the workflow pairs agentic coding with a written spec for anything non-trivial. A spec says what to build; the agent builds it; your review checks the build against the spec instead of against a vague memory. If you write software design documents or a [technical spec](https://scribelet.app/blog/technical-spec) already, you have most of the muscle. What changed is the reader: a spec used to inform a colleague who would ask when something was unclear. An agent does not ask. It guesses, confidently, so the spec has to close the gaps a human would have flagged.

## Where agentic coding breaks

Every technique trades one set of risks for another. Agentic coding trades the slowness of typing for a set of quieter failures, and the quiet ones are the ones that cost you in a month instead of a minute.

![Diagram showing a coding agent producing more output than a developer can carefully review, with the unreviewed remainder accumulating as review debt](/blog/agentic-coding/review-debt.svg)

| Failure mode | What it looks like | What to do |
|---|---|---|
| Review debt | The agent writes faster than you read, so you start skimming, then rubber-stamping. | Keep tasks small enough to review honestly. If you cannot review it, you cannot ship it. |
| Confident wrong guesses | The gaps you left in the task got filled with plausible defaults you never chose. | Frame the task: constraints, "done" criteria, out-of-scope. The gap is where the guess hides. |
| Hallucinated dependencies | The agent imports a package or calls an API method that does not exist but looks right. | Make "run it and show me the output" part of every task. Passing code cannot hallucinate. |
| Parallel systems | The agent rebuilds something you already have because it never saw the existing version. | Point it at the code to reuse in the task. An agent only knows the context you give it. |
| Rotting context | The `AGENTS.md`, specs, and docs the agent reads drift out of date, and the agent trusts them anyway. | Treat the agent's context as something to maintain, not just write. More on this next. |

The first three are about a single task and you catch them in review, if you actually review. The last two outlive the pull request, and they share a root cause: an agent is only as good as the context it reads, and that context both [fills up with clutter and goes stale](https://scribelet.app/blog/context-rot). The failure that gets the least attention is the one that compounds, so it gets its own section.

## The context an agent reads is an artifact that rots

Here is the part almost nobody writing about agentic coding mentions. An agent does not know your codebase. It knows what it can read at the moment it runs: the files you point it at, the `AGENTS.md` in your repo, the spec attached to the task, the [memory an AI keeps](https://scribelet.app/blog/ai-memory) across sessions. Those are the agent's map of your world, and every one of them is a document that was true when someone wrote it.

The moment the code changes and the context does not, the map starts lying. Someone renames the Redis client, but `AGENTS.md` still says "see src/lib/redis.ts." A later PR changes the error format, but the spec the next agent reads still describes the old one. Nothing broke. No test failed. The agent just inherited a confident, authoritative, wrong description of the system and built on top of it, which is exactly how [outdated documentation](https://scribelet.app/blog/outdated-documentation) does its damage, one stale line at a time.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and agentic coding is unusually exposed to it for two reasons. First, the context is precise, and precise things falsify fast: "we use pnpm" is trivially wrong the day the repo switches to bun. Second, the reader is an agent, which will not raise an eyebrow at a stale instruction the way a human teammate would. It reads the map, trusts it, and acts. The parts that rot first are the ones tied to something with its own clock:

- **A named file or function.** Any instruction that points at a path is wrong the refactor after it was written.
- **An external fact.** "The payments API returns `status: paid`" carries an expiry date the day that API changes, and no context file has an expiry field.
- **An out-of-scope line that quietly became in scope.** "We do not support webhooks yet" is true for exactly one release.

The workflow only pays off if the agent's context stays true, which means someone, or something, has to notice when it stops being true. The [same discipline that keeps a note honest](https://scribelet.app/blog/ai-fact-checking-for-notes), checking the source instead of trusting the copy, is what keeps an agent's context honest past its first use. That is the premise Scribelet is built on: the notes, docs, and facts your AI works from are things to maintain, not just store. When the reference material an agent leans on can flag its own staleness, a drifting instruction gets caught before it ships the wrong thing instead of quietly steering the next ten tasks wrong.

## Frame the work, then keep the context honest

Agentic coding moves you up a level, from writing code to deciding what code should be and checking that you got it. Done well, it is real leverage: frame a well-scoped task, delegate it to an agent that can plan and run and test, and review the result against criteria you set in advance. Done carelessly, it is a fast way to generate a lot of code nobody understands.

The two disciplines that separate the outcomes are small. Keep tasks small enough to review honestly, because the review is the part that makes the speed safe. And treat the agent's context, the `AGENTS.md`, the specs, the memory, the docs it reads, the way you would treat any note you rely on: as something that was true when you wrote it and needs a look before you trust it again. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what it looks like when the source of truth your AI works from is something that tells you when it has gone stale, instead of aging in silence while an agent builds on it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>agentic-coding</category>
            <category>ai</category>
            <category>software-development</category>
            <category>spec-driven-development</category>
            <category>system-prompt</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Meta prompting: use AI to write your prompts]]></title>
            <link>https://scribelet.app/blog/meta-prompting</link>
            <guid isPermaLink="false">https://scribelet.app/blog/meta-prompting</guid>
            <pubDate>Thu, 13 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What meta prompting is, a copy-paste meta-prompt template, when to reach for it, and why the prompt it writes quietly goes stale. Try it free.]]></description>
            <content:encoded><![CDATA[
You spend fifteen minutes wrestling with a prompt for a report you need, and the output is still generic mush. So you give up and try something else. You type: "I need a prompt that turns my raw meeting notes into a weekly status update for my manager. Ask me three questions first, then write it." The model asks about audience, length, and tone, you answer in a sentence each, and it hands back a prompt three times better than the one you were fighting with.

That is meta prompting, and the first time it works it feels like a cheat code. You stopped trying to be a prompt engineer and asked the thing that is good at language to do the part you are bad at.

Then you save the prompt it wrote, because it was good, and you reuse it every Monday. And somewhere around week seven it starts producing updates that are subtly wrong: the wrong length, a section your manager stopped caring about, a tone that fit the old team. Nothing errored. The prompt just kept doing exactly what it was told, long after what it was told stopped being right.

This piece covers what meta prompting is, a meta-prompt you can copy, when to reach for it instead of writing the prompt yourself, the ways it quietly goes wrong, and why the prompt it writes for you has an expiry date you will not see.

## What is meta prompting?

Meta prompting is the technique of using an AI model to write, improve, or structure the prompts you feed to an AI model. Instead of guessing at the wording yourself, you hand the model your goal and let it act as the prompt engineer: it asks what it needs to know, then produces a detailed, structured prompt you can run.

The name is literal. A normal prompt is an instruction about a task. A meta-prompt is an instruction about a prompt. You are one level up, working on the instruction itself rather than the work. OpenAI's [cookbook example on meta prompting](https://developers.openai.com/cookbook/examples/enhance_your_prompts_with_meta_prompting) describes it plainly: use a capable model to generate or refine a prompt, often a stronger model improving the instructions that a cheaper one will run at volume. IBM's write-up on [meta prompting](https://www.ibm.com/think/topics/meta-prompting) frames it as giving the model a reusable, step-by-step template in plain language rather than a one-off request. The [Prompt Engineering Guide](https://www.promptingguide.ai/techniques/meta-prompting) draws the same line: meta prompting focuses on the structure and syntax of a task rather than its specific content.

The appeal is real. Writing a good prompt is a skill, and most people do not have it, and the model has read more good prompts than any of us ever will. Asking it to write the instruction is often faster and better than writing the instruction by hand, especially for a task you will repeat.

The catch is the one nobody puts on the tin. A meta-prompt does not just save you the writing. It hands you a finished artifact, confident and complete, that you are now going to trust and reuse without ever having built the understanding that would tell you when it has gone wrong.

## The meta-prompt that does the work

The whole technique fits in a few lines. Here is a meta-prompt you can copy and adapt. The shape matters more than the exact words.

```markdown
I want a reusable prompt for the following task:

[describe the task in one or two plain sentences]

Before you write it, ask me up to 4 questions about anything that
would change the output: the audience, the format, the length, the
tone, and any edge cases the prompt must handle.

After I answer, write the prompt. Requirements:
- Start with the role and the single goal, stated once.
- List the inputs the prompt expects and the exact output format.
- Name what to do when an input is missing or ambiguous.
- Keep it as short as it can be while still unambiguous.

Then tell me, in one line, which of my answers you were least sure
about, so I know what to double-check.
```

Three things make this better than "write me a prompt for X", and each is a lever you can pull:

- **It interviews you first.** The single biggest reason a generated prompt is generic is that your request was generic. Forcing the model to ask before it writes pulls the context out of your head and into the prompt, where it belongs.
- **It names the failure cases.** "What to do when an input is missing" is the instruction people forget to write and the model forgets to follow. Asking for it up front is how you avoid a prompt that invents a value rather than flagging a gap.
- **It reports its own uncertainty.** The last line turns a black box into something you can check. The answer it was least sure about is the line most likely to be wrong, and now you know where to look.

![Diagram of the meta-prompting loop: describe the task, the AI interviews you, it drafts the prompt, you test it, you feed weak points back, and only then does the prompt get saved](/blog/meta-prompting/meta-prompting-loop.svg)

Notice what the loop does not end with. It does not end at "save the prompt." It ends at "test it, then feed the weak points back," and the difference between those two is most of whether meta prompting helps you or quietly hurts you later.

## When to meta-prompt, and when to just write it

Meta prompting is a tool, not a default. For a one-line ask you will use once, opening a dialogue with the model to write the prompt is slower than writing the request. The technique earns its cost when the prompt is going to be reused, or when the task is fiddly enough that you cannot see the right structure yourself.

It also sits next to other techniques that solve nearby problems, and reaching for the wrong one is the common mistake.

| Reach for | When | Instead of |
|---|---|---|
| Just writing the prompt | The task is simple, one-off, and you can see the right shape. | Spending three turns interviewing a model to save yourself one sentence. |
| Meta prompting | The prompt is complex or reusable, and you cannot see the structure. Let the model draft it, then you edit. | Rewriting a bad prompt by hand five times and hoping the sixth sticks. |
| [Few-shot prompting](https://scribelet.app/blog/few-shot-prompting) | The problem is a format or an edge case that one example would pin. | A longer instruction, when a worked example would say it in less space. |
| Editing the [system prompt](https://scribelet.app/blog/system-prompt) | The instruction should apply to every request, not just this one. | Pasting the same standing rule into every prompt by hand. |

The honest read is that meta prompting and the others are layers, not rivals. You might meta-prompt to draft a good instruction, keep the durable part of it in a system prompt, add a few-shot example to the request when a specific case needs pinning, and [break a big task into a chain of prompts](https://scribelet.app/blog/prompt-chaining) when one instruction is trying to do too much. What you should not do is treat the generated prompt as finished the moment it appears, which is exactly what its polish invites you to do.

## How meta prompting quietly goes wrong

The tutorials stop at "and now you have a great prompt". The failures that actually cost you come after that, and most of them are hidden because the generated prompt reads so well that you never inspect it.

| Failure mode | What you see | What caused it |
|---|---|---|
| Over-engineering | A short task comes back as a 300-word prompt with sections you did not need | The model optimizes for thoroughness. Given room, it adds structure whether the task wants it or not. |
| Invented constraints | The output obeys rules you never asked for: a word count, a format, a banned word | The model guessed at your intent and wrote its guess into the prompt as a hard rule. |
| Bloat you pay for | The prompt works but is long, and every run costs more tokens and more latency | A generated prompt is verbose by default. On a prompt you run often, the padding is a recurring bill. |
| Lost voice | The output is competent and sounds like nobody. Yours went missing | The model wrote a prompt for a generic professional, because you did not tell it whose voice to keep. |
| Skill atrophy | You can no longer fix the prompt when it drifts, because you did not write it | Outsourcing the writing outsources the understanding. When the prompt breaks, you are debugging a stranger's work. |
| Stale by design | It was perfect in March and subtly wrong by September, with no change on your end | The prompt froze the context of the day it was written. The world it captured moved. See below. |

The first two are worth catching on day one: read the prompt the model wrote before you trust it, and delete the constraints you did not ask for. The last one is the one nobody plans for, and it is the one worth dwelling on.

## The prompt it wrote has a shelf life

A generated prompt is a snapshot. When the model interviews you and writes an instruction, it bakes in everything true at that moment: the audience you named, the format you wanted, the tone that fit, the task as it stood. Then you save it, and it keeps steering toward that moment long after the moment has passed.

The Monday status update from the opening did not break because the model got worse. It broke because the prompt still encoded the manager, the length, and the sections that were right in the spring, while the actual job drifted underneath it. The output stayed confident and well-formatted the entire time, which is exactly why it took seven weeks to notice.

![Loop diagram: a meta-prompt generates a prompt that captures today's context, the context drifts, the saved prompt keeps steering to the old context, and the output stays confidently wrong](/blog/meta-prompting/prompt-shelf-life.svg)

This is the same rot that turns a good system prompt into scar tissue and a good runbook into a liability. It is [knowledge decay](https://scribelet.app/blog/knowledge-decay), one level up: the prompt is a note, the model reads it on every run, and nothing ever renders it visibly wrong. A meta-prompt makes the problem worse in one specific way, which is that a prompt you wrote yourself carries a memory of why each line is there, and a prompt the model wrote for you does not. You are more likely to keep it unquestioned, because you never questioned it in the first place.

The parts that rot fastest are the ones tied to something that changes on its own schedule:

- **A fact.** A generated prompt that says "our current pricing is X" or "the API returns Y" bakes a fact with an expiry into a place that has no expiry field.
- **A named target.** "Write for my manager Dana" is wrong the week Dana changes. The prompt does not know that.
- **A model assumption.** A prompt tuned for one model's quirks can misfire on the next one you switch to, and switching models is the whole point of being able to [choose your own provider](https://scribelet.app/blog/byok-ai).

If the context a meta-prompt captures comes from your own notes, the fix is upstream: the notes have to stay true. That is the premise of an assistant that treats your knowledge as something to maintain rather than only store. Scribelet's [AI memory](https://scribelet.app/blog/ai-memory) and background [fact-checking](https://scribelet.app/blog/ai-fact-checking-for-notes) exist so the material your AI works from can be listed, checked, and corrected in one place, instead of frozen into a prompt where it silently ages.

## A meta-prompt is an artifact, not a magic trick

Meta prompting is genuinely useful, and the case for it is simple: the model is better at writing prompts than most of us, and letting it do the part we are bad at is a good trade. Use it for anything reusable or fiddly. Let it interview you, because the interview is where the quality comes from.

But treat what it hands you as a draft, not a verdict. Read the prompt it wrote. Delete the constraints you did not ask for. Cut the length it padded. Keep the part that is durable, and keep it somewhere you can see and edit it, not buried in a chat you will never scroll back to. And re-read it on a schedule, because the prompt that was perfect in March is quietly steering your Monday mornings wrong by September, and the output will never tell you.

The trick is not getting a good prompt out of the machine. The trick is remembering that a good prompt, like a good note, is only good on the day you check it. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what it looks like when an AI has to show what it knows and where it learned it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>prompt-engineering</category>
            <category>meta-prompting</category>
            <category>ai</category>
            <category>llm</category>
            <category>system-prompt</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Prompt chaining: break one big prompt into steps]]></title>
            <link>https://scribelet.app/blog/prompt-chaining</link>
            <guid isPermaLink="false">https://scribelet.app/blog/prompt-chaining</guid>
            <pubDate>Thu, 13 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What prompt chaining is, a chain you can copy, when to chain vs few-shot vs chain-of-thought, and why a saved chain quietly goes stale. Try it free.]]></description>
            <content:encoded><![CDATA[
Here is a prompt a lot of people write on their first hard task: "Read these twelve pages of meeting notes, pull out the decisions, figure out which ones affect the roadmap, rank them by risk, and write me a one-paragraph update for my manager." One prompt, five jobs. The model does all five at once, badly. The decisions are half-right, the ranking is a guess, and the paragraph blends everything into a smooth summary that is confidently wrong in two places.

The fix is not a better mega-prompt. It is to stop asking for five things in one breath. Ask for the decisions. Take that output, and ask which ones touch the roadmap. Take that, and ask for the ranking. Then write the paragraph from the ranked list. Each step is small enough that the model can actually do it, and you can see the output of each one before it feeds the next.

That is prompt chaining, and it's the difference between a model that feels unreliable and one that feels like a tool. This piece covers what prompt chaining is, a chain you can copy, when to reach for it instead of a single prompt or few-shot examples, where chains break, and why a chain you save and reuse has an expiry date you will not see.

## What is prompt chaining?

Prompt chaining is a prompt engineering technique that breaks a complex task into a sequence of smaller prompts, where the output of each prompt becomes the input to the next. Instead of one instruction that tries to do everything, you get a pipeline: focused step, checked output, focused step, checked output, final result.

![Diagram comparing one overloaded prompt that outputs mush against a prompt chain where each step does one job and feeds the next](/blog/prompt-chaining/chain-pipeline.svg)

The reason it works is not magic, it is attention. A model asked to do one thing spends all of its capacity on that thing. A model asked to do four things at once splits its focus and cuts corners on all four. The [Prompt Engineering Guide](https://www.promptingguide.ai/techniques/prompt_chaining) describes chaining as breaking a task into subtasks and prompting the model with each in turn, using the response to the first as part of the input to the next. IBM's write-up on [prompt chaining](https://www.ibm.com/think/topics/prompt-chaining) frames it the same way, as generating a final output by following a series of prompts rather than a single one. Anthropic's guide to [building effective agents](https://www.anthropic.com/research/building-effective-agents) lists prompt chaining as the first and simplest workflow pattern: decompose a task into a fixed sequence of steps, and optionally check the output between them before continuing.

There is a second, quieter benefit. When a single prompt fails, you have no idea which part went wrong, so you rewrite the whole thing and hope. When a chain fails, you can see exactly which step produced the bad output and fix that one link. The chain is debuggable in a way the mega-prompt never is. If you already treat [your notes and instructions as things you maintain](https://scribelet.app/blog/knowledge-decay) rather than write once and forget, a chain fits the same habit: it's a workflow you can inspect a step at a time.

## A chain you can copy

The whole technique is easier to show than to explain. Here is a three-step chain for the meeting-notes task from the opening. Run each prompt, paste its output into the next, and read what comes back at each stage.

**Step 1: extract, do not summarize.**

```text
Below are my raw meeting notes. Extract every decision that was
actually made, one per line, in the format:

DECISION: <what was decided> | OWNER: <who> | DATE: <if stated>

Do not include discussion, opinions, or things that were only
proposed. Only decisions that were settled.

NOTES:
[paste raw notes]
```

**Step 2: filter against a goal.** Feed Step 1's list in.

```text
Here is a list of decisions from a meeting. Keep only the ones that
change our Q3 roadmap. For each, add one line: WHY IT MATTERS.
Drop the rest silently.

DECISIONS:
[paste Step 1 output]
```

**Step 3: write from the filtered list.** Feed Step 2's output in.

```text
Write a 4-sentence update for my engineering manager based only on
the decisions below. Lead with the highest-risk item. Plain language,
no hype, no filler. Do not invent anything not in the list.

DECISIONS:
[paste Step 2 output]
```

Notice what each step buys you. Step 1 forces the model to separate decisions from noise, which is the part it gets wrong when it is also trying to write prose. Step 2 does the judgment call in isolation, so you can eyeball the filter before it colors the writing. Step 3 writes from a clean, short input, so it has nothing to blur. If the final paragraph is wrong, you know within seconds whether the fault is extraction, filtering, or writing, because you kept all three outputs.

You do not need a framework for this. A chain is just running prompts in order and pasting outputs forward. Tools like LangChain automate the plumbing when a chain runs often enough to be worth wiring up, but the technique itself is copy, paste, read, repeat. Start there, and reach for automation only when the manual version has already earned its keep.

## When to chain, and when not to

Chaining is not always the right move. It costs more calls, more time, and more places to go wrong, so a task that a single prompt handles well should stay a single prompt. The question is which shape fits the job. This is also the question the search results for prompt chaining keep dancing around, because the honest answer is a comparison, not a definition.

| Situation | Reach for | Why |
|---|---|---|
| One clear task, one output | A single prompt | Chaining adds cost and failure points for no gain. |
| A task with distinct stages that build on each other | Prompt chaining | Each stage gets full attention, and you can inspect the handoffs. |
| The model keeps getting the format or category wrong | [Few-shot prompting](https://scribelet.app/blog/few-shot-prompting) | A few worked examples fix format and labeling faster than more steps. |
| One hard reasoning problem, solved in place | Chain-of-thought | Ask the model to reason step by step inside one prompt; the steps are its thinking, not separate calls. |
| A standing rule that should apply to everything | The [system prompt](https://scribelet.app/blog/system-prompt) | Durable instructions belong above the task, not repeated in every chain. |

The two that get confused most are prompt chaining and chain-of-thought, because both involve "steps." The difference is who does the stepping. Chain-of-thought is one prompt where the model reasons through steps out loud before answering; the steps are internal to a single call. Prompt chaining is several prompts where you own the boundaries, see each intermediate output, and decide what feeds the next. Use chain-of-thought for a single hard problem. Use chaining when the stages are genuinely different jobs, or when you need to check the work partway through.

Few-shot is the other near neighbor. If the model's problem is that it keeps producing the wrong shape, adding examples usually fixes it more cheaply than adding a step. Chaining and few-shot are not rivals, though: the best version of Step 1 above might carry two examples of a well-extracted decision. Reach for examples when the failure is format or category, and reach for a new link in the chain when the failure is that one prompt is doing too much.

## Where chains break

A chain trades one big failure for several small ones, and most of the small ones are quiet. Knowing the shapes in advance is the difference between a chain you trust and one that fails without telling you.

![Diagram showing a small error in step one of a prompt chain propagating and amplifying through later steps into a confidently wrong final output](/blog/prompt-chaining/error-compounding.svg)

| Failure mode | What it looks like | What to do |
|---|---|---|
| Error compounding | A small mistake in Step 1 is treated as fact by Steps 2 and 3 and amplifies. | Check the output of early steps, not just the final one. The first link matters most. |
| Context drift | Details get dropped or subtly reworded at each handoff, so the final output has drifted from the source. | Carry the original input forward where accuracy matters, not just the previous step's output. |
| First-prompt dependency | The whole chain's quality is capped by Step 1; a weak extraction cannot be rescued downstream. | Spend most of your effort on the first prompt. It is load-bearing. |
| Cost and latency multiplication | Three prompts is roughly three times the calls, tokens, and wait. | Only chain when the accuracy gain is worth the multiplier. A good single prompt beats a needless chain. |
| Silent staleness | A saved chain keeps running long after the task, format, or facts it assumed have changed. | Re-read the chain on a schedule. This one gets its own section. |

The first three are the ones people underestimate. Because each step looks reasonable in isolation, a chain can produce a polished final answer that is wrong for a reason buried two steps back. The habit that catches it is boring and effective: keep the intermediate outputs, and read the early ones first when something looks off. The same pressure shows up inside a single long context as [context rot](https://scribelet.app/blog/context-rot), where the model's accuracy slides as the window fills, so a shorter chain that keeps each step's input lean is easier to keep honest than one giant prompt. The [same discipline that keeps a note honest](https://scribelet.app/blog/ai-fact-checking-for-notes), checking the source rather than trusting the summary, is what keeps a chain honest.

## A saved chain is an artifact that rots

The first time a chain works, you save it, because rebuilding it every week is tedious. That is the right instinct and the start of the problem. A chain is a set of instructions, and instructions bake in the world as it was the day you wrote them.

The meeting-notes chain assumed a manager who wanted four sentences, a roadmap called Q3, and decisions that look a certain way. When the manager changes, or the quarter rolls, or the team starts recording decisions in a different format, the chain does not know. It keeps extracting, filtering, and writing exactly as instructed, producing output that is well-formatted and quietly wrong. Nothing errors. This is knowledge decay, the same rot that turns a good system prompt into scar tissue and a good runbook into a liability, sitting one level up in a workflow you stopped looking at.

The parts that go stale fastest are the ones tied to something that changes on its own schedule:

- **A baked fact.** A step that says "our pricing is X" or "the API returns Y" carries an expiry date in a place with no expiry field.
- **A named target.** "Write for my manager Dana" is wrong the week the org chart moves, and the chain cannot tell.
- **A model assumption.** A chain tuned around one model's quirks can misfire on the next one, and switching models freely is the whole point of being able to [bring your own provider](https://scribelet.app/blog/byok-ai).

When the context a chain leans on comes from your own notes, the fix is upstream: the notes have to stay true, or every workflow built on them inherits the error. That is the premise of an assistant that treats your knowledge as something to maintain rather than only store. Scribelet's [AI memory](https://scribelet.app/blog/ai-memory) exists so the facts your AI works from can be listed, checked, and corrected in one place, instead of frozen into a chain where they silently age. A chain, like [a generated prompt](https://scribelet.app/blog/meta-prompting), is only trustworthy on the day you last read it.

## Chain when the task earns it

Prompt chaining is the most useful prompt technique you can learn in an afternoon, and the case for it is plain: a model does one thing well and four things poorly, so give it one thing at a time. Break the task where the jobs are genuinely different. Keep the intermediate outputs so you can see which link failed. Spend your effort on the first prompt, because everything downstream inherits it.

And treat a chain you save the way you would treat any note you rely on: as something that was true when you wrote it and needs a look before you trust it again. The point of chaining is not to build a machine you never touch. It's to break a hard task into pieces small enough to check, and then to keep checking them. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what it looks like when an AI has to show its work at every step, not just hand you a confident final answer.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>prompt-engineering</category>
            <category>prompt-chaining</category>
            <category>ai</category>
            <category>llm</category>
            <category>system-prompt</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Spec-driven development: write the spec your agent follows]]></title>
            <link>https://scribelet.app/blog/spec-driven-development</link>
            <guid isPermaLink="false">https://scribelet.app/blog/spec-driven-development</guid>
            <pubDate>Thu, 13 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What spec-driven development is, a spec template you can copy, when to use it vs TDD or vibe coding, and why a spec quietly drifts from the code. Try it free.]]></description>
            <content:encoded><![CDATA[
Here is a way to build a feature with an AI coding agent that almost works. You open the chat and type: "Add a way for users to export their data as CSV, with a button in settings, and make sure it handles large accounts." The agent thinks for a while and produces four hundred lines across six files. Some of it is right. The button is in the wrong place, "large accounts" turned into an arbitrary 10,000-row cap you never asked for, and the CSV escaping breaks on the first name with a comma in it. You did not ask for any of that. You also did not say not to.

The problem is not the model. The problem is that you handed a paragraph to something that will happily fill every gap you left with a guess. A paragraph has a lot of gaps. The fix is the oldest idea in software, arriving in a new place: write down what you actually want before anything gets built, in enough detail that the gaps are closed.

That's spec-driven development, one discipline inside the broader practice of [agentic coding](https://scribelet.app/blog/agentic-coding), and it's the fastest-growing answer to a problem AI coding created. This piece covers what spec-driven development is, a spec you can copy and adapt today, when to reach for it instead of just prompting or writing tests first, where the approach breaks, and why the spec you write this week is quietly wrong by next month if you never look at it again.

## What is spec-driven development?

Spec-driven development (SDD) is a workflow where you write a structured, human-readable specification of what to build, review and agree on it, and then have an AI coding agent implement against it, rather than prompting the agent directly and correcting it after the fact. The spec is the source of truth. The code is derived from it.

![Diagram contrasting vibe coding, where a short prompt produces code directly, against spec-driven development, where the idea becomes a reviewed spec that the agent implements and validates against](/blog/spec-driven-development/spec-vs-vibe.svg)

The shape is consistent across the people defining it. Martin Fowler's team describes SDD as writing a well-considered spec first, then using it in the AI-assisted workflow as the durable artifact the code answers to. GitHub, which shipped an open-source toolkit called [Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) for exactly this, frames the loop as capturing intent in a spec, planning from it, then generating code inside those constraints. IBM's write-up on [spec-driven development](https://www.ibm.com/think/topics/spec-driven-development) puts it plainly: a detailed specification is authored and agreed upon before implementation begins.

What all of them are reacting to is "vibe coding," the prompt-and-pray style where you describe a feature in a sentence and accept whatever comes back. Vibe coding is fine for a throwaway script. It falls apart the moment the thing has to be correct, because the model is filling your gaps with statistically plausible choices, not the choices you would have made. A spec is how you make those choices yourself, up front, once, instead of catching them in review one wrong guess at a time.

If you have ever written a [software design document](https://scribelet.app/blog/software-design-document) or a [technical spec](https://scribelet.app/blog/technical-spec), you already know most of this. The document is the same idea. What changed is the reader. It used to be a teammate who would ask you questions when something was unclear. Now it is an agent that will not ask. It will guess, and it will guess confidently, so the spec has to close the gaps a human colleague would have flagged.

## A spec you can copy

The technique is easier to show than to argue about. Here is a spec skeleton for the CSV export from the opening. It's deliberately short. A spec is not a novel; it's the set of decisions you don't want the agent making for you.

```text
# Feature: CSV export of user data

## Goal
Let a signed-in user download all their own records as a CSV file.

## User-facing behavior
- A "Export CSV" button on the Settings > Data page, under "Your data".
- Clicking it downloads a file named `export-<YYYY-MM-DD>.csv` immediately.
- No email, no background job, no "we'll send you a link".

## Scope
- Export ONLY the current user's own rows. Never another user's data.
- Include these columns, in this order: id, title, created_at, status.
- Exclude soft-deleted rows (deleted_at is not null).

## Rules and edge cases
- Escape any field containing a comma, quote, or newline per RFC 4180.
- created_at in ISO 8601 UTC.
- An account with zero rows downloads a header-only file, not an error.
- Do NOT add a row limit. Stream the response if the result is large.

## Out of scope
- No XLSX, no PDF, no column picker. CSV only, all columns, this release.

## Done when
- A user with 0, 1, and 50,000 rows all get a correct file.
- A title containing `a,"b"` round-trips correctly through a spreadsheet.
```

Read what that buys you. Every wrong guess from the opening is now a line the agent cannot get wrong: the button's location, the "large accounts" behavior, the escaping rule, the filename. The "Out of scope" section is doing as much work as the rest, because it stops the agent from helpfully building three formats you did not ask for. The "Done when" section gives it something to check its own work against, which is the part vibe coding never has.

You hand that spec to the agent as the task. The agent implements it. Then you check the result against the spec, not against a vague memory of what you wanted, because the spec wrote the memory down. When something is wrong, you fix the spec first and regenerate, so the spec stays the source of truth instead of drifting behind the code on day one.

You do not need a framework to start. A spec is a markdown file and some discipline. Tools like Spec Kit or Kiro add structure, templates, and a repeatable command loop when you are doing this every day, but the technique underneath is exactly what you just read: decide, write it down, then build.

## When to reach for a spec, and when not to

Spec-driven development is not free. Writing the spec is real work, and for a small enough task it is slower than just asking. The skill is knowing which shape fits the job. This is also the question the search results dance around, because the useful answer is a comparison, not a definition.

| Situation | Reach for | Why |
|---|---|---|
| A throwaway script or a one-line change | A single prompt | Writing a spec costs more than the fix. Just ask. |
| A feature with real behavior, edge cases, or "don't do X" rules | Spec-driven development | The spec closes the gaps the agent would otherwise guess. |
| You care most about verified behavior, not structure | Test-driven development | Write the failing tests first; the tests are the spec. Pairs well with SDD. |
| A cross-team product decision about what to build | A PRD or design doc | The audience is people, and the questions are product, not implementation. |
| A recurring instruction for every task in a repo | The [system prompt](https://scribelet.app/blog/system-prompt) or an agent rules file | Durable, cross-cutting rules belong above the task, not in each spec. |

The pairing worth noticing is spec-driven and test-driven development, which people treat as rivals and are not. A spec says what to build in prose; tests say what "correct" means in code. The "Done when" section of the spec above is a test suite waiting to be written. The strongest version of this workflow writes the spec, turns the "Done when" bullets into failing tests, and lets the agent code until the tests pass against the spec. SDD sets the intent; TDD verifies it.

The other honest boundary is the design doc. A software design document answers "should we build this, and how does it fit the system," for an audience of humans who will push back. A spec answers "build exactly this," for an agent that will not. The same project often has both: the design doc decides the shape, the spec hands the agent the details. Do not collapse them into one document that serves neither reader well.

## Where spec-driven development breaks

A spec trades the risk of a wrong guess for a set of quieter risks, and the quiet ones are the ones that cost you later. Knowing them in advance is the difference between a spec that helps and a spec that lies to you.

![Diagram showing a spec frozen at the moment it was written while the code around it keeps changing, the gap between them widening into spec drift](/blog/spec-driven-development/spec-drift.svg)

| Failure mode | What it looks like | What to do |
|---|---|---|
| Over-speccing | You spend an hour specifying a ten-minute change, or dictate implementation details the agent should own. | Spec the decisions and constraints, not the code. If a line does not close a gap, cut it. |
| Under-speccing | The spec reads clean but leaves the same gaps as a prompt, so the agent still guesses. | Write the edge cases and the out-of-scope list. Those are where guesses hide. |
| Spec drift | The code changes in review or later PRs, the spec does not, and the two quietly diverge. | Fix the spec first and regenerate, or delete it when it stops being true. A stale spec is worse than none. |
| Trusting a passing agent | The agent says it matched the spec; it matched its reading of the spec. | Verify against the spec yourself, especially the "Done when" cases. The spec is the check, not the agent. |
| Baked-in facts | The spec hardcodes an API shape, a limit, or a dependency that changes on its own schedule. | Reference the source of that fact instead of copying it, and re-read specs that name external systems. |

The first two are about writing the spec well, and they trade off against each other: over-spec and it is slower than prompting, under-spec and it is prompting with extra steps. The line is the gap. A good spec line closes a decision the agent would otherwise make wrong. A wasted line describes something obvious or something the agent should decide on its own.

The last three are the ones that outlive the pull request, and they share a cause. A spec is a document, and documents freeze the world as it was the day you wrote them. The [same discipline that keeps a note honest](https://scribelet.app/blog/ai-fact-checking-for-notes), checking the source instead of trusting the copy, is what keeps a spec honest past its first use.

## A spec is an artifact that rots

Here is the part almost nobody writing about spec-driven development mentions. The first time a spec works, you keep it. You put it in the repo next to the code, because it explains the feature and you might need it again. That's the right instinct and the start of a slow problem.

The moment the code changes and the spec does not, the spec starts lying. Someone tweaks the export to include a fifth column in a later PR, the "columns, in this order" line still says four, and now the most authoritative-looking document about that feature is wrong. The next person to read it, or the next agent asked to modify the feature "according to the spec," inherits the error. Nothing broke. Nothing warned anyone. The spec just aged out of agreement with reality while sitting still, which is exactly how [outdated documentation](https://scribelet.app/blog/outdated-documentation) happens one file at a time.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and a spec is unusually exposed to it because it is precise. A vague doc is hard to falsify. A spec that says "these four columns, in this order" is trivially falsifiable and therefore trivially wrong the day a fifth column ships. The precision that makes a spec useful to an agent is the same precision that makes it stale fast. The parts that rot first are the ones tied to something with its own clock:

- **A hardcoded external fact.** "The payments API returns `status: paid`" carries an expiry date the day that API changes, and the spec has no expiry field.
- **A reference to code that moved.** A spec that names files, functions, or limits is wrong the refactor after it was written.
- **An out-of-scope line that quietly became in scope.** "No XLSX this release" is true for exactly one release.

A spec you regenerate from and then update is a living artifact. A spec you write once and leave in the repo is a trap with good formatting. The workflow only pays off if the spec stays true, which means someone, or something, has to notice when it stops being true. That is the premise Scribelet is built on: your notes, docs, and the facts your AI works from are things to maintain, not just store. When the reference material an agent leans on lives somewhere that can flag its own staleness, a drifting spec gets caught instead of quietly shipping the wrong column. A spec, like [the memory an AI keeps](https://scribelet.app/blog/ai-memory), is only trustworthy on the day you last checked it.

## Write the spec, then keep it honest

Spec-driven development is the correction AI coding needed. A model will fill every gap you leave with a confident guess, so leave fewer gaps: decide the behavior, the edge cases, and the out-of-scope list before anything gets built, and hand the agent a spec instead of a paragraph. Keep it short enough to be worth writing and specific enough to close the guesses.

Then treat the spec the way you would treat any note you rely on: as something that was true when you wrote it and needs a look before you trust it again. The point of a spec is not a document you file and forget. It is a decision you made on purpose, written down so an agent cannot undo it, and worth keeping true for as long as the feature lives. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what it looks like when the source of truth is something that tells you when it has gone stale, instead of aging in silence.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>spec-driven-development</category>
            <category>ai</category>
            <category>software-development</category>
            <category>documentation</category>
            <category>technical-spec</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Few-shot prompting: when examples help and when they hurt]]></title>
            <link>https://scribelet.app/blog/few-shot-prompting</link>
            <guid isPermaLink="false">https://scribelet.app/blog/few-shot-prompting</guid>
            <pubDate>Wed, 12 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What few-shot prompting is, when to use zero-, one-, or few-shot, the failure modes nobody names, and why your examples decay. Template included. Try it free.]]></description>
            <content:encoded><![CDATA[
A team ships a few-shot prompt to sort support tickets: three examples labeled urgent, normal, and low. It works. Six weeks later the same prompt is calling half of everything urgent, and nobody changed a line.

What changed was the tickets. The three examples were written back when "urgent" meant a payment outage. The new tickets are feature requests and billing questions, and the model, still matching against three months-old examples, keeps forcing them into a shape that no longer fits.

That is few-shot prompting working exactly as designed and failing anyway. The examples did their job. They just encoded a world that moved.

This piece covers what few-shot prompting is, when to use no examples versus one versus a handful, a prompt you can copy, the failure modes the tutorials skip, and why the examples you paste today have an expiry date you will not see.

## What is few-shot prompting?

Few-shot prompting is a technique where you put a small number of examples, usually two to five, of the input you will give and the output you want directly inside the prompt, before the real request. The model reads the pattern in those examples and applies it to the new input, with no retraining.

The name comes from the paper that made the technique famous. When OpenAI introduced GPT-3 in 2020, the title was [Language Models are Few-Shot Learners](https://arxiv.org/abs/2005.14165): the finding was that a large enough model could learn a task from a few examples in the prompt, with no gradient updates and no fine-tuning. The mechanism has a name, in-context learning. The model's weights never change; it conditions its next answer on the examples sitting in front of it. IBM's write-up on [zero-shot versus few-shot prompting](https://www.ibm.com/think/topics/zero-shot-vs-few-shot-prompting) frames it the same way: the examples are guidance, not training.

That is the whole idea, and it is genuinely useful. An example is worth a paragraph of instructions. "Return the answer as JSON with keys name and role" is a rule the model might follow. One filled-in example of that JSON is a rule it can see.

The catch is that an example carries more than you meant to put in it. Its format, its wording, its order, and the mix of cases you happened to include are all instructions, whether you intended them or not.

## Zero-shot, one-shot, few-shot: which to reach for

The "shot" is just the count of examples. Zero-shot is no examples, only an instruction. One-shot is a single example. Few-shot is two or more. Each is the right tool in a different place, and reaching for the wrong one is the first mistake.

| Approach | Examples | Reach for it when | The risk |
|---|---|---|---|
| Zero-shot | None | The task is common and the format is simple. Modern models already know "summarize this" or "translate to French". | The model guesses the format, and the guess drifts between calls. |
| One-shot | One | You need a specific output shape and one example pins it: a layout, a tone, a particular JSON. | A single example reads as the answer, not a pattern. The model over-copies it. |
| Few-shot | Two to five | The task has edge cases, categories, or a judgment call one example cannot show. Classification, extraction with exceptions. | More examples, more tokens on every call, plus the ordering bias below. |
| Fine-tuning | Dozens to thousands | You run the same task at volume and the examples no longer fit in the prompt. | A trained model is a frozen artifact too, and a costlier one to change. |

![Diagram of the zero-shot, one-shot, few-shot spectrum and what each one trades off](/blog/few-shot-prompting/shot-spectrum.svg)

The honest default for most one-off work is zero-shot first. Try the instruction alone. Add examples only when the output is wrong in a way an example would fix, which is almost always a format or edge-case problem, not a knowledge problem. If the model does not know something, examples will not teach it. They will only make it guess more confidently, which is the opposite of what you want when the thing you are prompting has to be [checked against a source](https://scribelet.app/blog/ai-fact-checking-for-notes) afterward. And when the failure is not a missing example but a single prompt trying to do too much at once, the fix is not more examples; it is [breaking the task into a chain of smaller prompts](https://scribelet.app/blog/prompt-chaining), each doing one job.

## A few-shot prompt that works

Here is a few-shot prompt for a real task: turning a messy meeting note into structured action items. The shape matters more than the words.

```markdown
Extract action items from meeting notes. For each, return the owner,
the task, and a due date if one is stated. If no owner is named, use "unassigned".

Input: Sarah will send the vendor contract by Friday. We still need
someone to review the Q3 numbers.
Output:
- owner: Sarah | task: send the vendor contract | due: Friday
- owner: unassigned | task: review the Q3 numbers | due: none

Input: Mike is going to update the runbook after the migration.
Let's revisit pricing next week.
Output:
- owner: Mike | task: update the runbook | due: after the migration
- owner: unassigned | task: revisit pricing | due: next week

Input: {your meeting note here}
Output:
```

Three things make this work, and each is a lever:

- **Consistent structure.** Every example uses the same labels (owner, task, due) in the same order. Models copy structure faster than content, so a wobble in your examples becomes a wobble in the output.
- **An edge case on purpose.** The "unassigned" and "none" cases appear in the examples, so the model has seen what to do when a field is missing. An example set that only shows the happy path teaches the model to invent a value rather than leave it blank.
- **The pattern is the point.** Two examples, not eight. Once the shape is unambiguous, more examples add token cost and the ordering bias below, not accuracy.

If you use an assistant that keeps a [system prompt](https://scribelet.app/blog/system-prompt) or custom instructions, this is exactly the kind of thing that should not live there permanently. A worked example is paid for on every request and relevant to few of them, which is why long examples belong in the request that needs them, not in the standing brief.

## How few-shot prompting quietly breaks

The tutorials stop at "use consistent formatting". The failures that actually cost you are more specific, and most stay hidden because the output reads fluently while it goes wrong.

| Failure mode | What you see | What caused it |
|---|---|---|
| Recency bias | The model favors the label or format of your last example | Models weight the most recent example most heavily. Put the most typical case last, not an edge case. |
| Majority-label bias | With three "urgent" examples and one "normal", everything trends urgent | The label mix in your examples leaks into the output. Balance the classes, or the model learns your ratio instead of the task. |
| Format lock-in | A new input that does not fit the example shape gets forced into it anyway | The examples taught a rigid template, and the model bends the input rather than break the pattern. |
| Example leakage | Names or values from your examples show up in answers about unrelated inputs | The model treats example content as context, not just as a pattern. Use obviously generic, fake values. |
| Domain overfitting | Great on inputs like your examples, poor on everything else | Your examples all came from one domain, so the model narrowed to it. Cover the range you actually expect. |
| Stale examples | Output was right for months, then slowly went wrong with no code change | The examples encode a format, taxonomy, or tone that has since moved. See below. |

The first two have a name in the research. The paper [Calibrate Before Use](https://arxiv.org/abs/2102.09690) showed that few-shot accuracy swings widely based on the order of the examples, the specific examples chosen, and the label distribution, and that the model leans toward answers it saw recently and often. The practical version is short: your examples are not neutral. Their order and their balance are instructions you did not know you were writing.

## Your examples have a shelf life

The last row of that table is the one nobody plans for, and it is the one worth dwelling on.

An example is a snapshot. When you paste two support tickets labeled by your 2025 taxonomy, or a meeting note formatted the way your team wrote them last quarter, you are freezing a moment. The prompt keeps steering toward that moment long after the world it captured has changed.

The classifier from the opening did not break because the model got worse. It broke because "urgent" drifted while the three examples still defined it the old way. The output stayed confident the whole time, which is exactly why it took six weeks to notice.

![Loop diagram: an example pins a format, the real format drifts, the model keeps matching the stale example, and the output stays confidently wrong](/blog/few-shot-prompting/example-shelf-life.svg)

This is the same failure that turns a good [system prompt into scar tissue](https://scribelet.app/blog/system-prompt) and a good runbook into a liability. It is [knowledge decay](https://scribelet.app/blog/knowledge-decay), one layer down: the examples are notes, the model reads them on every call, and nothing ever renders them visibly wrong.

The examples that rot fastest are the ones tied to something that changes on its own schedule:

- **A taxonomy.** Category labels, priority levels, tag names. When the set changes, every example using the old set is teaching the wrong map.
- **A format.** A JSON schema, a date convention, a field that got renamed. The examples keep producing the old shape.
- **A fact.** An example modeling "our current plan is X" bakes a fact with an expiry into a place that has no expiry field.

If the examples you feed a model come from your own notes, the fix is upstream: the notes have to stay true. That is the premise of an assistant that treats your knowledge as something to maintain rather than just store. Scribelet's [AI memory](https://scribelet.app/blog/ai-memory) and background verification exist so the material your AI works from can be listed, checked, and corrected in one place, instead of copied into a prompt where it silently ages.

## When to stop adding examples

There is a point where the answer is not another example. Few-shot has a ceiling, and pushing past it spends tokens for worse results.

Stop adding examples when:

- **You are past five or six and still not happy.** The gain from each example flattens fast. If six have not fixed it, the problem is the instruction or the task, not the count. When it is the instruction, [having the model draft the prompt for you](https://scribelet.app/blog/meta-prompting) beats reaching for a seventh example.
- **The examples no longer fit the context window.** Long few-shot prompts get expensive on every call, and the earliest examples start getting ignored anyway. If you need dozens, you have outgrown the technique.
- **The task needs knowledge, not a pattern.** Examples show the model how to answer, not what is true. For facts, reach for retrieval, not more examples.

At volume, the honest next step is fine-tuning: train the pattern into the model so it does not cost prompt space on every call. But note the trade. A fine-tuned model is a frozen artifact, and a costlier one to change than a prompt. The examples that rot in a few-shot prompt at least sit in a text file you can read; the same drift baked into fine-tuning weights is invisible and costs a training run to fix. When you [choose your own provider and model](https://scribelet.app/blog/byok-ai), that trade is at least yours to make on purpose.

## Examples are an artifact, not a setting

Few-shot prompting gets treated as a trick: paste a couple of examples, get better output, move on. It works well enough often enough that the examples turn permanent the day they are added, and then they sit there, defining a task by a handful of cases from one particular week.

They deserve the same care as anything else the machine reads on every request. Keep them few. Keep them balanced. Keep them in version control, so a change is a diff and not a mystery. And re-read them on a schedule, because the examples that were perfect in March are quietly teaching your model the wrong lesson by September, and the output will never tell you.

If the examples your AI learns from come from your own notes, they should be as inspectable and as maintainable as anything else you write down. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what it looks like when an AI has to show what it knows and where it learned it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>prompt-engineering</category>
            <category>few-shot-prompting</category>
            <category>ai</category>
            <category>llm</category>
            <category>system-prompt</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[AI memory: what to store, what to expire, what to check]]></title>
            <link>https://scribelet.app/blog/ai-memory</link>
            <guid isPermaLink="false">https://scribelet.app/blog/ai-memory</guid>
            <pubDate>Tue, 11 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[AI memory is easy to write and hard to correct. The four types with their failure modes, what to store and never store, and a five-step memory audit. Try it free.]]></description>
            <content:encoded><![CDATA[
Your assistant knows you moved teams in March. It knows because you mentioned it once, in a conversation you have long forgotten. It does not know that the team was folded into another one in June, because nothing in the system is designed to be told that a fact stopped being true.

So it keeps helping. It drafts your update with the old team name in it. It suggests people who are no longer on the project. Every answer is fluent, confident, and quietly wrong in the same small way, and none of it looks like an error because errors announce themselves and stale facts do not.

That is the actual state of AI memory in 2026. Writing to it is nearly free. Correcting it is a manual job nobody has been assigned. This piece covers the four types of memory, what belongs in each one, how long each kind of fact stays true, and how to audit what a system already believes about you.

## What is AI memory?

AI memory is a system's ability to carry information across sessions, so a model can use what it learned about you last week without you pasting it in again. It is what separates an assistant that knows your stack from one that meets you fresh every morning.

The context window is not memory. The context window is the desk: everything currently spread out in front of the model, available all at once and gone when the session ends. And the more that piles onto the desk, the less reliably the model reads any one thing on it, a slide known as [context rot](https://scribelet.app/blog/context-rot). Memory is what somebody wrote down before clearing the desk. IBM's overview of [AI agent memory](https://www.ibm.com/think/topics/ai-agent-memory) frames it the same way, as the ability to store and recall past experience rather than to hold a large amount of text at once.

One disambiguation, because the phrase now points at two different industries. If you came here about the other AI memory, the DRAM and high-bandwidth memory shortage pushing up hardware prices, [J. P. Morgan's research on the AI-driven memory shortage](https://www.jpmorgan.com/insights/global-research/artificial-intelligence/dram-memory-shortage-from-ai) is the better read. This piece is about the software kind: what an AI remembers about you.

![Diagram comparing the context window, which is cleared at the end of a session, with persisted AI memory that survives it](/blog/ai-memory/session-boundary.svg)

If you want to see the mechanics in a working system rather than in the abstract, Scribelet's [AI memory](https://scribelet.app/learn/ai/ai-memory) documentation walks through how facts get extracted, stored, and retrieved per workspace.

## The four types of AI memory

Almost every explanation of AI memory lists the types. Very few say what each type gets wrong, which is the part you need before you decide what to trust it with.

| Type | What it holds | Where it lives | What it gets wrong |
|---|---|---|---|
| **Working memory** | The current conversation, the files you just opened, the task in progress | The context window | Falls off the end. Nothing survives the session unless something else writes it down, and the model cannot tell you what it forgot |
| **Semantic memory** | Standalone facts: your role, your stack, your terminology, your preferences | Database rows or a vector store | Records facts without any notion of expiry, so a fact from March outranks nothing and is retrieved with full confidence in December |
| **Episodic memory** | What happened and when: a conversation, a decision, a session summary | Timestamped summaries | Accumulates faster than it is pruned. Ten summaries of the same recurring meeting are noise, not history |
| **Procedural memory** | Rules and standing instructions: how you want things formatted, what to never do | System prompts, rule files, instruction documents | The hardest to inspect and the most likely to silently override a request you made just now |

The two failure modes worth internalising are in the middle rows. Semantic memory has no clock, and episodic memory has no editor. Both problems compound in the same direction: the store grows, the average fact gets older, and nothing in the retrieval path knows the difference between a fact that is true and a fact that was true.

This is the same shape as [knowledge decay](https://scribelet.app/blog/knowledge-decay) in a notes system, which is not a coincidence. A memory store is a notes system with no reader. At least when your own notes go stale, you eventually open one and wince. Nobody reads their AI's memory store for pleasure. The same blind spot covers [few-shot examples that live in the prompt](https://scribelet.app/blog/few-shot-prompting) rather than in memory: they steer every answer from the context window and go stale with nobody reading them back.

## Memory is write-heavy and has no retraction step

Look at how the writing and the un-writing compare in any current memory system.

Writing is automatic. You say something in passing, an extraction step decides it is a durable fact, and it is stored. Mem0's [guide to memory in agents](https://mem0.ai/blog/memory-in-agents-what-why-and-how) describes this loop well: the value of the pattern is precisely that the user does not have to curate anything.

Retraction is manual, and usually undiscoverable. There's rarely a screen that lists what the system believes. When there is one, it lists facts without sources, so you can't tell whether "prefers Postgres" came from a considered decision or from you losing an argument on a Tuesday.

The asymmetry produces a specific outcome: memory quality degrades even when every individual write was correct at the time. Nothing was wrong when it was written. It just kept being retrieved afterwards.

There is a useful piece of evidence for how much this matters. In a benchmark posted to r/AI_Agents, one developer [ran eight agent memory systems through 2,176 tasks](https://www.reddit.com/r/AI_Agents/comments/1veeix3/i_ran_8_ai_agent_memory_systems_through_2176/) and reported that a plain markdown wiki beat every product in the comparison. Treat any single benchmark carefully, but the direction is worth sitting with: the setup that won was the one a human could open, read, and correct. Legibility beat sophistication.

That result rhymes with what happens to a [compiled LLM wiki](https://scribelet.app/blog/llm-wiki) when its sources move on. Everyone builds the compile step. Almost nobody builds the recompile.

## What to store, and what to never store

Most memory systems will store anything you say. That is a capability, not a policy. Here is the policy, organised by how long the fact stays true.

| What it is | Example | Shelf life | Store it? |
|---|---|---|---|
| Stable identity | Timezone, name, working language | Years | Yes. This is what memory is for |
| Terminology | What your team means by "desk", "run", "cell" | Years, until a rename | Yes, and it pays for itself on every retrieval |
| Role and team | "Works on the payments team" | 6 to 18 months | Yes, with the date attached |
| Standing preferences | "Prefers short answers, no preamble" | Months, until you change your mind | Yes, and make it easy to override in the moment |
| Project state | "Migration is blocked on the vendor" | Days to weeks | Only with a review trigger. This is the category that ages worst |
| Numbers from a source | "The API rate limit is 100 requests a minute" | Until the source changes, which nobody tells you | Store the source, not the number |
| Other people's details | A colleague's personal circumstances | Not yours to decide | Almost never. Store what the work needs, not what you happened to hear |
| Secrets | API keys, passwords, tokens | Never | Never. A memory store is a retrieval surface, and anything in it can come back out in an answer |

The row that catches the most people is the numbers row. A remembered figure is a snapshot with the timestamp filed off. Six months later the model quotes it back with the same confidence it had on day one, and the only signal that something changed is the thing you were trying to avoid: finding out the hard way. Storing the source instead means the fact can be re-checked. That is what [AI fact-checking against live sources](https://scribelet.app/blog/ai-fact-checking-for-notes) is for.

## How to audit what an AI remembers about you

Run this quarterly, and after any change big enough to invalidate a category above. It takes about twenty minutes.

![Diagram of the memory audit loop: list, sort by age, find contradictions, correct the source, re-check](/blog/ai-memory/audit-loop.svg)

1. **List it.** Open the memory store and read every entry. If your tool can't produce that list, you have already found the most important thing about it. A store you cannot enumerate is a store you cannot correct.
2. **Sort by age.** Anything older than its shelf life from the table above is a suspect, not yet a defect. You are looking for facts that outlived the situation that produced them.
3. **Look for contradictions, not just errors.** Two entries that cannot both be true are far easier to spot than one entry that is quietly wrong, and they are the strongest signal available that something changed and the store missed it. Scribelet surfaces these through [knowledge health](https://scribelet.app/learn/ai/knowledge-health), which flags memories that conflict with each other instead of waiting for you to notice.
4. **Correct the source, not just the memory.** This is the step everyone skips. If a stale memory came from a note that still says the old thing, deleting the memory accomplishes nothing: the next extraction pass reads the same note and writes the same fact back. Fix the note, then fix the memory. Deleting alone is a loop.
5. **Re-check after a change.** New job, new team, finished project, deprecated tool. These are the moments when a memory store goes from mostly right to confidently misleading, and they're predictable enough to put on a calendar.

Nothing in this list requires a specific product. It requires that the store be readable and editable, which is the whole of the argument.

## Agent memory vs personal AI memory

The phrase covers two jobs that pull in different directions, and the distinction decides which failure you should care about.

**Agent memory** exists so a task can finish. An agent working through a long job needs to recall what it already tried, what failed, and what it decided three steps ago. Success is measured over the life of the task, and after that the memory is mostly disposable. Getting it wrong wastes tokens and repeats work.

**Personal AI memory** exists so knowledge stays true across months. Success is measured in whether the thing it tells you in December is still accurate. Getting it wrong means acting on something that stopped being the case, and never finding out which fact did it.

They need opposite defaults. Agent memory should forget aggressively once the task closes. Personal memory should keep facts but attach a review trigger to the ones that rot. Most tools ship one implementation and use it for both, which is why personal memory stores get cluttered with task residue and agents keep re-learning your preferences.

## How Scribelet handles AI memory

Scribelet builds memory per desk, so the terminology and people from your work desk never leak into your personal one. Facts are extracted from notes and conversations, categorised (person, project, term, preference), and linked into a knowledge graph, so asking about a project can surface the people and dependencies attached to it rather than only the words you searched for.

The parts that matter for everything above: memories are listable and editable rather than a hidden store, conflicting facts are surfaced by knowledge health instead of waiting to be discovered, and consolidation merges redundant entries so an episodic log does not become the noise described earlier. Memories are encrypted at rest with per-desk keys, and if you would rather the extraction run through a provider you chose, [bring your own key](https://scribelet.app/learn/ai/byok) for OpenAI, Anthropic, or Google.

The honest limitation: none of this decides for you which project facts have expired. It tells you where two beliefs disagree and makes the store easy to read. You still make the call, which is the same trade-off as any [AI second brain worth trusting](https://scribelet.app/blog/ai-second-brain-setup).

Worth saying plainly: a memory store that can't be read is a memory store you're trusting on faith.

## The part nobody builds

Every memory system on the market has a good answer for how it remembers. Ask what happens when a stored fact stops being true and the answers get vague, because the industry has been optimising the write path for two years and the correction path for almost none of it.

Until that changes, the practical position is the boring one. Store the durable things. Store sources rather than figures. Keep the store small enough that a human can read it, and read it on a schedule. An assistant that knows four true things about you is worth more than one that knows forty things, six of which expired in the spring.

Want a memory you can actually inspect? [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what your notes look like when the AI has to show its working.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>ai-memory</category>
            <category>ai</category>
            <category>knowledge-management</category>
            <category>knowledge-decay</category>
            <category>note-taking</category>
            <category>llm</category>
        </item>
        <item>
            <title><![CDATA[Pull request template: the fields nobody fills in]]></title>
            <link>https://scribelet.app/blog/pull-request-template</link>
            <guid isPermaLink="false">https://scribelet.app/blog/pull-request-template</guid>
            <pubDate>Tue, 11 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A pull request template that asks for what the diff already shows gets filled with N/A. A short default, three variants by change type, and the fields to delete.]]></description>
            <content:encoded><![CDATA[
Here is a pull request description from a real repository. The template was added six months ago by someone who cared.

```markdown
## Description
N/A

## Type of Change
- [x] Bug fix

## Screenshots
N/A

## Checklist
- [x] I have performed a self-review of my code
- [x] New and existing unit tests pass locally
```

Nothing here is wrong, exactly. Every box is ticked. The author complied. And the reviewer learned nothing they could not have learned from the diff in four seconds. When a review has nothing substantive to engage, the comments drift to the one thing everyone can judge, the formatting, which is [Sayre's law](/blog/sayres-law) playing out inside a diff: the trivial gets the attention the logic deserved.

This is the normal outcome. A team notices reviews are slow, adds a pull request template copied from a blog post, and six months later the template is a formality that everyone completes and nobody reads. The usual diagnosis is that people are lazy. The actual cause is in the template: it asks the author for information the reviewer already has.

## What is a pull request template?

A pull request template is [a markdown file in your repository](https://scribelet.app/blog/docs-as-code) that pre-fills the description box whenever someone opens a new pull request. On GitHub it lives at `.github/pull_request_template.md`. The platform reads it, drops its contents into the empty description field, and the author writes over the prompts. The same `.github/` directory holds [issue templates](https://scribelet.app/blog/github-issue-template), the intake-side sibling that shapes bug reports the way this one shapes pull requests. A level up sits [the repository's README](https://scribelet.app/blog/how-to-write-a-readme), the front page a reviewer reads before either template.

That is the whole mechanism. It is a default value for a text box, and the platform vendors document it well: [GitHub's own guide](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) covers the setup in about four steps, as does [Microsoft's for Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/pull-request-templates).

What none of them tell you is what to put in it. That question is not a formatting question, and it is the one that decides whether the template survives contact with a busy Tuesday.

## Why pull request templates fill up with N/A

A pull request arrives carrying two kinds of information. The first kind is already in the diff, and the reviewer can see it without being told. The second kind exists only in the author's head, and if they do not write it down it is gone.

Most templates ask almost entirely for the first kind.

| The reviewer can already see this | Only the author knows this |
|---|---|
| Which files changed | Which approach was tried first and abandoned |
| That it is a bug fix, from the one-line change | Whether the bug had a second cause that is still there |
| That tests were added, from the test file | Which case the tests deliberately do not cover |
| The new endpoint's shape | Why it is a new endpoint instead of a parameter |
| That a migration file exists | Whether the migration is safe to run while traffic is live |

![What a reviewer reads from the diff versus what only the pull request author knows](/blog/pull-request-template/what-the-diff-shows.svg)

Read the left column again. "Type of Change: Bug fix" is on it. So is "Screenshots" for a backend service that has no user interface. So is most of the standard checklist.

There is a second source of N/A, and it's worse because it looks responsible: checklist items that duplicate continuous integration. Tests pass locally. Lint passes. No debug statements left in.

If a machine can check it, a machine should. Asking a human to promise it produces exactly one outcome, which is that the human ticks the box without looking. That isn't a safety net. It's a ritual that trains people to tick boxes without reading them, which is a strange thing to teach anyone who also reviews code.

The third source is scope. Most templates are written for the worst pull request the team has ever received, so a one-line copy fix inherits a form designed for a database migration. The author looks at eight prompts, four of which are irrelevant, and reasonably concludes that the whole thing is decoration.

[Start writing in Scribelet](https://scribelet.app) if you want somewhere to keep the reasoning that does not fit in a diff. More on that at the end.

## A pull request template you can copy

Here is a default that is deliberately shorter than the one you will find in most guides. Every prompt asks for something the diff cannot answer.

```markdown
## What and why

One or two sentences. What changes, and what problem that solves.
Link the issue if there is one.

## Approach

What you chose, and what you rejected. Skip if the change is obvious.

## Risk

What breaks if this is wrong, and how you would know.
Write "low, reversible" when that is true. It usually is.

## Testing

What you actually ran. Not what CI runs.
Call out anything you could not test.
```

Four prompts. Roughly forty seconds of work for a small change and five minutes for a serious one, which is the correct ratio.

The reasoning behind each one:

- **What and why** exists because six months from now this description is the only record of intent that will still be attached to the code. `git blame` finds the pull request, and the pull request should say something.
- **Approach** is the field that pays for the template on its own. "I tried a database constraint first, it deadlocked under the importer's write pattern, so this validates in the service layer" turns a reviewer's objection into a conversation that has already happened.
- **Risk** is there because authors underestimate it silently and reviewers cannot see the absence of a concern. Writing "low, reversible" costs nothing and is genuinely informative when it is wrong.
- **Testing** asks what you ran, not whether tests exist. The test file already answers the second question.

Notice what is missing: no type-of-change checkboxes, no screenshots section, no checklist repeating CI. Those are in the section on what to delete, further down.

Google's [code review guide](https://google.github.io/eng-practices/review/reviewer/looking-for.html) makes the same point from the reviewer's side. What a reviewer is asked to judge is design, complexity, and whether the change makes the system better overall. None of that is visible in a checkbox.

## Three pull request templates instead of one

The reason a single template fails is that a typo fix and a schema migration are not the same event, and no set of prompts serves both. Both GitHub and GitLab support multiple templates, and almost nobody uses the feature.

Put several files in `.github/PULL_REQUEST_TEMPLATE/` instead of one at the root, then select one by adding `?template=migration.md` to the pull request URL. Most teams link the two or three they use from their contributing guide.

![A single pull request template applied to every change, versus three templates chosen by change type](/blog/pull-request-template/one-template-vs-three.svg)

**Bug fix.** The default above, minus Approach. Add one prompt that matters more than anything else in a fix:

```markdown
## Root cause

What was actually wrong. Not the symptom.

## Why it was not caught

Test gap, monitoring gap, or a case nobody considered.
```

That second prompt is the one that turns a fix into a lesson. It also produces, at no extra cost, the raw material for the incident write-ups and the [runbooks](https://scribelet.app/blog/runbook) somebody will otherwise reconstruct from memory a week later.

**Feature.** The default, plus the pointer to the thinking that already happened:

```markdown
## Design

Link the design doc, spec, or ADR. If there is not one, say why not.
```

If the change is large enough to need that link, it was large enough to need [a design doc](https://scribelet.app/blog/software-design-document) or [a technical spec](https://scribelet.app/blog/technical-spec) before the code. When the answer to "why not" is "this got big halfway through", that is worth knowing during review rather than after.

**Migration or revert.** The one place a checklist earns its keep, because the items are genuinely not machine-checkable, the parts of your [definition of done](/blog/definition-of-done) a human still has to confirm:

```markdown
## Rollout

- [ ] Safe to run while traffic is live, or the downtime window is booked
- [ ] Backwards compatible with the currently deployed code
- [ ] Rollback tested, not assumed

## Blast radius

What data this touches and how much of it.
```

Every one of those requires a human to think. That is the test for whether a checkbox belongs in a pull request template at all.

## Where the pull request template file goes

The mechanics differ by platform in ways that are easy to get wrong, mostly around casing and directory names.

| Platform | Single template path | Multiple templates | How one is selected |
|---|---|---|---|
| GitHub | `.github/pull_request_template.md` | `.github/PULL_REQUEST_TEMPLATE/` directory | `?template=name.md` in the URL |
| GitLab | `.gitlab/merge_request_templates/Default.md` | Same directory, one file each | Dropdown in the merge request form |
| Bitbucket Cloud | Repository settings, not a file | Not supported | Applied to every pull request |
| Azure DevOps | `.azuredevops/pull_request_template.md` | `pull_request_template/` subdirectory | Branch-specific, or `?template=name` |

Two details that cost people an afternoon. On GitHub the single-file name is lowercase while the directory name is uppercase, and both work only in `.github/`, the repository root, or `docs/`. On Azure DevOps templates can be bound to a target branch, so a template can apply to pull requests into `main` and not into a feature branch.

## The fields to delete

If you already have a template and it is being ignored, this section is the whole intervention. Deleting is faster than rewriting and it works better.

- **Type of change checkboxes.** The diff says. In the rare case it does not, the title does.
- **Anything continuous integration already enforces.** Tests pass, lint passes, build succeeds, no debug statements. Let the machine assert it.
- **Screenshots, unless the repository has a user interface.** A required screenshots section on a backend service is where the N/A habit is born, and the habit spreads to the fields that matter.
- **"I have performed a self-review of my code."** Nobody has ever ticked this box honestly and then unticked it.
- **Long contribution reminders.** Link the contributing guide instead of pasting it into every pull request.
- **Emoji section headers**, if the team reads pull requests in a terminal or in email digests, where they render as boxes.

The rule underneath all six: **a prompt earns its place only if a thoughtful author could write something surprising in it.** If every honest answer is identical, the field is decoration, and decoration is what teaches people to stop reading the template.

## Your pull request template goes stale too

A template is a standing instruction. It gets written once, applied thousands of times, and reviewed almost never, which makes it one of the purest examples of [documentation that quietly stops being true](https://scribelet.app/blog/outdated-documentation).

The failures are specific and they all look like this:

- It asks for a QA sign-off from a QA team that was reorganised last year.
- It links a staging environment at a URL that now redirects to a login page.
- It requires a Jira ticket number, six months after the team moved to Linear.
- It asks contributors to update the wiki, and the wiki has been read-only since the migration.

None of these break anything. That is the problem. The pull request still opens, the box still gets ticked, and the instruction that no longer means anything is followed by a hundred people who assume somebody checked. This is the same failure mode as [internal documentation nobody owns](https://scribelet.app/blog/internal-documentation) and the reason an [architecture decision record](https://scribelet.app/blog/architecture-decision-record-examples) needs a supersession discipline rather than a review calendar.

Two things fix it, and neither is a quarterly review meeting.

**Give the template an owner and a last-verified date.** Put a comment at the top of the file recording when someone last confirmed every link and process reference in it still resolves. Last edited is not last verified. A template edited last month to add an emoji is not a template anyone has checked.

**Attach the check to a trigger, not a calendar.** The template needs re-reading when the ticket system changes, when the QA process changes, or when a linked environment moves. Those are the events that invalidate it, and they are far more reliable prompts than "the first Monday of the quarter".

This is the part Scribelet is built for. A pull request template, like a runbook or an ADR, is a set of claims about the world that were true on the day they were written. Scribelet's background agents check the claims in your notes against current sources on a schedule you set, and show you a diff of what changed and why, so a dead link or a renamed process surfaces as a flagged change rather than as an instruction a hundred people quietly ignore. It is the same argument we make about [knowledge decay](https://scribelet.app/blog/knowledge-decay) everywhere else, applied to the one document your team reads more often than any other.

[Try Scribelet free](https://scribelet.app) and keep the claims in your engineering docs under review.

## The short version

A pull request template works when it asks for what only the author knows and stays quiet about everything else.

1. Ask four things: what and why, approach, risk, testing.
2. Delete every prompt the diff already answers and every box continuous integration already enforces.
3. Use two or three templates by change type instead of one that fits nothing.
4. Give the file an owner and a last-verified date, because it decays like any other document.

If your current template is being filled with N/A, that is not a discipline problem on your team. It is feedback, and it is telling you which fields to cut.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>pull-request-template</category>
            <category>code-review</category>
            <category>engineering</category>
            <category>documentation</category>
            <category>technical-documentation</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[System prompt: what to keep, what to cut, when to revisit]]></title>
            <link>https://scribelet.app/blog/system-prompt</link>
            <guid isPermaLink="false">https://scribelet.app/blog/system-prompt</guid>
            <pubDate>Tue, 11 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What belongs in a system prompt, what does not, and how to find the lines that stopped earning their place. Template, placement table, and a review loop. Try it free.]]></description>
            <content:encoded><![CDATA[
Open the system prompt of any assistant that has been in production for a year and read it from the bottom up. The last lines are the newest, and they are the strangest.

Do not begin a reply with "Certainly". Never use the word "delve". If asked about pricing, say you do not know. Each of those was added on a particular afternoon, after a particular complaint, by someone who may no longer be on the team.

Nobody wrote that file. It accumulated. And it only ever grows, because adding a line is a two minute fix with a visible payoff, while removing one is a risk nobody has a ticket for.

Meanwhile the model underneath gets replaced twice a year. The instructions stay frozen at the failure modes of a model that no longer exists. This piece covers what a system prompt is, which four places an instruction can live and how to pick the right one, what belongs in the file and what does not, and how to find the lines that stopped paying rent.

## What is a system prompt?

A system prompt is the set of instructions a language model reads before the conversation starts. It defines the model's role, the rules it works under, and the shape of its output. NIST's glossary describes it as [application-specific instructions provided in-context](https://csrc.nist.gov/glossary/term/system_prompt) by the model developer or the application designer, which is the useful part of the definition: a system prompt comes from whoever built the thing, not from whoever is typing into it.

The user prompt is the question. The system prompt is the standing brief that the question arrives into.

You have probably written one without calling it that. ChatGPT's custom instructions are a system prompt with a friendlier label. So are Claude Projects instructions, the `system` parameter in an API call, the "how should this assistant behave" box in whatever internal tool your team shipped last quarter, and the `.md` file [your coding agent](https://scribelet.app/blog/agentic-coding) reads on startup. Same artifact, four names. However you write one, by hand or by [asking a model to draft it for you](https://scribelet.app/blog/meta-prompting), the same rules decide what belongs in it.

The difference between a system prompt that works and one that fights you is rarely eloquence. It is placement: whether each instruction is in the layer that can hold it.

## System prompt vs user prompt, and the two layers people forget

Most comparisons stop at two. There are four places an instruction can live before the model answers, and putting something in the wrong one produces a specific, recognizable failure.

| Layer | What it holds | How long it lasts | Failure when misused |
|---|---|---|---|
| System prompt | Role, output format, tone, refusal rules, how to use tools | Every request, until someone edits the file | Facts pinned here go stale silently, with no expiry and no owner |
| User prompt | The actual request and its specifics | One turn | Standing rules repeated here get dropped the moment someone forgets to paste them |
| Memory | Stable facts about the person and their work | Across sessions, until corrected | Volatile detail stored here is confidently repeated long after it stopped being true |
| Retrieved context | Documents and notes pulled in for this question | One turn | Source material pasted into the system prompt instead bloats every request and ages in place |

![Diagram of the four layers a model reads before answering: system prompt, memory, retrieved context, and user prompt](/blog/system-prompt/prompt-layers.svg)

The most common mistake is the first row. A line like "the user works at Acme on the Titan migration" reads as helpful context when you write it. It's a fact, and facts change.

Eight months later the migration is done, the model still opens with it, and the person who typed it has moved to another team. A fact in a system prompt has no expiry date and no review, which is the argument for keeping changing detail in [what the AI remembers about you](https://scribelet.app/blog/ai-memory) rather than in the standing brief, where it can at least be listed, edited, and contradicted.

If you want to see that split in a working system rather than in the abstract, Scribelet's [AI memory](https://scribelet.app/learn/ai/ai-memory) documentation shows what gets extracted, where it is stored, and how to correct it.

## What belongs in a system prompt

A good default is shorter than you expect. Six sections, most of them two or three lines, in an order that puts the output contract last so it sits closest to the model's answer.

```markdown
## Role
You are a technical writing assistant for an internal engineering wiki.
Readers are engineers who already know the codebase.

## Scope
Answer from the provided documents. If they do not cover it, say so
and name what is missing. Do not fill gaps from general knowledge.

## Tone
Direct. No preamble, no summary of the question, no closing offer to help.

## Tools
Use `search_notes` before answering anything about internal systems.
Use it once. If it returns nothing, say the wiki has no entry.

## Refusals
Decline requests to modify production configuration. Point at the runbook.

## Output
Markdown. Lead with the answer in one sentence, then the detail.
Code blocks carry a language tag. Never exceed 300 words unless asked.
```

Read that against a typical production prompt and the difference isn't quality of prose, it's what has been left out. No persona backstory. No list of values. No instruction telling the model to be helpful and accurate, because a model that needs to be told to be accurate won't be fixed by being told.

The section that earns its length is Output. Format rules are the first thing models drop when a prompt gets long, so they belong at the end, written as a contract rather than a preference. "Never exceed 300 words" is checkable. "Be concise" is a mood.

## What does not belong

Four things, and they leave for different reasons.

| Keep it out | Why | Where it goes instead |
|---|---|---|
| Facts with a shelf life | No expiry, no owner, no review | Memory, or retrieved context |
| Secrets and permission rules | The prompt isn't a secret and isn't a control | Outside anything the model reads |
| Long worked examples | Paid for on every request, relevant to few | Retrieval, one example per question |
| Workarounds for a retired model | Fixing behavior the current model doesn't have | Deleted, once a test says so |

The first row covers team names, project status, current pricing, who owns what. Memory and retrieved context can both be corrected in one place. A system prompt can't, because nobody opens it again.

On the second, OWASP's [LLM07:2025 System Prompt Leakage](https://genai.owasp.org/llmrisk/llm072025-system-prompt-leakage/) entry is blunt: the system prompt should not be treated as a secret, and it should not be used as a security control. Credentials, connection strings, internal architecture and permission structures don't belong in it. Anyone who can talk to the application will eventually infer most of what the prompt says, so anything that has to stay private has to live somewhere the model can't read.

The third row is where good intentions collect. A couple of examples pasted in to fix one bad answer turn permanent the day they are added, but [few-shot examples belong with the request that needs them](https://scribelet.app/blog/few-shot-prompting), not in a brief that pays for them on every call.

The fourth row is the quiet one, and it's the reason the file keeps growing. A line added in 2024 to stop a model padding its answers is still there in 2026, still costing tokens, still shaping behavior in ways nobody predicted. The model it was written for is gone. Nobody ran the test.

Model choice makes that worse or better depending on how much control you have over it. When the provider swaps the model underneath you on their schedule, your prompt was tuned against a moving target you cannot see; [choosing your own provider and model](https://scribelet.app/blog/byok-ai) at least makes the change an event you decide on.

## Why system prompts rot

Three forces, running at the same time.

The first is scar tissue. Every incident produces a line, and lines are never audited as a set. Twenty of them accumulate, some contradicting each other, and the model resolves the contradiction however it resolves it.

The second is the upgrade. Each new model handles instruction following differently, so a prompt tuned for one is a pile of workarounds for a system that no longer behaves that way.

The vendors know this about their own products. Anthropic publishes the [system prompts for Claude](https://docs.claude.com/en/release-notes/system-prompts) as dated release notes, versioned per model and revised when the model changes. Most teams can't say when their own prompt last changed, or who changed it.

The third is ownership. A system prompt is usually in a config file, a database row, or a settings box in an admin panel. It has no code review, no tests, and no author after the first week. It is the same failure that turns a good runbook into a liability: writing it was somebody's job, and [keeping it true](https://scribelet.app/blog/knowledge-decay) never became anybody's.

![Loop diagram: a failure adds a line, the model is upgraded, the line stays, and the prompt keeps growing](/blog/system-prompt/prompt-drift-loop.svg)

## Read the symptom, then find the line

Bad output from a long system prompt usually traces back to a specific instruction. The mapping is more predictable than it looks.

| What you see | The line that usually causes it | Fix |
|---|---|---|
| Your JSON format is ignored on long answers | The format rule sits in paragraph four, behind 300 words of persona | Move the output contract to the end of the prompt and state it as a hard constraint |
| Replies run three times longer than you want | "Be thorough and comprehensive", written once to fix a thin answer | Replace with a number. Word or sentence limits are followed; adjectives are not |
| Harmless requests get refused | A refusal rule written broadly for an older model that needed the guardrail | Narrow it to the actual case, or delete it and re-test |
| It repeats a fact that stopped being true | A fact pinned in the system prompt with no expiry | Move it to memory, where it can be listed and corrected |
| The newest instruction has no effect | An older line contradicts it, and the model picked the other one | Search the prompt for the opposite instruction before adding another |

The last row is worth its own habit. Before adding a line, search the prompt for the thing you are about to forbid. In a file that has grown for a year, roughly one in five new instructions is arguing with an old one.

## Delete and measure

There is one reliable way to find out whether a line still earns its place, and it takes an afternoon to set up.

Collect twenty real requests, the ordinary ones plus the two or three that caused the incidents that produced the lines in the first place. Save the current answers. Then remove exactly one line from the prompt, run the twenty again, and compare.

If nothing changed, the line was scar tissue, and you've just made every future request cheaper and the file easier to read. If something broke, you've learned what that line does, which nobody currently knows.

A team doing this for the first time on a two year old assistant will usually cut a third of the prompt in a morning. Not because the writing was bad, but because a third of it was written for a model that has since been retired twice.

Two rules make this safe. Keep the prompt in version control, so a bad delete is a revert rather than an archaeology project. And change one line at a time, because a batch of five deletions with one regression tells you nothing about which of the five caused it. The same discipline that makes [checking a claim against its source](https://scribelet.app/blog/ai-fact-checking-for-notes) useful applies here: an unverified change and an unverified fact fail the same way, quietly and later.

## When to revisit

Four triggers, and one floor.

Revisit on a model upgrade, because that is when half the workarounds expire. Revisit when you add a tool, because tool instructions are where contradictions breed. Revisit after any incident that produced a new line, one week later, to check whether the line was the fix or just the thing you did while panicking. And revisit when the prompt crosses whatever length makes you stop reading it top to bottom, which for most people is somewhere around forty lines.

The floor is quarterly, even when none of the four fire. A prompt nobody has read in six months is a prompt nobody knows the contents of, and that is true whether or not it is working.

This is the same maintenance gap that swallows [an AI-compiled wiki](https://scribelet.app/blog/llm-wiki): the compile step is exciting and gets automated, the recompile step is boring and does not.

## The file is an artifact, not a setting

The reason system prompts rot is that everyone treats them as configuration. Configuration gets set once and revisited when something breaks. A system prompt is closer to a piece of documentation that the machine reads on every request, which means it decays the way documentation decays, except that nothing ever renders it visibly wrong. It just gets slowly less true, one obsolete workaround at a time, while the outputs stay fluent enough that nobody goes looking.

Treat it accordingly. Put it in version control, keep it short enough to read in one sitting, move every changing fact into a layer built for change, and delete a line whenever you can prove it does nothing.

If the facts your assistant works from live in your notes, they should be as inspectable as the prompt. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what an AI looks like when it has to show what it knows and where it learned it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>system-prompt</category>
            <category>ai</category>
            <category>llm</category>
            <category>prompt-engineering</category>
            <category>ai-memory</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[9 Obsidian alternatives in 2026, sorted by why you're leaving]]></title>
            <link>https://scribelet.app/blog/obsidian-alternative</link>
            <guid isPermaLink="false">https://scribelet.app/blog/obsidian-alternative</guid>
            <pubDate>Mon, 10 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Nine Obsidian alternatives compared, then sorted by the reason you're actually leaving: too much setup, paid sync, no AI, or notes that quietly went stale.]]></description>
            <content:encoded><![CDATA[
You didn't start looking for an Obsidian alternative because you hate Obsidian. You probably love the core idea: your notes are plain text on your own disk, and no company can take them away. Something specific pushed you to the search bar. The mobile app, the paid sync, the blank vault you never finished setting up, or the slow realization that nothing in there tells you when a note has gone out of date.

That's the problem with most "best Obsidian alternative" lists. They hand you ten apps ranked by popularity and let you sort out which one fixes your actual complaint. A tool that's perfect for someone who wants free self-hosting is useless to someone who just wants the mobile app to stop fighting them.

So here are nine alternatives worth knowing, compared first on the things that decide a switch, then sorted by the reason you're leaving rather than by a ranking. We name the honest best pick for each reason, including several that aren't ours. And we're upfront that one of them is ours, for one specific reason no other tool on this list covers.

## The 9 Obsidian alternatives at a glance

| Tool | Price | Sync | Open source | Built-in AI | Best for |
|---|---|---|---|---|---|
| Logseq | Free | Built-in paid tier, or Git | Yes | No | Daily notes and bullet thinkers |
| Joplin | Free | Your own cloud, or paid Joplin Cloud | Yes | No | Encryption and self-hosting |
| Standard Notes | Freemium | Built-in, end-to-end encrypted | Yes | No | Privacy above everything |
| Anytype | Free | Peer-to-peer, no central server | Code public | No | Local-first without a server bill |
| SiYuan | Freemium | Paid cloud, or self-hosted | Yes | Optional | Notion-style blocks, kept local |
| Notion | Freemium | Built-in, cloud-native | No | Paid add-on | Structure you adopt instead of invent |
| Capacities | Freemium | Built-in, cloud-native | No | Yes | Object-based notes with a modern editor |
| Craft | Freemium | Built-in, cloud-native | No | Yes | A polished editor that opens fast |
| Scribelet | Free tier, Pro $8/mo | Built-in, cross-platform | No | Yes, plus background verification | Notes that stay accurate over time |

Read that table as a starting filter, not a verdict. The column that matters is the one attached to your reason for leaving, which is what the rest of this guide sorts by.

## What's actually pushing people away from Obsidian

Spend ten minutes in any [Obsidian alternatives thread](https://www.reddit.com/r/ObsidianMD/comments/1io0zzx/what_best_obsidian_alternatives_are_out_there/) and the same complaints repeat. They sort into a handful of reasons, and the right alternative is completely different for each one.

Some people find Obsidian too much: too many plugins, too much setup, a blank vault that demands decisions before it gives value. Others love the local-first model but want it free and open source all the way down, or self-hosted on their own server. A large group has no problem with the app and one problem with the price: Obsidian Sync is a [paid add-on](https://obsidian.md/sync), and the mobile experience pushes them to look elsewhere. And a growing group wants AI built in, not bolted on through a community plugin.

There's a fifth reason that rarely makes the lists, and it's the one we built around. Obsidian shows you the graph, the backlinks, and the word count. It never tells you whether the notes inside are still true. If that last one resonates, our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why it happens to every note, in every app, not just yours.

![Diagram mapping each reason for leaving Obsidian to a best-fit tool: too complex to Notion, free or open source to Logseq or Joplin, sync and mobile friction to Logseq, Joplin, or Anytype, built-in AI to Notion, and notes that stay accurate to Scribelet](/blog/obsidian-alternative/pick-by-reason.svg)

## If Obsidian feels like too much setup

If the blank vault defeated you, the fix is an opinionated tool that makes the decisions for you. Picture installing Obsidian, opening it to an empty pane, and realizing you now have to choose a folder structure, a linking convention, and a dozen plugins before you can write a single useful note. For a lot of people that's where the trial ended. (If you do commit to Obsidian, our guide to [the best Obsidian plugins](https://scribelet.app/blog/best-obsidian-plugins) covers which few actually earn a place.)

### Notion

Notion is the obvious move here. It comes with templates, databases, and a structure you can adopt instead of invent, and a non-technical teammate can be productive the same afternoon. The tradeoff is that your notes now live in Notion's cloud database rather than as files you own, which is the exact thing Obsidian fans usually care about. Worth knowing before you commit: people leave Notion too, and [a Notion alternative that fits your reason](https://scribelet.app/blog/notion-alternative) is a different pick depending on whether it got slow, got loud with AI, or locked you in.

**Pick it if** you want structure handed to you and you can live in the cloud. **Skip it if** file ownership was the whole reason you liked Obsidian.

### Capacities and Craft

If you want less structure rather than more, the honest answer might be a simpler note app entirely. Capacities organizes around objects (people, books, meetings) instead of folders, so the shape emerges as you write rather than before. Craft gives you a polished, doc-style editor with light organization and exports that don't embarrass you. Both are cloud-native and both ship AI features, so neither is a local-files replacement.

Apple Notes or Google Keep are fine if all you need is fast capture. If you are torn between the pocket notebook and the power tool, we put [Obsidian and Apple Notes head to head](https://scribelet.app/blog/obsidian-vs-apple-notes) on capture, ownership, and cross-platform reach. If Keep is the app you outgrew rather than Obsidian, we sorted [the Google Keep alternatives by what you outgrew](https://scribelet.app/blog/google-keep-alternative) the same way. Not every Obsidian refugee needs another power tool. Some just need a clean editor that opens fast and stays out of the way.

**Pick them if** the editor was the thing you wanted and the vault was the thing you dreaded.

## If you want it free, open source, or self-hosted

This is where Obsidian's commercial model loses people, and where the open-source community is genuinely strong. Obsidian is free to use but it is not open source, and for some people that distinction is the entire reason they're reading this.

### Logseq

[Logseq](https://logseq.com/) is the closest spiritual sibling: free, open source, local-first, and built around an outliner instead of a document editor. If you think in bullets and daily notes, it can feel more natural than Obsidian. It is also the option here whose storage model is actively changing as the project moves to a database backend, which we weigh in [Obsidian vs Logseq](https://scribelet.app/blog/obsidian-vs-logseq).

**Pick it if** you write in bullets and want the closest free equivalent. **Skip it if** you need a settled file format today.

### Joplin

[Joplin](https://joplinapp.org/) is the pick when end-to-end encryption and sync-to-your-own-cloud matter most. It's open source, stores Markdown, and syncs through Dropbox, Nextcloud, WebDAV, your own server, or its paid cloud. The editor is plainer than Obsidian's and that's rather the point.

**Pick it if** encryption and self-hosting are non-negotiable. **Skip it if** you want a polished writing surface.

### Standard Notes

Encryption-first, end-to-end encrypted by default, open source, with a free tier and paid plans for richer editors. Zero-knowledge apps like Standard Notes win on privacy precisely because they can't read your notes, which is also why they can't run AI over them. If encryption is the actual reason you're leaving, sort out [which secure note-taking app fits your threat model](https://scribelet.app/blog/secure-note-taking-app) before you switch.

**Pick it if** privacy outranks every other feature.

### Anytype

Local-first and object-based, with peer-to-peer sync and no central server, so there's no subscription and no company holding your data. The code is public, though under its own license rather than a standard open-source one, which matters if strict licensing is your reason for leaving.

**Pick it if** you want local-first without a server bill.

### SiYuan

The one that rarely makes these lists and keeps coming up on Hacker News as ["a mix of Notion and Obsidian"](https://news.ycombinator.com/item?id=38772353). Block-based like Notion, local-first like Obsidian, open source, and self-hostable with Docker if you want your own instance. Sync is a paid cloud add-on or your own server.

**Pick it if** you want Notion's block editor without Notion's cloud.

If plain Markdown is the real requirement rather than Obsidian specifically, our roundup of the [best markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) weighs each of these on portability and, just as importantly, on whether anything keeps the notes inside accurate.

All of these share Obsidian's core virtue: the data is yours. They also share its core cost: you are the one maintaining everything inside it. None of them checks whether what you wrote is still accurate, because that was never what they set out to do.

## If sync and mobile are the dealbreaker

Plenty of people would stay on Obsidian if syncing across devices were free and the mobile app felt native.

Obsidian Sync works well but is a paid subscription on top of a free app, and the do-it-yourself alternatives (Git, iCloud, third-party plugins) range from fiddly to fragile. The friction usually shows up at the worst moment. You capture an idea on your phone on the train, open your laptop at your desk, and the note isn't there yet, or it synced twice and now there are two copies to reconcile. For someone living across a phone, a tablet, and a laptop, that gap is the entire reason they start searching.

On Android specifically, the gap widens. Git-based sync plugins that work fine on desktop are awkward to run on a phone, and iCloud is not an option at all, which leaves Android users choosing between the paid subscription and a workaround they have to babysit. Logseq and Joplin both ship real Android apps with their own sync paths, and Anytype syncs peer-to-peer without a central server. If your only complaint with Obsidian is the sync bill and the mobile friction, one of these usually solves it without asking you to relearn how you take notes. Before you commit, it's worth knowing [what true cross-platform note-taking takes](https://scribelet.app/blog/cross-platform-note-taking-app), because a cheaper sync bill doesn't help if the app still treats mobile as a second-class citizen.

Worth saying plainly: if sync is the single issue, switching tools to fix a subscription is a lot of churn. Sometimes the better move is to keep your vault and change how it syncs.

## If it's the graph view you'd miss most

The graph is the feature people picture when they picture Obsidian, and it's the one they're most afraid to lose. The good news is that it's also the easiest to replace. Logseq, SiYuan, and Anytype all ship a graph or a linked-references view, and Capacities builds its whole model around typed objects and their connections. Notion is the notable exception: it has backlinks but no graph, so if the visual map is load-bearing for you, Notion will feel like a downgrade no matter how good its databases are.

Be honest with yourself about how often you used it. For most people the graph is a thing they show other people rather than a thing they work in, and the feature they actually relied on was backlinks, which every tool here supports.

## If you want built-in AI, not another plugin

This is where the alternatives start to look the same, and where most of them stop short.

Obsidian has no native AI, so the community fills the gap with plugins that bolt a chat box onto your vault; we mapped [every way to add AI to Obsidian](https://scribelet.app/blog/obsidian-ai), from plugins to Claude Code, in a separate guide. Notion ships Notion AI as a paid add-on. Newer tools like Mem, Reflect, and Capacities lead with AI as the headline. Google's NotebookLM belongs to a different family again, because it chats over sources you upload rather than notes you keep writing and revising, which is why we sorted the [NotebookLM alternatives for personal notes](https://scribelet.app/blog/notebooklm-alternatives-personal-notes) by job instead of by feature count. Almost all of it is the same shape: reactive AI you have to prompt. You ask a question, it answers from your notes. That's useful for drafting and search, and it's genuinely good at both.

None of it watches your notes for accuracy. Reactive AI only helps when you already suspect something is wrong and think to ask. The far more common case is the note you trust without checking, the one that quietly went stale months ago.

Picture a developer's integration guide that documents an API's auth flow. The provider deprecates that flow in a point release. A chat plugin sitting on the vault has no idea, because nobody asked it. The next person to follow the guide loses a morning to errors that the note caused. That's knowledge decay, and a chat sidebar does nothing about it.

![Side-by-side comparison of reactive AI, which only answers when you prompt it, and proactive AI, which searches the web on a schedule, compares findings to your note, and surfaces a diff for review](/blog/obsidian-alternative/reactive-vs-proactive-ai.svg)

## If you love the ownership but you're tired of maintaining everything

Here's the reason that doesn't make the listicles, and the one Scribelet is built for.

If what you love about Obsidian is ownership, and what wore you down is being the sole maintenance engine for your own knowledge base, the missing piece isn't a prettier editor or another plugin. It's a tool that keeps your notes accurate without you auditing them by hand.

Scribelet keeps the parts Obsidian users care about. You can [bring your own key](https://scribelet.app/blog/byok-ai) and route AI through OpenAI, Anthropic, or Gemini, with the key encrypted at rest, so your notes go to the provider you trust. Notes connect with the same [wikilinks](https://scribelet.app/learn/notes/wikilinks-backlinks) you already use. Then it adds the layer none of the others have: background agents search the web on a schedule you set, compare what they find against what you wrote, and surface the difference as a diff, green for new information, red for what's outdated, with a source link on every change. That's [how background verification works](https://scribelet.app/learn/ai/ai-verification).

A research note you cited six months ago points to a study that's since been retracted. According to [Retraction Watch](https://retractionwatch.com/), paper retractions have grown roughly tenfold since 2000, so this is not a rare edge case. In Obsidian, the link still resolves and the note still looks authoritative. With scheduled verification, the retraction shows up as a diff before you build on it again.

> **Tired of being your own maintenance department?** Start free, run your first verification, and see what a diff actually catches. The [Pro plan](https://scribelet.app/pricing) is $8/mo or $79/yr when you want the full set.

The honest tradeoff: Scribelet isn't a folder of local plain-text files you mold with plugins, and it isn't a free self-hosted project. If pure local ownership is the whole point for you, Logseq or Joplin will fit better. Scribelet is for people who want their notes to stay accurate, not just stay theirs.

## Is there a free version of Obsidian, and should you even switch?

Yes. Obsidian is free for personal use, and most of what makes it good costs nothing. The paid pieces are Sync, Publish, and a commercial license. So before you migrate a vault you've spent years building, it's worth asking whether you have an Obsidian problem or a habit problem.

If the issue is a specific feature, the cheapest fix is often a single add-on or a free sync path, not a new app and a weekend of migration. Switch when the reason you're leaving is structural, when the tool itself can't do the thing you need, like keeping your notes current or working natively across every device. A new editor won't fix a maintenance gap, and a maintenance layer won't make you love an interface you've outgrown.

There's an upside to that weekend of migration, though, whichever tool you're leaving. It's the one moment you have the whole archive in front of you and are already deciding what deserves to come along, which makes it the best chance you'll get to [audit your archive while you migrate](https://scribelet.app/blog/evernote-alternative) instead of quietly rebuilding the same graveyard somewhere nicer.

## So which Obsidian alternative should you pick?

The right alternative is the one that fixes the specific reason you went looking.

If Obsidian was too much, a structured tool like Notion does the deciding for you. If you want free and open source, Logseq and Joplin are the strongest picks, though Logseq's own users are now running the same exercise in reverse, which we mapped in [a Logseq alternative sorted by why you're leaving](https://scribelet.app/blog/logseq-alternative). If sync and mobile drove you out, one of those or Anytype solves it without relearning everything. And if you loved the ownership but not the upkeep, that's the gap Scribelet fills.

| Why you're leaving Obsidian | Best fit |
|---|---|
| Too complex, too much setup | Notion |
| Free, open source, self-hosted | Logseq, Joplin, or SiYuan |
| Sync and mobile friction | Logseq, Joplin, or Anytype |
| Privacy above everything | Standard Notes |
| Built-in AI for drafting | Notion or Capacities |
| The graph view specifically | Logseq, SiYuan, or Anytype |
| Notes that stay accurate over time | Scribelet |

For the two tools people weigh most often before leaving either, our [Notion vs Obsidian comparison](https://scribelet.app/blog/notion-vs-obsidian) goes deeper, and if you are weighing Obsidian against Microsoft's notebook we break down [how Obsidian compares with OneNote](https://scribelet.app/blog/obsidian-vs-onenote), and our [weekly maintenance system](https://scribelet.app/blog/keep-notes-up-to-date) works no matter which app you land on.

## Pick the fix, not the most popular app

The best Obsidian alternative isn't the one with the longest feature list or the most upvotes. It's the one that solves the exact thing that made you start searching. Sort by your reason first, and the field of nine apps shrinks to one or two real candidates.

If the thing that wore you out was maintaining your own knowledge by hand, that's the reason worth fixing for good. [Start writing with background verification and see your first diff](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>obsidian-alternative</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>personal-knowledge-management</category>
            <category>open-source</category>
            <category>byok</category>
        </item>
        <item>
            <title><![CDATA[Technical spec: the three readers your one document has]]></title>
            <link>https://scribelet.app/blog/technical-spec</link>
            <guid isPermaLink="false">https://scribelet.app/blog/technical-spec</guid>
            <pubDate>Mon, 10 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A technical spec serves a reviewer, an implementer, and whoever inherits the system. Most specs are written for none of them. A template, an example, and what to cut.]]></description>
            <content:encoded><![CDATA[
You have been asked to write a technical spec. So you open the team wiki to find one to copy.

There is nothing there. Or worse, there is one: forty pages about a service that got cancelled in 2024, written by someone who left, with a section header called "Non-Functional Requirements Matrix" that is empty.

This is the most common way engineers meet the technical spec. Not as a practice they were taught, but as a task handed to them with no house format, no example, and no clear idea of what "good" looks like. The guidance you find when you search is a list of seven to twelve sections you should include. It is never a list of the ones you should leave out, and it never says who the document is for.

That second question is the one that decides whether a spec works. A technical spec has three readers with genuinely incompatible needs, and most specs are written as one undifferentiated block that serves none of them.

## What is a technical spec?

A technical spec (also called a tech spec, a spec document, or a technical specification document) is a written plan for how a specific piece of software will be built, produced before the implementation starts, so the approach can be reviewed and argued with while changing it is still cheap.

It states the problem, the proposed approach, the parts of the system that will change, the things that could go wrong, and what was deliberately not done. That last part carries more weight than it looks: on a rebuild, the "deliberately not done" list is your main brake on [the urge to over-build version two](/blog/second-system-effect), cramming every deferred idea into the successor. It is not a description of a system that exists. That distinction matters more than any section list, and it is where most of the confusion around the term comes from. The same plan-before-you-build discipline is what [spec-driven development](https://scribelet.app/blog/spec-driven-development) hands to an AI coding agent instead of a teammate, and it is half of [how to work with a coding agent](https://scribelet.app/blog/agentic-coding) at all.

Note that "technical spec" means slightly different things at different companies. At some it is the engineering half of a product plan, written after a product requirements document. At others it is the whole design conversation and the term "design doc" is used interchangeably. Nobody is wrong. What matters is that your team agrees which document decides what, and that the decision is written down somewhere other than someone's memory.

## The three readers your technical spec has

The same file gets read three times, by three people, at three points in time, and each of them wants something the others do not care about.

| Reader | Reads it when | Wants to know | Fails if the spec |
|---|---|---|---|
| The reviewer | This week, once, probably in 20 minutes | Is this approach wrong, and where | Is too long to finish, or too vague to disagree with |
| The implementer | Over the next few weeks, repeatedly | What exactly am I changing, and in what order | Skips the boring specifics: names, endpoints, migration order |
| The inheritor | In a year, once, under pressure | Why is it built like this, and what else was considered | Lists only the chosen approach, with no rejected alternatives |

![Three readers of a technical spec: the reviewer in week 1, the implementer in weeks 2 to 6, the inheritor a year later](/blog/technical-spec/three-readers.svg)

Notice that the reviewer and the implementer want opposite things. The reviewer wants the document short enough to actually read. The implementer wants the migration order, the exact table names, and the rollback command. They aren't the same document. Trying to serve both in one continuous narrative produces a document that is too long for one and too vague for the other.

The fix is not a longer spec. It is a spec that separates the argument from the instructions, so the reviewer can read the first part and stop. Surfacing the load-bearing decision also protects it from [the pull toward arguing the trivia](/blog/sayres-law): a reviewer who can find the choice that matters is less likely to spend the review on variable names.

[Start writing in Scribelet](https://scribelet.app) if you want a place to keep specs where the claims in them get checked later. More on that at the end.

## What each reader needs you to write

### The reviewer wants sentences they can disagree with

The single most common defect in a technical spec is that it can't be argued with. "We will use a queue to decouple the services" is not a claim. Nobody can disagree with it, because it doesn't say which queue, what happens when it backs up, or what the ordering guarantee is.

Compare that to: "We will use SQS FIFO with a 5 minute visibility timeout. Messages are ordered per customer, not globally. If the consumer falls behind by more than 10,000 messages, we page rather than shed load."

That version can be wrong. A reviewer can point at the second sentence and say the ordering guarantee will not hold for the batch importer. That is what a review is for, and a spec that cannot produce that sentence has wasted everyone's twenty minutes.

![A vague claim defers the argument from spec review to the pull request and then to production, where it costs most](/blog/technical-spec/where-disagreement-lands.svg)

The argument does not go away when the sentence is vague. It just moves to a more expensive room.

The IETF made this concrete decades ago. [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) defines MUST, SHOULD, and MAY as distinct requirement levels precisely so that a reader can tell a hard constraint from a preference. You don't need to adopt the capitalised keywords, but you do need the distinction. "The service should retry" and "the service must retry" describe different systems, and reviewers will assume whichever one is convenient unless you say.

### The implementer wants the boring parts

The reviewer is gone by week two. Now the document has one job: stop the person building it from having to guess.

That means the parts that feel too obvious to write down. The name of the new table. The order of the migration relative to the deploy. Which feature flag gates it. What the rollback actually is, in a form specific enough that someone can run it at a bad time.

This is also where most specs quietly go wrong, because these are the details most likely to change during implementation. The decision gets made in a pull request comment, the code ships, and the spec still describes the plan rather than the thing. If that sounds familiar, it is the same failure mode covered in [why engineering docs go stale](https://scribelet.app/blog/outdated-documentation).

### The inheritor wants to know what was rejected

A year later, someone is looking at this system and wondering why it is built the strange way it is built. The chosen approach is [visible in the code](/blog/self-documenting-code). What is not visible is the three approaches that were considered and dropped, and why.

Rejected alternatives are the highest-value and first-cut section of any spec. Write them as one honest sentence each: what it was, and the specific reason it lost. "Postgres LISTEN/NOTIFY: dropped because notifications are lost if no listener is connected, and we need delivery across a deploy" is worth more in a year than four pages of the design that won. It is also your first defense against [feature creep](https://scribelet.app/blog/feature-creep): a feature you rejected with the reason written down cannot quietly return the next time someone asks for it.

When a decision outlives the spec that contained it, promote it. That is what [an ADR template you can copy](https://scribelet.app/blog/architecture-decision-record-examples) exists for: a decision record survives the project, and a spec does not.

## A technical spec template

Copy this. It is short on purpose, and the fields most templates omit are the last three.

```markdown
## Technical spec: [what is being built]

Status: draft | in review | approved | shipped | abandoned
Author:
Reviewers:
Last true on: [date the described plan last matched reality]

## Problem

What is broken or missing, and how you know. One paragraph. Include the number
that made this worth doing.

## Proposed approach

What you are going to build, in enough detail that a reviewer can say
"that will not work because...". Name the services, the data, the interfaces.

## What changes

The concrete surface area. New or modified tables, endpoints, queues, jobs,
config. This is the implementer's section.

## Rollout and rollback

Order of operations. What is behind a flag. The exact rollback, written so
somebody can run it at 3 a.m. without you.

## Alternatives rejected

One line each: what it was, and the specific reason it lost.

## Risks and what would change our mind

Each risk paired with the observation that would prove it real.

## Assumptions with expiry

Claims this plan depends on that are true today and may not stay true.
Each one gets a trigger: "if X ships, revisit this."

## Open questions

Things not decided yet, each with an owner and a date.
```

Three of those fields are unusual, and they are the ones that pay off later.

**Last true on** is a date separate from "last edited". Editing a typo does not make a plan current. This is the same distinction that makes internal wikis untrustworthy: [last edited is not last verified](https://scribelet.app/blog/internal-documentation).

**Assumptions with expiry** turns a silent dependency into a tripwire. "We assume the vendor's rate limit stays at 1,000 requests per minute; if they announce a change, this design needs revisiting" is a sentence that can be checked later. "We assume reasonable vendor limits" is not.

**Risks paired with observations** stops the risk section from being decorative. Every real risk has a thing you would see if it were happening. Write that thing. Naming the unknowns this way is also how you [narrow the range on your estimate](/blog/cone-of-uncertainty): each risk you resolve on paper is a slice of the schedule you no longer have to guess at.

## A worked example, abbreviated

Here is the middle of a real-shaped spec, compressed. The point is the texture, not the completeness.

```markdown
## Technical spec: per-customer rate limiting on the public API

Status: in review
Last true on: 2026-08-10

## Problem

Three customers generated 61% of API traffic last month. One of them ran a
backfill on 14 July that pushed p99 latency from 180 ms to 4.2 s for everyone
else for 40 minutes. We have no per-customer ceiling.

## Proposed approach

Token bucket per API key, held in Redis, refilled at the plan's rate. Limits
are checked in the existing auth middleware, before routing, so a rejected
request never touches a handler. Over-limit requests get 429 with a
Retry-After header. Buckets are sized per plan, not per endpoint.

## Alternatives rejected

- Nginx rate limiting: dropped, limits are per instance and we run 12, so the
 effective limit is 12x the intended one.
- Per-endpoint limits: dropped, a customer hitting one expensive endpoint is
 the actual failure and per-endpoint budgets hide it.
- Queue and defer instead of rejecting: dropped, clients time out at 30 s and
 a deferred request they no longer wait for is worse than a fast 429.

## Risks and what would change our mind

- Redis becomes a hard dependency of every request. If Redis p99 exceeds 5 ms
 we will see it as added latency on all traffic, not just limited traffic.
- Buckets are per key, so a customer with six keys gets six buckets. If
 support tickets about "the limit is wrong" start arriving, this is why.

## Assumptions with expiry

- Plan tiers stay at three. If usage-based pricing ships, bucket sizing moves
 out of the code and this section is wrong.
```

Read the alternatives section again. In a year, that is the only part anybody will need.

## Technical spec vs design doc, ADR, PRD, and RFC

These overlap, and teams use the words loosely. What follows is the distinction that is worth keeping, which is about scope and lifespan rather than format.

| Document | Answers | Written | Lifespan |
|---|---|---|---|
| Technical spec | How will we build this specific thing | Before implementation | Until the code ships |
| [Design doc](https://scribelet.app/blog/software-design-document) | What should this system look like | Before or alongside the spec, usually broader | Until the design is superseded |
| ADR | Why did we choose this, and what did we reject | At the moment of decision | Forever, superseded but never deleted |
| PRD | What should the product do, and for whom | Before engineering starts | Until the feature ships |
| RFC | Should we do this at all, across teams | When the blast radius is wide | Until accepted or withdrawn |
| [Runbook](https://scribelet.app/blog/runbook) | What do I do when it breaks at 3 a.m. | After it ships | As long as the system runs |

The practical rule: if the document answers "why", it should end up as an ADR. If it answers "what do I type when this breaks", it should end up as a runbook. The spec is the thing in between, and it is the only one on that list with a short life by design.

[Malte Ubl's account of design docs at Google](https://www.industrialempathy.com/posts/design-docs-at-google/) makes the same point from a different angle: the value is concentrated in the writing and reviewing, not in the artifact left behind. The [Stack Overflow engineering blog's guide to technical specs](https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/) is the other piece worth reading, mostly for its treatment of getting reviewers to actually respond.

## What to cut

Every guide adds sections. Here are the ones to remove.

- **The glossary**, unless the spec introduces a term that does not exist anywhere else. Otherwise it is four paragraphs nobody reads to define "idempotent".
- **The architecture diagram of the existing system.** It is already out of date and it is not what you are changing. If you do keep a diagram, [write it as code](https://scribelet.app/blog/mermaid-diagrams) so it lives in the diff rather than drifting as a stale image.
- **Estimates in hours.** They are wrong, they age instantly, and they turn a technical review into a scheduling argument. If you must put a number on it, at least know [why that number always runs long](/blog/hofstadters-law) before you defend it.
- **Anything restating the ticket.** Link the ticket.
- **The success metrics section**, if it is aspirational. Either name the number you will look at and when, or cut it.
- **The full API schema.** Put the two endpoints that change in the spec and link the schema.
- **The complete future-state architecture.** Specify the version you will actually build next, not the complex system you hope it becomes. The reliable path is to [start with a simple system that works](/blog/galls-law) and grow it one validated layer at a time, beginning with [the thinnest slice that runs end to end](/blog/walking-skeleton), so a spec that designs the whole end state up front is describing a system that does not exist yet and probably never will as drawn.

A ten page spec gets skimmed. A two page spec gets argued with. Only one of those produces the thing you wrote it for.

## What happens to the spec after the code ships

The spec has done its job the moment the change is merged and reviewed. This is where teams go wrong in one of two directions.

Some delete it, and lose the rejected alternatives, which is the part with a long half-life. Others keep it in the wiki forever, where it sits at the top of search results describing a plan rather than a system, and gets read as though it were documentation. The second failure is worse, because it looks like an asset.

The handover is short, and it is worth doing on the day the pull request merges:

1. Decisions with a long life become ADRs.
2. Operational steps become a runbook.
3. Usage becomes a README or an API doc.
4. The spec gets marked `shipped`, keeps its rejected alternatives, and stops being presented as current.

That last step is the one that never happens, because nothing prompts anyone to do it. The document doesn't know it went out of date, and neither does the wiki. This is the general shape of [information half-life](https://scribelet.app/blog/knowledge-decay) in engineering: nothing announces its own decay, so it accumulates silently until somebody trusts the wrong page.

Scribelet exists for that gap. Background checks re-examine the claims in a note against current sources and your own repository, and show you a diff of what no longer holds rather than a vague warning that something might be stale. For specs, the useful version is pointing it at your code: [verify notes against your repo](https://scribelet.app/learn/ai/github-connector) catches the case where the spec says one queue and the service has three, which is the exact drift that makes an old spec dangerous.

None of this writes the spec for you. It answers the question that comes after: of the documents you kept, which ones are still true. [Try AI verification free](https://scribelet.app/learn/ai/ai-verification) and start with the oldest spec anybody still links to.

## The short version

A technical spec is a plan for something that does not exist yet, written to be argued with before it is expensive to change.

Write it for three readers and keep them separate. The reviewer gets claims specific enough to be wrong. The implementer gets the boring, exact parts. The inheritor gets the alternatives you rejected and the reason each one lost.

Keep it to two pages. Give it a "last true on" date, assumptions with triggers, and risks paired with what you would observe. Then, at merge, hand the durable parts off to an ADR and a runbook and mark the spec shipped.

The document that describes your system is never the one you wrote before you built it.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>technical-spec</category>
            <category>technical-documentation</category>
            <category>engineering</category>
            <category>documentation</category>
            <category>software-architecture</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Software design document: a template that expires on purpose]]></title>
            <link>https://scribelet.app/blog/software-design-document</link>
            <guid isPermaLink="false">https://scribelet.app/blog/software-design-document</guid>
            <pubDate>Sun, 09 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What a software design document is, what belongs in one, a template with expiry fields built in, and how it differs from an ADR or runbook. Try it free.]]></description>
            <content:encoded><![CDATA[
Six months after the payment service shipped, someone searches the wiki for how it works. The top hit is the design doc.

It is twenty pages, carefully written, and it describes a system with three queues and a Redis cache. The service that runs in production has one queue and no Redis. That change happened in week two, in a pull request comment, and the doc was never touched again.

The doc wasn't wrong when it was written. It was a proposal. Then the proposal got argued with, which is what proposals are for, and the argument happened somewhere else.

This is the part almost nobody writes about. There is no shortage of guidance on what sections belong in a software design document. There is very little on what the document is for after the code merges, which is when most of them quietly become misinformation with a table of contents.

So: what a software design document is, what belongs in one and what to cut, a template with expiry built into it, how it differs from an ADR or a runbook, and what to do with the thing once the system it describes actually exists.

## What is a software design document?

A software design document (SDD) is a written proposal for how a system will be built, produced before implementation starts, so that reviewers can find problems in the design while changing it is still cheap. It states the problem, the proposed approach, the alternatives that were rejected, and the trade-offs accepted. Working through those is also what turns a day-one estimate from [a guess with a huge margin into a narrowing range](/blog/cone-of-uncertainty), because the design phase is where the biggest unknowns finally get resolved.

Note the tense. A software design document describes a system that doesn't exist yet. Most definitions call it a blueprint, and that word does real damage, because a blueprint implies a faithful description of a finished building.

The formal standard is more careful. [IEEE 1016](https://en.wikipedia.org/wiki/Software_design_description) frames a software design description as a representation used to communicate a design to its stakeholders, which describes an audience, not a finished system. A design doc is closer to a planning application: a serious, detailed argument about something you intend to build, subject to revision by everyone who reads it, including the timeline, which [will slip for reasons the plan cannot yet name](/blog/hofstadters-law).

Getting the tense right changes how you write one, how long you make it, and what you do with it afterwards.

Scribelet was built on the observation that documents start decaying the moment they are saved. A design doc is the purest case: it is out of date by design, on a schedule you can predict. [Start writing with Scribelet](https://scribelet.app) if you want the docs that outlive the design doc to stay true.

## What actually goes in a software design document

The section list is not the hard part, and it is where most guides stop. Angela Zhang's [guide to writing a good design doc](https://medium.com/free-code-camp/how-to-write-a-good-software-design-document-66fcf019569c) remains the best public version of the list, and it is worth reading. Here is the working set, with the thing each section is really for.

**Context and problem statement.** What is broken or missing, for whom, and what it costs today. If a reader cannot restate the problem after this section, nothing below it matters.

**Goals and non-goals.** Non-goals do more work than goals. They are how you stop the review from expanding into every adjacent system, how you [keep a product from bloating past its scope](https://scribelet.app/blog/feature-creep), and the first thing to check when someone later asks why the design did not handle a case. On a rewrite they matter even more: an explicit non-goals list is the surest defense against a [bloated second-system rewrite](/blog/second-system-effect), the pull to pour every feature the first version skipped into its successor.

**Proposed design.** The approach, the components, how data moves between them. Diagrams belong here, and if you write them as [diagrams as code](https://scribelet.app/blog/mermaid-diagrams) they stay in the doc's diff instead of rotting as an exported image; so do the interfaces between pieces owned by different people, because those are where the expensive misunderstandings live. Describe the version you will build next, not the entire end state: [a complex system designed from scratch](/blog/galls-law) rarely survives contact with reality, so the strongest designs specify a simple system that works and the next layer they will grow onto it.

**Alternatives considered.** The designs you rejected and why. This is the highest-value section in the document and the most commonly skipped. It is also the section most likely to still be true in a year, since the reasons an approach was rejected tend to outlive the approach that won.

**Trade-offs and risks.** What this design is bad at. A design doc with no weaknesses listed has not been thought about hard enough.

**Rollout and migration.** How the change reaches production, and how it comes back out if it goes badly.

**Open questions.** What is genuinely undecided. Naming these attracts exactly the review comments you need.

### What to cut

Cut the boilerplate front matter: scope statements, glossaries of terms every reader knows, document revision history nobody maintains. Cut anything the code will state more precisely than prose ever could, such as full schemas and exhaustive API signatures. Cut restatements of the company's standard architecture.

Google's internal practice, described in [Design Docs at Google](https://www.industrialempathy.com/posts/design-docs-at-google/), pushes the same way: the useful documents are the short ones that get read, and the ceremony around them is what kills them.

The test for a section is simple: could a reviewer disagree with it? A section nobody can disagree with is not a design decision, and it is costing you review attention that should go somewhere else.

## A software design document template

Copy this. The first four fields exist because a design doc has a predictable expiry date, and almost no published template acknowledges that.

```markdown
# Design: [system or change]

Author:
Reviewers:
Status: draft | in review | accepted | shipped | superseded | abandoned
Written: YYYY-MM-DD
Design last true as of: YYYY-MM-DD
On merge, this becomes: [ADR #, runbook, README section, or "archive"]

## Context and problem
What is broken, for whom, and what it costs today.

## Goals
## Non-goals

## Proposed design
The approach. Components, data flow, interfaces between pieces owned by
different teams.

## Alternatives considered
| Option | Why not |
|---|---|

## Trade-offs and risks
What this design is bad at.

## Assumptions
| Assumption | What would invalidate it |
|---|---|

## Decisions deferred
Decisions we are explicitly not making now, and when we will make them.

## Rollout and rollback

## Open questions
```

Four fields there are unusual, and they are the point of the template.

**`Status` including `shipped` and `abandoned`.** Most templates stop at "accepted", which means every document in the folder looks equally live forever. A doc marked `shipped` tells a reader the system exists and this file is history. A doc marked `abandoned` saves the next person from designing the same thing again.

**`Design last true as of`.** Separate from the written date. When the design changes in review or during implementation, this is the field you touch. The gap between the two dates is the fastest available signal that a doc has drifted.

**`Assumptions` with an invalidation column.** "We assume fewer than 500 writes per second" is a fact with a shelf life. Writing down what would break it turns a buried assumption into something checkable later.

**`On merge, this becomes`.** The most important line in the template. It forces the author to decide, up front, which durable document inherits this content once the code ships. Without it, the design doc becomes the permanent home for information it was never built to hold.

## Software design document vs ADR, RFC, PRD, and runbook

The related searches for this term are full of people trying to work out which document they actually need. The honest answer is that these are different documents with different expiry dates, and using one for another's job is where most documentation rot starts.

| Document | Answers | Written | Expires |
|---|---|---|---|
| **Design doc / SDD** | How should we build this? | Before implementation | At merge. The system it describes is now the source of truth. |
| **Technical design document** | Same thing, different house style. Often narrower, one component rather than a system. | Before implementation | At merge. |
| **ADR** | Why did we choose X over Y? | At the moment of decision | Never. It records a decision that was true then, and gets superseded, not edited. |
| **RFC** | Should we do this at all? | Before the design | When the decision is made. |
| **PRD** | What should this do, and for whom? | Before the design | When the feature ships. |
| **Runbook** | What do I do when this breaks at 3 a.m.? | After the system exists | Continuously, every time the system changes. |
| **README** | How do I use or run this today? | With the code | Continuously, and it lives next to the code so it can be reviewed with it. |

![Timeline comparing when a PRD, RFC, software design document, ADR, runbook and README are written and when each one expires](/blog/software-design-document/doc-types-expiry.svg)

Two rows deserve attention.

The **design doc and the technical design document** are the same artifact in most organisations. Where teams distinguish them, the design doc covers a system or feature and the technical design document covers one component's implementation. If your team uses both words for the same thing, that is normal, and standardising on one is not worth a meeting.

The **ADR is the only document in this table that never expires**, because it is scoped to a decision rather than a system. That is exactly why it is the right destination for the "alternatives considered" section when the design doc retires. Our guide to [architecture decision records with real examples](https://scribelet.app/blog/architecture-decision-record-examples) covers the template and the supersession pattern that makes this work.

## Why the doc stops being true at merge

Design docs do not rot the way a wiki page rots. They fail on a schedule, and the schedule is short.

The divergence starts in review. Someone points out that the three-queue design has a head-of-line blocking problem, and the team agrees on one queue with a priority field. That decision is now in a comment thread. It reaches the code the same week and it never reaches the document, because updating the document is nobody's task in the sprint and the code is what needs to ship.

By merge day, the doc describes a design that was superseded by its own review. Nothing about this is negligent, and nobody was lazy. The review worked exactly as intended: it changed the design. The failure is that the artifact was treated as durable when it was written to be argued with.

Then a second, worse thing happens. The doc stays in the wiki, well written and confident, and it outranks the code in search results. Six months later it's the first thing a new engineer reads about the payment service, and the specific hazard of a design doc is that it's *plausible*.

A stale runbook fails loudly, with a command that exits non-zero. A stale design doc fails silently, by teaching someone a mental model of a system that was never built. This is the same failure mode we covered in [why internal documentation goes stale](https://scribelet.app/blog/internal-documentation): the first draft always gets written, and the second draft is nobody's job. The AI-native heir to the design doc inherits it too: [the spec you hand a coding agent](https://scribelet.app/blog/spec-driven-development) is authoritative right up until the code moves past it.

## Write sections a reviewer can check

Most weak design docs are weak in the same way. They describe intentions rather than commitments, which makes them impossible to disagree with in review and impossible to check afterwards.

Before:

> The service will handle high traffic and scale as needed. We will use caching to improve performance and ensure a good user experience.

Nobody can review this. There is no number to challenge, no mechanism to question, and in a year there is no way to tell whether it is still true.

After:

> Peak load today is 400 writes per second, measured over the last 90 days. This design targets 1,200, which is three times the current peak, using a single queue with a priority field. Above roughly 2,000 writes per second the single consumer becomes the bottleneck and we would need to partition by tenant. We are explicitly not building partitioning now (see Decisions deferred).

The second version can be argued with, which is the point of the review. It also stays useful afterwards: the numbers can be compared against reality later, and "we are not building partitioning yet" is exactly the context the next engineer needs.

A good heuristic while drafting: if a sentence would survive being copied into a different company's design doc unchanged, cut it. It is not carrying information about your system.

Scribelet's background agents run against claims like these. When a doc asserts a number, a version, or a limit, that assertion is something a verification pass can check later. [See how AI verification works](https://scribelet.app/learn/ai/ai-verification) if the idea of a document that reports its own drift is new.

## What to do with the doc after the code ships

This is the step that separates a design doc that ages gracefully from one that quietly misinforms people for years. Do it in the same pull request that merges the implementation, while the divergence is still fresh in someone's head. If nothing prompts for it there, it will not happen: [three templates instead of one](https://scribelet.app/blog/pull-request-template) covers how to make the prompt fit the size of the change.

![Diagram showing a software design document moving from draft to review to shipped, then handing its content off to an ADR, a runbook, a README, and an archive](/blog/software-design-document/design-doc-lifecycle.svg)

1. **Set `Status: shipped`** and update `Design last true as of`. Two fields, thirty seconds, and every future reader now knows what they are holding.
2. **Move the decisions out.** Each entry in "alternatives considered" that the team will care about later becomes an ADR. The design doc explained one system; the ADR explains one choice, and it stays valid long after the system is rewritten.
3. **Move the operations out.** Rollout, rollback, failure modes, and anything that answers "what do I do when this breaks" belongs in a [runbook](https://scribelet.app/blog/runbook), where it will be exercised and corrected.
4. **Move the usage out.** How to run the thing, its configuration, its interfaces: README, next to the code, reviewed when the code changes.
5. **Archive the rest.** Not delete. Move it somewhere clearly marked as history, so the search hit six months from now carries the right label.

Note what survives. The design doc is the only document in this list built to be discarded, and the four documents it feeds are the ones built to last. Treating the design doc as permanent is what puts durable content in a disposable container.

## Keeping the surviving documents true

The conversion step solves the design doc. It does not solve what comes next, because the ADRs, runbooks, and READMEs it produces are subject to [the same decay](https://scribelet.app/blog/knowledge-decay) as any other document. They just decay more slowly, which is a real improvement and not a fix.

What breaks them is external change: a library deprecates the API a runbook depends on, a service you documented changes its rate limits, a link in an ADR moves. None of it generates a notification. The document keeps looking correct. This is the general case of [outdated documentation](https://scribelet.app/blog/outdated-documentation), and it is why a review cadence based on the calendar rarely survives contact with a quarter that has a fire in it.

Scribelet runs background agents against your notes and docs on a schedule you set. They search the web, compare what they find to what you wrote, and return a diff: green for what changed, red for what no longer holds, with source links so you can judge the finding yourself. If your docs live alongside code, the [GitHub connector](https://scribelet.app/learn/ai/github-connector) pulls the repository into the same checks, so a doc claiming a flag that no longer exists gets flagged.

You choose the model and, if you want the sovereignty path, bring your own API key. Your keys are encrypted at rest, and your documents go to the provider you picked.

None of this writes your design doc for you. It answers the question that comes after: which of the documents you kept are still true today. [Try AI verification free](https://scribelet.app) and start with the doc you trust least.

## The short version

A software design document is a proposal for a system that does not exist yet. Write it to be argued with, keep it short enough that people actually review it, and give it fields that make its expiry visible: a status that includes `shipped`, a date for when the design was last true, assumptions with what would invalidate them, and an explicit note about which document inherits the content at merge.

Then, when the code ships, actually do the handover. Decisions become ADRs. Operations become runbooks. Usage becomes [a README that stays current](https://scribelet.app/blog/how-to-write-a-readme). The design doc gets marked shipped and archived, having done its job.

The doc that describes your system is not the doc you wrote before you built it. It never was.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>software-design-document</category>
            <category>technical-documentation</category>
            <category>engineering</category>
            <category>documentation</category>
            <category>software-architecture</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Runbooks: what they are and why yours is already stale]]></title>
            <link>https://scribelet.app/blog/runbook</link>
            <guid isPermaLink="false">https://scribelet.app/blog/runbook</guid>
            <pubDate>Sat, 08 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A runbook is a step-by-step guide for a repeated operational task. What goes in one, how it differs from a playbook, and why yours drifts. Try it free.]]></description>
            <content:encoded><![CDATA[
It's 3:40 a.m. and the page says the payment queue is backing up. You're half awake, you've never seen this alert before, and you do the correct thing: you open the runbook.

Step one, check the dashboard. The link 404s; that dashboard moved when the team migrated to the new Grafana instance. Step two, run the drain command. The flag it uses was renamed two releases ago and the command exits non-zero. Step four references a service that was folded into another service in March.

Somebody wrote this carefully. It was accurate the day it was written. Nobody lied to you, and nobody was lazy. The runbook just aged, quietly, in a repo where nothing forced anyone to look at it until the exact moment you needed it to be right.

This is the part of runbook documentation that almost nobody writes about. There's no shortage of guidance on what a runbook is and which sections belong in one. There's almost nothing on what happens to it over the following eighteen months. So: what a runbook is, how it differs from a playbook, the four specific ways it goes wrong, and how to build one that tells you when it has stopped being true.

## What is a runbook?

A runbook is a documented, step-by-step procedure for a specific, repeatable operational task: restarting a stuck service, rotating a certificate, draining a queue, failing over a database. It names the trigger that starts the procedure, the exact commands or checks to run, the expected result at each step, and who to escalate to when the steps don't work. Writing one down at all is the point: it moves a procedure out of the head of whoever set it up, which makes a runbook one of the most direct ways to [raise the bus factor](/blog/bus-factor) on an operational task.

The value is not that it contains knowledge. It's that it contains knowledge in a form somebody can execute at 2 a.m. with no context and adrenaline in their bloodstream. Google's SRE team puts a number on it: consulting a playbook during an incident produces [roughly a 3x improvement in mean time to repair](https://sre.google/sre-book/being-on-call/) compared with improvising. That's the whole case for writing them. It's also the case for keeping them accurate, which is the harder half, and the reason we [built background verification into a notebook](https://scribelet.app) in the first place.

A useful operational runbook has five parts:

1. **Trigger.** The alert, symptom, or schedule that means "open this document." Be specific enough that someone can match a page to a runbook without reading six of them.
2. **Preconditions.** Access you need, systems that must be up, and anything you should check before touching production.
3. **Steps.** Numbered, with the literal command and the expected output. Not "restart the consumer" but the command, and what a healthy response looks like.
4. **Verification.** How you know it worked, stated as an observable: a metric returning to baseline, a queue depth falling, a health endpoint returning 200.
5. **Escalation and rollback.** Who to wake, and how to undo what you just did if it made things worse.

AWS's Well-Architected Framework frames the target well: a runbook should carry [the minimum information necessary to perform the procedure successfully](https://wa.aws.amazon.com/wellarchitected/2020-07-02T19-33-23/wat.concept.runbook.en.html). Everything past that minimum is surface area that can rot.

If you want to see what mature ones look like in the wild rather than in a template, GitLab publishes [its production runbooks openly](https://gitlab.com/gitlab-com/runbooks). It's an unusually honest look at the format, including how much of it is maintenance scaffolding.

![Diagram of the five parts of a runbook: trigger, preconditions, steps, verification, and escalation, arranged as a vertical flow with a verified-on stamp](/blog/runbook/runbook-anatomy.svg)

## Runbook vs playbook vs SOP

These three get used interchangeably in most organizations, which is fine until someone asks you to "write a runbook" and hands you a scope you didn't expect. The distinction that actually matters is how much judgment the document assumes the reader will apply.

| | Runbook | Playbook | SOP |
|---|---|---|---|
| **Scope** | One specific task or alert | A whole class of incident or event | A recurring business process |
| **Reader** | On-call engineer, mid-incident | Incident commander, coordinating | Anyone performing the process |
| **Judgment assumed** | Almost none. Follow the steps. | Substantial. Choose a branch. | Some. Follow policy, apply context. |
| **Typical length** | One page | Several pages | Varies, often long |
| **Failure mode when stale** | Wrong command at 2 a.m. | Wrong escalation path | Compliance gap |

An incident runbook says "the payment queue is backing up, here is how to drain it." A playbook says "we're in a Sev1 involving payments, here is how we run the incident, who declares, who communicates, when we page the exec on call." An SOP says "here is how we onboard a vendor." The runbook is the tactical one, and it's the one that gets read fastest and checked least.

Runbook automation sits at the end of that spectrum: you take a procedure stable enough that no judgment is required, and turn its steps into a script or workflow. That's a real improvement, and it moves the decay problem rather than solving it. An automated script that calls a renamed endpoint fails just as hard as a human following a stale instruction, and it fails without a person there to notice something looked off.

## Why runbooks rot faster than any other document

Every document in your organization decays. Runbooks decay faster, for three reasons that compound.

**The subject changes constantly.** A runbook describes a live production system, and that system ships. Every deploy, rename, migration, dependency bump, and dashboard reorganization is a chance for a step to fall out of sync. If you deploy weekly, the document has roughly fifty opportunities a year to become wrong. Design docs describe intentions, which stay fixed. Runbooks describe infrastructure, which does not. That's the same mechanism behind [why engineering docs go stale](https://scribelet.app/blog/outdated-documentation) generally, running at a much higher clock speed.

**Almost nobody reads it.** A good runbook covers a failure that's rare. Rare failure means the document sits untouched for months, so the normal correction mechanism (someone reading it and noticing an error) almost never fires. The documents that stay accurate are the ones people read constantly, and by definition your runbooks are not those.

**The error surfaces at the worst moment.** A wrong entry in your architecture notes costs you an awkward meeting. A wrong step in an on-call runbook costs you minutes in an outage, or worse, it makes you run a command that does something you didn't intend. The document with the highest cost of being wrong is also the one with the fewest natural opportunities to be corrected. That inversion is the entire problem, and it's a sharper version of [knowledge decay](https://scribelet.app/blog/knowledge-decay) than most notes ever face.

![Chart showing a runbook accuracy line falling steadily over eighteen months while system changes accumulate, with the gap between them labeled as drift](/blog/runbook/runbook-drift.svg)

## The four ways a runbook actually goes wrong

Runbook rot isn't one failure. It's four, and they need different fixes.

**Dead references** are the most common and the least dangerous, because they announce themselves. A dashboard URL that 404s, a wiki page that moved, a Slack channel that was archived, a person who left in 2025 listed as the escalation contact. You lose time, you don't lose data.

**Drifted commands** are worse. The command still exists and still runs, but a flag was renamed, a default changed, or the tool moved from `v1` to `v2` with different semantics. The step no longer does what the document says it does, and sometimes it does something adjacent and harmful. This is the failure mode that turns a 15-minute incident into a postmortem.

**Phantom steps** survive their own purpose. A step exists because a service used to need a manual cache flush before restart. That service was rewritten and no longer does. The step is now a no-op at best, and the document is teaching every new engineer a piece of folklore about a system that doesn't exist. Nobody removes it, because deleting a step feels riskier than leaving it.

Then there are **missing steps**, which are invisible by construction. A new dependency was added to the deploy path six months ago. The runbook was never updated, so it doesn't mention it, and there's nothing in the document to indicate an absence. You only discover a missing step by executing the procedure and having it not work, which means you discover it during an incident. Reviews rarely catch these, because a reviewer reads what's on the page and evaluates whether it's correct. It is correct. It's just incomplete.

## Why "review it quarterly" doesn't work

The standard advice is to assign an owner and review runbooks on a schedule. Every team that has tried this knows how it goes. The review lands in a sprint that's already full, one person skims fifteen documents in an hour, and each one gets a fresh `last updated` date that certifies nothing. Now the runbook is stale *and* it looks current, which is worse than stale and obviously old.

Calendar review fails because the calendar isn't what changed. Your runbook didn't become wrong on the first of the quarter. It became wrong the afternoon somebody merged a PR that renamed a service. The review interval and the decay event have no relationship to each other, so you're either reviewing documents that didn't need it or missing the ones that did.

The second failure is that `last updated` is doing work it can't do. Editing a typo bumps the date. So does rewriting every command. The field records that a human touched the file, not that anyone confirmed the contents still match production, which is the distinction behind [last edited is not last verified](https://scribelet.app/blog/internal-documentation). A runbook needs a separate `verified-on` field, changed only when someone actually ran or checked the procedure against the current system.

> A runbook with a recent edit date and no verification date is a document that looks trustworthy and isn't. That combination is worse than no runbook, because it stops the on-call engineer from being appropriately suspicious.

## A runbook that tells you when it's wrong

The fix isn't more discipline. It's building the expiry into the document and attaching the check to the thing that actually causes drift.

Start by writing down what would make each step wrong, next to the step. Not a vague "review if things change," but the specific dependency: *this step breaks if the queue consumer is renamed or the drain endpoint moves.* These are [named drift triggers](https://scribelet.app/blog/architecture-decision-record-examples), the same technique that keeps architecture decision records honest, and they convert a periodic review into a targeted one. When you rename the consumer, you know which document to open, because the document told you in advance.

Give every runbook a `verified-on` date and a verification method. The method matters as much as the date: "read it" is not verification, "ran it in staging" is, and "executed during the last game day" is better. Google's [incident response practice](https://sre.google/workbook/incident-response/) and Atlassian's [incident response guidance](https://www.atlassian.com/incident-management/incident-response) both land on the same conclusion, which is that a procedure nobody has executed recently is a hypothesis rather than a procedure.

The strongest signal is execution. Run the runbook deliberately, on a schedule, in a controlled window: a game day, a failover drill, a staging exercise where somebody unfamiliar with the system follows the document literally and reports every place it lied. This is the only technique on the list that catches missing steps, because it's the only one that exercises the procedure rather than reading it.

For the rest, automate the checking. Scribelet's [AI verification](https://scribelet.app/learn/ai/ai-verification) runs background checks on a schedule you set, comparing what a note claims against current sources and returning a diff: green for what's changed, red for what no longer holds, with a link to the source for each. For a runbook, the useful source is usually your own codebase, and the [GitHub connector](https://scribelet.app/learn/ai/github-connector) points verification at your repos instead of the open web, so a step that references a renamed service or a deleted flag gets flagged against the code that actually shipped. You review the diff and accept or dismiss it. Nothing is rewritten without you seeing it.

None of that removes the need to think about your runbooks. It removes the need to *remember* to think about them, which is the part that fails. If you'd rather start manual, the same instinct scales down into [a 30-minute weekly review system](https://scribelet.app/blog/keep-notes-up-to-date) that touches the documents most likely to have drifted rather than all of them. [Point a background check at your first procedure](https://scribelet.app) and see what it finds; the free plan includes 10 verifications a month, which is enough to test the idea on the documents you trust least.

## A runbook template with an expiry built in

Most runbook templates give you sections. This one gives you sections plus the two fields that determine whether the sections are still true.

```markdown
# Runbook: [task or alert name]

**Trigger:** [the specific alert, symptom, or schedule]
**Owner:** [team, not a person]
**Verified on:** 2026-08-08 by [name], method: [executed in staging]
**Drift triggers:** [rename of X service, change to Y endpoint, Z dashboard migration]

## Preconditions
- Access required: [role, VPN, credentials]
- Confirm before starting: [system states to check]

## Steps
1. [Command]
   Expected: [observable result]
2. [Command]
   Expected: [observable result]

## Verification
- [Metric returning to baseline, queue depth, health endpoint]

## If this doesn't work
- Rollback: [how to undo the steps above]
- Escalate to: [team or rotation, not an individual]

## Known failure modes
- [Symptom] usually means [cause]. See [linked runbook].
```

Two rules make the template work. First, `verified on` only changes when someone confirms the procedure against the current system, never when someone fixes a typo. Second, drift triggers are written at the same time as the steps, while you still remember which parts of the system the procedure depends on. Trying to reconstruct them a year later is guesswork.

## The document you only read when you can't afford it to be wrong

Runbooks are the highest-stakes writing most engineering teams do, and they're treated as the lowest-status. They get written during an incident retro, committed, and never opened again until the next incident, at which point their accuracy is a matter of luck and deploy velocity.

The reframe is small. A runbook isn't a description of your system; it's a claim about your system, and claims expire. Once you treat it that way, the maintenance work becomes obvious: date the claim, write down what would falsify it, and give something the job of checking. [Keep your runbooks true before the next page](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>runbook</category>
            <category>documentation</category>
            <category>devops</category>
            <category>incident-response</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[The best Logseq alternative depends on why you're leaving]]></title>
            <link>https://scribelet.app/blog/logseq-alternative</link>
            <guid isPermaLink="false">https://scribelet.app/blog/logseq-alternative</guid>
            <pubDate>Fri, 07 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The best Logseq alternative depends on your reason: the database split, the mobile app, sync, or life inside a bullet. An honest, sorted guide. Try it free.]]></description>
            <content:encoded><![CDATA[
The top result for "logseq alternative" is a thread on Logseq's own forum called [Leaving Logseq](https://discuss.logseq.com/t/leaving-logseq-alternative-suggestions/34942). That says most of it. People don't drift away from an outliner they spent two years learning. Something specific pushed them, and they go looking for a Logseq alternative with that one thing in mind.

Every ranked list you'll find answers a question you didn't ask. Here are eight apps for linked notes, sorted by the author's preference, with the author's own product at number one. But the right replacement for someone stuck waiting on the database rewrite is not the right replacement for someone who just wants a mobile app that opens reliably, and neither of them wants what the person escaping bullet points wants.

So this guide is sorted by reason, not by rank. Each reason gets an honest best pick, and most of them aren't ours. One of them is, for a problem no other app on this list touches.

## What is a Logseq alternative?

A Logseq alternative is any note-taking app that covers what you actually used Logseq for: block-level outlining, bidirectional links between notes, a daily journal as the default capture surface, and local-first storage you control. Logseq's specific combination is unusual, so most alternatives trade one of those pillars away. Obsidian keeps local files and links but works in documents rather than blocks. Tana and Roam keep the outliner but move your data to their cloud. Knowing which pillar you can live without is the whole decision.

## Why people are leaving Logseq in 2026

Five reasons come up repeatedly, in the forum thread above, in r/NoteTaking, and in the Hacker News threads that surface whenever the project's roadmap comes up:

- **The database rewrite** moved the source of truth out of plain Markdown files.
- **The mobile app** stayed slow and awkward while the desktop app got good.
- **Sync** arrived late, stayed in beta, and pushed people onto Git or Syncthing.
- **Release pace** got slow enough that people started asking whether the project had stalled.
- **The bullet** is the only container, which is wrong for long-form writing.

Each one points at a different replacement.

### The database version split the project in two

On 13 July 2026, Logseq shipped its [2.0 beta](https://github.com/logseq/logseq/releases) and moved the canonical copy of your notes out of a folder of Markdown files and into a local SQLite database, splitting the project into two versions in the process. For a tool whose pitch was "your notes are just files in a folder," moving the source of truth into a database is not a minor release note. It changes the guarantee people chose the app for. We wrote about that specific tradeoff in [Obsidian vs Logseq](https://scribelet.app/blog/obsidian-vs-logseq), because the file question is the real fault line between the two.

### The mobile app never caught up

This is the most common practical complaint. Logseq's desktop experience is strong and its mobile app has consistently lagged: slower to open, awkward to edit in, and historically dependent on sync working perfectly to be useful at all. If you capture on your phone, you feel this every day.

### Sync was the weak link

Official sync arrived late and stayed in beta for a long time, which pushed most users onto Git, Syncthing, or iCloud. Those work until they don't, and when they don't you get conflicted copies of a graph where every block is supposed to have one canonical home.

### Development pace made people nervous

Search volume for "is logseq dead" doubled year over year. The project isn't dead, and the [Logseq GitHub repository](https://github.com/logseq/logseq) shows real ongoing activity, but long gaps between user-facing releases do something specific to trust: people stop building their working life on a tool they suspect might stall. Worth being fair here, because the lists that profit from your departure won't be. Logseq is a small open-source team attempting a full architectural rewrite in public, which is harder and more honest than shipping a rebrand. Slow is not the same as abandoned.

### Everything is a bullet

Logseq's outliner model is a genuine idea, not a limitation, and for thinking in fragments it's excellent. It's also a poor fit for long-form prose. If you're writing documents rather than accumulating thoughts, you eventually notice you're fighting the editor.

![Decision map matching each reason for leaving Logseq to a best-fit alternative: database split maps to Obsidian, mobile and sync map to Capacities or Scribelet, outliner loyalty maps to Tana or Roam, open source maps to Joplin or SiYuan, and notes that stay accurate maps to Scribelet](/blog/logseq-alternative/pick-by-reason.svg)

## Logseq alternatives, sorted by why you're leaving

| Your reason for leaving | Best pick | The tradeoff |
|---|---|---|
| You want plain Markdown files, permanently | Obsidian | Documents, not blocks. You rebuild outliner habits with plugins. |
| You want the outliner, better executed | Tana | Powerful structure, but your data lives in their cloud. |
| You want blocks plus a real mobile app | Capacities | Object-based rather than pure outlining. Paid for the good parts. |
| You want open source above all | Joplin, SiYuan, or Anytype | Rougher edges and smaller plugin ecosystems. |
| You want notes plus spaced repetition | RemNote | Study-shaped. Heavier than you need for work notes. |
| You want notes that stay accurate over time | Scribelet | Not an outliner. Blocks are not the unit. |

### If you want your files to stay files

Obsidian is the safe default and the most common destination in every thread. Your notes stay as Markdown in a folder you own, links and backlinks work, and the plugin ecosystem is large enough that outliner-style workflows are reachable if you want them. You give up native block references as a first-class primitive, and you'll spend a weekend configuring. If Obsidian is where you're heading, our guide to [markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) covers the rest of the field in the same format.

### If you want the outliner, done better

Tana is the most credible upgrade for people who genuinely think in blocks. Supertags and structured nodes give you the database-like power Logseq was reaching for, with AI built in rather than bolted on. Roam Research remains the original and still has the smoothest daily-journal loop. Both ask you to accept cloud hosting, which is precisely the thing many Logseq users chose Logseq to avoid.

### If open source is the point

If you left Logseq for reasons of principle rather than friction, staying in the free software world matters more than polish. Joplin is the mature option with strong encryption. SiYuan sits closest to a Notion and Logseq hybrid and is genuinely local-first. Anytype is the most ambitious and the least finished. All three trade smoothness for control, and if encryption is what's driving you, our breakdown of [what "secure" actually protects](https://scribelet.app/blog/secure-note-taking-app) is worth reading before you pick, because at-rest and zero-knowledge encryption mean very different things for what your notes can do afterward.

### If AI is what's missing

Logseq has no native AI, and the community plugins that add it vary in quality and maintenance. Most people leaving for this reason are choosing between bolting AI onto a local vault or moving to a tool where it's native. That decision maps almost exactly onto the one we mapped for Obsidian in [Obsidian AI](https://scribelet.app/blog/obsidian-ai), and the conclusion is the same: a plugin can answer questions about your notes, but it won't maintain them.

## What you give up by leaving

Most alternative guides are written as though the tool you're leaving had no virtues. Logseq has several, and you should know which ones you're about to lose so the regret doesn't arrive three weeks later.

You lose block-level addressability. In Logseq, any bullet anywhere is a first-class thing you can reference, embed, and query from somewhere else. Obsidian's block references exist but are clumsier, and most other apps don't have the concept at all. If you built query-driven dashboards out of block references, budget real time to rebuild them or accept that they're gone.

You lose journal-first capture. Logseq opens on today's date with the cursor blinking. That single design choice removes the "where does this go?" decision that stops people from writing things down at all. Plenty of apps have daily notes; few make them the default surface. If your capture habit depends on it, check that your replacement can be configured the same way before you commit.

You lose an outliner that never fought you about structure. Folding, zooming into a bullet, and restructuring a page by dragging one line are all instant in Logseq and merely available elsewhere. This is the piece people miss most, and it's why the honest answer for a lot of readers is Tana rather than Obsidian, even at the cost of cloud storage.

What you don't lose is your writing, provided you're on the file-based version and you take the directory with you. That was always the point of local-first, and it still holds.

## Logseq vs Obsidian, the short version

This is the comparison most people are actually running, so here it is compressed. Choose Logseq if the block is your unit of thought, journals are your capture habit, and you like outlining everything. Choose Obsidian if the file is your unit, you write in documents, you want the larger plugin and theme ecosystem, and you want a mobile app that works today. The deeper version, including what the database rewrite changes about the file guarantee, is in our full [Obsidian vs Logseq breakdown](https://scribelet.app/blog/obsidian-vs-logseq).

## What none of these alternatives fixes

Here's the part the ranked lists leave out. Every app above changes how you capture, structure, and store notes. Not one of them does anything about what happens to those notes after you write them.

Your Logseq graph has blocks in it from two years ago. Some describe an API that has since changed its auth flow. Some cite a paper that was corrected, or a pricing page that has moved twice. [Retraction Watch](https://retractionwatch.com/) documents a research retraction problem that keeps growing, and that's just the citations. Nothing in Logseq flagged any of it, and nothing in Obsidian, Tana, or Joplin will either. They show you what you captured. They stay silent on whether it's still true.

This is the reason we built Scribelet, and it's the only reason we'd put ourselves on this list. Background agents re-check your notes against current sources on a schedule you set, and when something has changed you get a diff showing what's different and why, with the source. You accept or dismiss it. Your keys, your provider, your call. This is the [step every PKM system skips](https://scribelet.app/blog/personal-knowledge-management), and migrating between apps doesn't close it. It just moves the same decaying archive somewhere nicer.

If that's the complaint underneath your search, [see what a verification diff actually looks like](https://scribelet.app).

## How to migrate off Logseq without losing the graph

A migration is the one moment your entire archive is in front of you. Use it.

1. **Export to Markdown first.** Logseq's files are already Markdown on disk if you're on the file-based version. Copy the whole graph directory before you touch anything, and keep that copy untouched as your rollback.
2. **Expect the bullets to survive as bullets.** Every block in Logseq is a list item. In a document-first app like Obsidian, your notes will land as nested lists. Budget time to flatten the pages you actually reread, and leave the rest.
3. **Accept that block references will break.** Block-level `((refs))` are Logseq-specific. Page links survive; block links usually don't. Grep your export for `((` before you migrate so you know the scale.
4. **Move journals separately.** Daily notes are usually the largest and least valuable half of a graph. Migrating them into a dated folder rather than mixing them with your reference notes keeps the new vault legible.
5. **Audit while you move.** Every note you touch, ask one question: is this still true? You will delete more than you expect. This is the only pass most archives ever get, which is exactly the problem worth fixing permanently.

## Pick the fix, not the highest-rated app

The best Logseq alternative isn't the one at the top of somebody's list. It's the one that solves the specific thing that made you open a new tab and start searching. Name the reason first and the shortlist gets short fast.

And if the reason underneath the reason is that you've now spent two years building a knowledge base you're no longer sure you can trust, moving it to a different app won't change that. [Start writing with background verification](https://scribelet.app) and let the notes check themselves. Free to start, and you bring your own API key if you want full control over the provider. Compare what's included on [our pricing page](https://scribelet.app/pricing).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>logseq-alternative</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>open-source</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[How to take smart notes (and why they stop being smart)]]></title>
            <link>https://scribelet.app/blog/how-to-take-smart-notes</link>
            <guid isPermaLink="false">https://scribelet.app/blog/how-to-take-smart-notes</guid>
            <pubDate>Thu, 06 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[How to take smart notes the way Ahrens describes, plus the failure the book skips: permanent notes quietly stop being true. Fix the last step. Try it free.]]></description>
            <content:encoded><![CDATA[
Four months ago you read the book, bought into the argument, and rebuilt your whole system around it. Fleeting notes in an inbox. Literature notes for every source. Permanent notes written in full sentences, in your own words, linked to their neighbours.

Open the box now and ask it a question. Ask it what you know about the thing you're writing this week. It probably gives you back a tidy pile of notes you already remember writing, and nothing you'd forgotten. That's the complaint underneath half the threads on r/Zettelkasten: you learned how to take smart notes, you executed the method correctly, and the slip-box still isn't talking back.

This piece covers the workflow properly, in the order it works, and then it covers the part no *how to take smart notes* summary gets to. The workflow is sound. What nobody prices in is what happens to a permanent note eighteen months after you write it, when the claim inside it has quietly stopped being true and the note is still sitting there in confident present tense, looking exactly as trustworthy as the day you distilled it.

## What is the smart notes method?

The smart notes method is a note-taking system built around three note types and one rule: you write notes for your future writing, not for your future filing. It comes from Sönke Ahrens' *How to Take Smart Notes* book (first edition 2017, second edition 2022), which reverse-engineered the working habits of the German sociologist Niklas Luhmann.

Luhmann's setup was a wooden box of index cards, a *Zettelkasten*. The [Niklas Luhmann Archive](https://niklas-luhmann-archiv.de/), which is digitising the whole thing, puts it at roughly 90,000 slips, alongside some 50 books and more than 600 articles that came out of it. He consistently credited the box rather than his own discipline. In his essay [Communicating with Slip Boxes](https://luhmann.surge.sh/communicating-with-slip-boxes), he describes it as a genuine communication partner, something that had to be able to surprise him or it wasn't worth keeping.

The three note types do different jobs:

**Fleeting notes** are the raw catch. A phrase on your phone, a thought in the margin, anything you'd lose otherwise. They're disposable by design and should be empty again within a day or two.

**Literature notes** are what you write while reading. Short, in your own words, one per idea worth keeping, always with the source attached. Ahrens is strict about the "own words" part: copying a passage feels like understanding and isn't.

**Permanent notes** are the ones that go in the box. Each holds a single developed thought, written as if for a reader who isn't you, connected to the notes it argues with or extends. These are the notes the whole system exists to produce.

The point of the distinction is that the third type costs real effort and the first two exist to make that effort possible. If you're keeping only one kind of note, you're running a filing cabinet.

Want to see what this looks like when something else handles the linking? [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) in about five minutes.

## How to take smart notes: the workflow

Here's the loop, compressed. It's less complicated than the book makes it look, and the sequence matters more than the tooling.

1. **Capture fleeting notes without judgement.** One inbox, no structure, no decisions. Anything that survives the week gets processed; the rest gets deleted without guilt.
2. **Write a literature note for each source, while you read.** In your own words, short, and with the page or link recorded. One note can hold several ideas as long as each one is separable later.
3. **Turn ideas into permanent notes the same day, or the next.** Full sentences. One idea per note. Written so that a stranger could follow it, because in two years you are that stranger.
4. **Link every new permanent note to at least one existing one.** Not by tag or folder, by argument. What does this extend, contradict, or complicate? The link is the thinking.
5. **Let the links suggest what to write.** When a cluster gets dense enough, you have a section. When several clusters connect, you have a piece. This is the payout step and it's the one people skip.
6. **Empty the fleeting inbox.** Every week, to zero.

Taking smart notes well comes down to steps 3 and 4. That's where the method earns its name. A note that says "spaced repetition works" is a fact. A note that says "spaced repetition works because retrieval difficulty, not exposure, drives retention, which is why rereading feels productive and isn't" is a thought, and it can be argued with by the note next to it.

Ahrens' own framing on [his page for the method](https://www.soenkeahrens.de/en/takesmartnotes) is that a good system is simple and keeps you focused on reading, thinking and writing. Anything you add beyond that is decoration.

### The part where most systems stall

Step 5. Almost everyone builds a beautiful box and never runs step 5, because step 5 requires an actual writing project pulling on the notes.

Luhmann's box worked because it was under constant load. He wrote every day, and writing meant pulling cards, reading them again, disagreeing with his younger self, and filing the disagreement as a new card. The box got re-read continuously as a side effect of being used. Nothing sat untouched for two years, because the work kept dragging things back into the light.

Most people adopting the method today have no equivalent load. There's no book. There's a vague intention to write more. So the notes accumulate, the graph gets prettier, and nothing ever pulls a card back out. A slip-box that is never read is a slip-box that never surprises you, and Luhmann's whole test for the thing was whether it could surprise him.

![Luhmann's slip-box, continuously pulled back open by writing projects, next to a modern one where notes only accumulate](/blog/how-to-take-smart-notes/slip-box-load.svg)

## Why permanent notes stop being true

Now the part the book doesn't cover, and the reason "permanent" is a slightly dangerous word.

A permanent note is the output of a deliberate compression. You read a source, understood it, and rewrote the idea in clean present-tense prose with the scaffolding removed. That compression is the value. It's also what strips out every signal that would let you judge the note's age later.

Think about what you deleted when you distilled. The version number. The date you read it. The hedge the author put in the third paragraph. The "as of the current release" that made the claim conditional. What's left is a sentence that reads like a principle: *Validate the token server-side before rendering.* It reads that way whether the underlying framework still works that way or not.

Compare it to the messy literature note it came from. That one has a page number, a date, a half-finished thought, and an obvious seam showing where you stopped understanding. When you reread the messy note you can tell how much to trust it. The polished one gives you nothing to go on, which is exactly why it's pleasant to reuse and exactly why reusing it can bite you.

Two ways this shows up in practice. A researcher keeps a permanent note summarising a finding from a 2019 paper; the paper is later retracted, and [Retraction Watch's database](https://retractionwatch.com/retraction-watch-database-user-guide/) has catalogued tens of thousands of retractions like it, but the note in the box doesn't know that and still states the finding flatly. An engineer distils an authentication pattern into a permanent note; two major versions later the pattern is deprecated, the note still reads like a principle, and it gets quoted into a design doc.

Neither failure is a failure of the method's writing advice. Both are failures of the same missing step: nothing in the smart notes workflow ever goes back and asks whether a filed note is still correct. Ahrens tells you how to make a note worth keeping. He doesn't tell you how to keep it worth keeping, because Luhmann never had to solve that problem. Luhmann's cards were records of his own thinking, dated by handwriting and context, read as history. Ours are full of external claims about a world that keeps moving.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay) hitting a format engineered to hide it. The same thing that makes [atomic notes](https://scribelet.app/blog/atomic-notes) reusable, one clean self-contained claim, makes each of them independently able to go wrong without any visible symptom.

![The three smart note types compressing into one clean permanent claim, and the fourth step that re-verifies it](/blog/how-to-take-smart-notes/note-types-missing-step.svg)

**Ready to see what your own box is hiding?** [Start free](https://scribelet.app) and point verification at the oldest notes you still cite.

## Smart notes vs the other systems it gets confused with

The method overlaps with several neighbours, and knowing where the seams are saves you from adopting the same idea twice.

| System | Core unit | What it optimises for | Has a maintenance step |
|---|---|---|---|
| Smart notes (Ahrens) | Permanent note | Producing writing from accumulated thought | No |
| Classic zettelkasten (Luhmann) | Index card | Surprising connections under constant use | No, but constant re-reading substituted for one |
| [Evergreen notes](https://scribelet.app/blog/evergreen-notes) (Matuschak) | Concept note | Notes that keep evolving as understanding grows | Named as a principle, unspecified in practice |
| PARA (Forte) | Folder by actionability | Fast retrieval for current projects | No |
| Commonplace book | Quotation | Collecting other people's words | No |

Every row says no in the last column, which is the observation that motivated this article. Matuschak's "evolving" principle gets closest, but it names the requirement without giving you any mechanism for noticing which of your 600 notes needs to evolve this month.

If you want the full survey of where these methods came from and how they relate, our overview of [personal knowledge management](https://scribelet.app/blog/personal-knowledge-management) walks the whole family tree. The short version: they disagree about the unit and the folder structure, and they agree entirely about stopping the moment the note is filed.

## Making smart notes that stay smart

Keep the method. All of it. The three note types are good, the "own words" rule is good, and linking by argument instead of by tag is the single best habit in the whole system. What's missing is a fourth step after "permanent," and it has two halves.

**Something has to re-read the box.** Not you, on a heroic Sunday. If step 5 depends on you having an active writing project, and you don't, then the resurfacing has to come from somewhere else. Relevance-based resurfacing, where working on a topic pulls the old notes about it back in front of you, does what Luhmann's daily writing did without requiring you to be Luhmann. That's the same gap [literature notes](https://scribelet.app/blog/literature-notes) fall into, one layer down: a note that never gets promoted and a note that never gets re-read fail for identical reasons.

**Something has to re-check the claims.** Resurfacing an outdated note only shows you the outdated note. The claims that came from outside your head, the version numbers, statistics, cited findings, and links, need to be checked against the current state of the source. Scribelet's background agents do that on a schedule you set: they search the web, compare what they find to what the note says, and show you a diff with the source cited. Green for new information, red for what no longer holds. You accept it, dismiss it, or edit, and the note goes back in the box still true. The mechanics are in the [AI verification docs](https://scribelet.app/learn/ai/ai-verification), and you choose the model and bring your own key if you'd rather your notes never touch a provider you didn't pick.

The practical version of this, if you want to start today with nothing new installed: put a `last-verified` line at the bottom of every permanent note that contains an external claim, and treat any note older than a year as unconfirmed until you check it. It's tedious and it works, which is roughly the review discipline behind [remembering what you read](https://scribelet.app/blog/how-to-remember-what-you-read) at all. Automation removes the part where you have to remember to do it.

None of this changes how you write the note. It changes how long the note stays worth having, which is the difference between a slip-box you consult and a slip-box you feel guilty about.

## The box only gets smart if it stays true

The reason Luhmann's slip-box could act like a conversation partner wasn't the index cards or the numbering scheme. It was that the box was in constant use and therefore constantly corrected, thousands of small re-readings a year, every one of them a chance to notice that a card no longer held up.

Copy the note-taking and skip the load and you've built the vocabulary of the system without the metabolism. That's why a technically perfect [zettelkasten](https://scribelet.app/blog/zettelkasten-with-ai) can go quiet in four months. Not because the notes are badly written, but because nothing is pulling them back out and nothing is checking whether they're still right.

Write the fleeting note. Write the literature note. Write the permanent note in your own words and link it to the one it argues with. Then give the box a way to read itself back and re-check what it's holding, so the note you pull out in 2028 still says something true. [Keep your smart notes worth reusing](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>smart-notes</category>
            <category>zettelkasten</category>
            <category>pkm</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Obsidian vs Logseq in 2026: the file question has a direction now]]></title>
            <link>https://scribelet.app/blog/obsidian-vs-logseq</link>
            <guid isPermaLink="false">https://scribelet.app/blog/obsidian-vs-logseq</guid>
            <pubDate>Wed, 05 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Logseq vs Obsidian, compared for late 2026: outliner vs editor, where the Logseq 2.0 database beta actually stands now, and the accuracy question neither answers. Try it free.]]></description>
            <content:encoded><![CDATA[
*Updated October 2026 with where the Logseq 2.0 database beta actually stands, and why the file-based version has gone quiet.*

Most people arrive at the Logseq vs Obsidian decision with the same shortlist logic. Both are local-first. Both keep your notes in plain Markdown on your own disk. Both are free. So the choice comes down to taste: do you think in documents or in bullets?

That was a fair summary until July. On 13 July 2026, Logseq shipped [its 2.0 beta](https://github.com/logseq/logseq/releases) and moved the canonical copy of your notes out of a folder of Markdown files and into a local SQLite database, splitting the project into two versions. Three and a half months on, the picture is clearer than it looked at launch, and not in the direction most comparisons assume: the database beta is where all the work is happening, and the file-based version has not shipped a release since December 2025.

Which means the single premise every comparison of these two apps rests on, the one that says your Logseq notes are plain files you own forever, is now the thing in question.

This is a fair comparison of both tools as they stand in late 2026: how each one actually models a note, who each is genuinely better for, what Logseq's database switch costs and buys at this point in the beta, and the dimension neither of them measures.

## Logseq vs Obsidian: which should you pick?

The full reasoning is below, but here is the short answer. Find the row that describes you and start there.

| If this is you | Pick | Why |
|---|---|---|
| You capture all day and sort later | Logseq | Journal-first, built for a running log |
| You write long-form prose | Obsidian | Prose in an outline fights you |
| Your vault will pass 10,000 notes | Obsidian | Handles scale outliners struggle with |
| You want tasks without a plugin stack | Logseq | States, scheduling, queries built in |
| Plain files you can read in 20 years are non-negotiable | Obsidian | Logseq's file version is now frozen (see below) |
| An open-source licence is a requirement | Logseq | AGPL-3.0 |
| The notes have to still be correct next year | Neither | Both stop the moment you save |

## Obsidian vs Logseq at a glance

Obsidian is a Markdown editor where the file is the unit of thought. Logseq is an outliner where the block is the unit of thought, built around a daily journal. Obsidian suits long-form writing and large vaults. Logseq suits fast capture, tasks, and dense cross-referencing.

| | Obsidian | Logseq |
|---|---|---|
| Unit of thought | The file (a note) | The block (a bullet) |
| Default entry point | A vault of folders you organize | Today's journal page |
| Storage | Plain Markdown files on your disk | Markdown files (the frozen 0.10.x line), or SQLite in the 2.0 beta |
| Linking | Wikilinks, backlinks, graph view | Wikilinks plus block-level references and embeds |
| Tasks | Plugins (Tasks, Dataview) | Built in, with states and queries |
| Extensibility | 4,300+ community plugins | Smaller plugin market, more built in |
| Licence | Proprietary, free including commercial use | Open source (AGPL-3.0) |
| Cost | Free; Sync $4/mo, Publish $8/mo (annual) | Free; sync (real-time collaboration) in alpha |
| Note maintenance | None (manual) | None (manual) |

The last row is the one nobody benchmarks, and it is the one that decides whether a three-year-old vault is an asset or a liability. More on it below.

## Where Logseq 2.0 stands now

For most of its life, Logseq's pitch to Obsidian users was: same guarantees, better thinking model. Your notes were Markdown files in a folder you controlled, and the outliner sat on top of them.

The 2.0 beta changed the bottom layer. Notes now live in a [local SQLite database](https://github.com/logseq/logseq/releases) that is the source of truth, with a DB Graph Importer to convert an existing file graph across. The database unlocks things files made painful: typed properties, faster queries on large graphs, and a credible path to real-time collaboration.

It also gives up the property that made Logseq an easy recommendation. A SQLite file is not a folder of documents you can grep, diff, or open in any editor for the next twenty years. The team is explicit that this is a beta and tells you to back up your graph before testing.

The part worth updating since launch is the pace. The database version is still in beta in late 2026: the latest numbered desktop release is 2.0.2 (October 2026), the newest build on top of it is a nightly the project itself labels unstable, and sync and the rebuilt mobile app are still in alpha. None of that is alarming for a young rewrite, but "beta with a back-up-your-data warning" is the honest status, not a finished product.

The more telling fact is the other branch. When Logseq split into two versions, the assumption was that the file-based app would keep going for people who wanted it. In practice it has not shipped a release since December 2025. So the choice is not really between two actively developed versions. It is between a database beta that gets all the attention and a file-based version, now nicknamed Logseq OG, that is effectively frozen.

That tilts the two readings the launch left open. The optimistic one still holds: files were holding the product back, and a database is the right foundation for what Logseq wants to be. But the cautious one got stronger. The reason many people chose Logseq over Notion was the plain-text guarantee, and that guarantee now lives on the branch nobody is updating, while the future lives in a beta. If plain text is the reason you are shortlisting either app, that is worth weighing directly, because [plain text keeps notes portable, not accurate](https://scribelet.app/blog/markdown-note-taking-apps), and portability is only half of what people think they are buying.

> **Practical read for late 2026**: Logseq's direction is the database, and the file version is standing still. If you choose Logseq today, choose it for the outliner and the open-source licence, not for a plain-text promise that is quietly being left behind.

## What is the difference between Logseq and Obsidian?

Logseq is an outliner: every note is a tree of indented blocks, each block is individually addressable, and the app opens on today's journal. Obsidian is a document editor: every note is a whole Markdown file you write into freely, and the app opens on whatever you left open.

Everything else follows from that one choice.

Because a Logseq block has an identity, you can reference or embed a single bullet somewhere else and it stays live. That makes Logseq unusually good at accumulating a thought across many days without copy-paste. Because an Obsidian note is a file, it behaves like every other file on your computer: version control works, sync works, and any tool that reads text can read it.

The same split explains the friction each one causes. Long-form prose inside a bullet outline fights you. And a blank Obsidian vault gives you no opinion at all about where anything should go.

![Diagram contrasting Obsidian's file as the unit of thought with Logseq's block-level outline anchored to a daily journal](/blog/obsidian-vs-logseq/file-vs-block.svg)

## Where Logseq wins

Logseq is the better tool when capture speed matters more than composition.

The journal-first design removes the daily "where does this go?" tax. You open the app, you are already on today's page, and you type. Filing happens later through tags and references, or never, which is fine because block references let you pull the thought into the right context afterwards. This is the closest thing in mainstream PKM to a running log that actually gets used, which is also its risk: a log that nobody reads back is [the log nobody reads back](https://scribelet.app/blog/interstitial-journaling), no matter how quickly you filled it.

Tasks are built in rather than assembled. States, scheduling, and queries work out of the box, where Obsidian needs a plugin stack and a Dataview query you will maintain yourself. Flashcards and PDF highlighting ship natively too.

And it is genuinely open source under AGPL-3.0, which matters if licence terms are part of your threat model rather than a detail.

> **Choose Logseq** if you think in bullets, capture constantly through the day, want tasks and references without assembling a plugin stack, and want an open-source licence.

## Where Obsidian wins

Obsidian is the better tool when your notes need to outlive your enthusiasm for note-taking.

Files are the reason. A vault is a folder, so backups, Git, and any sync service you already trust work without the app's cooperation, and a note stays readable if the company disappears. Obsidian handles vaults in the tens of thousands of notes without the slowdown outliners tend to hit, and long-form drafting in a file simply feels better than drafting in an outline.

The plugin ecosystem is the other half, with over 4,300 community plugins, plus Bases for database-style views without leaving the file model. Pricing is straightforward: the app is [free, including commercial use](https://obsidian.md/pricing), with Sync at $4/month and Publish at $8/month on annual billing.

The costs are real and Obsidian's fans understate them. You own the setup and the upkeep. Sync across devices is a paid add-on or a project. There is no native AI, and every option for adding it is a plugin or an external agent you wire up yourself, which we cover in [every way to add AI to Obsidian](https://scribelet.app/blog/obsidian-ai). If Obsidian is already the incumbent and you are here because something specific broke, [Obsidian alternatives sorted by reason](https://scribelet.app/blog/obsidian-alternative) is the more useful question than this one.

> **Choose Obsidian** if you write long-form, expect a large vault, want files you can back up and read anywhere, and are happy trading setup effort for control.

## What are Logseq's disadvantages?

Three, and the first one is new.

**The transition risk.** The 2.0 database beta is the project's future, and it is a beta with a back-up-your-data warning. The file-based app was meant to continue on its own track, but it has not shipped a release since December 2025, so the split in practice is one active beta and one static version. Choosing Logseq today means betting on the beta or settling for a branch nobody is updating.

**Everything is an outline.** Block-level structure is a real advantage until you need to write four paragraphs of continuous prose, at which point the indentation is working against you.

**A smaller ecosystem.** Fewer plugins, fewer themes, fewer people to answer your question. Logseq builds more in the core, which is a coherent strategy, but it means fewer escape hatches when your workflow does not fit. On the Obsidian side, [the community plugins worth installing](https://scribelet.app/blog/best-obsidian-plugins) are a short list, not the whole catalog.

For balance, Obsidian's mirror-image disadvantages are the blank-vault problem, no native tasks or AI, paid sync, and a proprietary (if generously licensed) codebase.

## The row neither of them fills

Here is what the whole Obsidian vs Logseq argument is about: structure. Blocks against files, outline against document, database against folder. It is a real question and both answers are respectable.

It is also a question about how notes are *stored*, and nobody is asking what happens to what is *inside* them.

Your note on a framework's auth flow was accurate the Tuesday you wrote it. The library shipped a major version in March. The Stack Overflow answer you leaned on has a correction now, and the doc you linked returns a 404. Neither app has any concept of that. A block reference points just as confidently at a stale claim as a current one, and a graph view renders a beautiful web of things that may no longer be true. This is [why notes go stale](https://scribelet.app/blog/knowledge-decay) in every system, regardless of how well it is organized, and it is the step [every PKM system skips](https://scribelet.app/blog/personal-knowledge-management).

Both tools are excellent at capture, structure, and retrieval. Both stop the moment the note is saved. The upkeep is yours, forever, and in practice that means it does not happen.

![Diagram showing capture, organize and retrieve handled by both apps, with the maintenance step after saving left empty in each](/blog/obsidian-vs-logseq/maintenance-gap.svg)

That gap is what Scribelet was built for. Background agents re-check the claims in your notes against the web on a schedule you set, and when something has moved you get a diff: what you wrote, what changed, and the source, to accept or dismiss. Nothing is rewritten behind your back. You can see [how verification works](https://scribelet.app/learn/ai/ai-verification) before deciding whether it belongs in your setup.

## So which should you pick?

If you are choosing between these two on the merits, the honest rule still holds. Run down this list and take the first line that describes you:

1. **You capture all day and sort later**: Logseq. The journal-first design is built for exactly this.
2. **You write long-form**: Obsidian. Prose in an outline fights you every paragraph.
3. **Your vault will pass 10,000 notes**: Obsidian. It handles scale that outliners struggle with.
4. **You want tasks without assembling plugins**: Logseq. States and queries are built in.
5. **Plain files are non-negotiable**: Obsidian. Logseq's plain-text version is the frozen branch now, and its future is the database, so the file guarantee is the weaker bet of the two. If that is pushing you off Logseq entirely rather than toward Obsidian specifically, we sorted [the Logseq alternatives by the reason people leave](https://scribelet.app/blog/logseq-alternative).
6. **An open-source licence is a requirement**: Logseq, AGPL-3.0.
7. **You want the notes to still be right in a year**: neither, and that is the rest of this section.

If you are choosing a note app to hold work that has to stay correct, both leave you with the same job. They organize what you wrote; they never revisit it. That is the same conclusion we reached comparing two very different tools in [an honest Notion vs Obsidian breakdown](https://scribelet.app/blog/notion-vs-obsidian) and again in [Obsidian vs OneNote](https://scribelet.app/blog/obsidian-vs-onenote), which suggests the gap is in the category rather than in any one app.

Structure is a solved problem. Accuracy is not.

Scribelet keeps the parts both tools do well, linked notes you own, and adds the part neither does: AI that checks whether what you wrote is still true. Start free, and see your first diff.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>obsidian-vs-logseq</category>
            <category>comparison</category>
            <category>obsidian</category>
            <category>logseq</category>
            <category>note-taking</category>
            <category>personal-knowledge-management</category>
        </item>
        <item>
            <title><![CDATA[Atomic notes: the maintenance bill nobody mentions]]></title>
            <link>https://scribelet.app/blog/atomic-notes</link>
            <guid isPermaLink="false">https://scribelet.app/blog/atomic-notes</guid>
            <pubDate>Tue, 04 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Atomic notes give you one idea per note and 400 claims that can quietly go stale. Here is the upkeep the method never priced in, and how to automate it. Try it free.]]></description>
            <content:encoded><![CDATA[
You did the work. You stopped dumping whole book summaries into one file and started splitting your reading into single ideas, each one titled like a claim, each one small enough to read in fifteen seconds. Four hundred notes later, your graph looks like the diagrams in every PKM guide you have ever read.

Now open the twelve oldest ones. Not the graph, the notes themselves. How many have been edited since the day they were written? How many cite a version number, a statistic, or a link that you have checked even once since?

That is the part the method never mentions. Atomic notes are an excellent way to write. They are also a decision to break your knowledge into hundreds of small, independent, confidently worded claims, each of which can go out of date on its own schedule, without telling you. Granularity is a writing choice. What it does to your collection over the following year is a maintenance problem, and nobody hands you a plan for that.

## What is an atomic note?

An atomic note is a note that contains exactly one idea, written in your own words, and understandable on its own without the source it came from. That is the whole definition. One note, one concept, self-contained, and titled clearly enough that you can find and link it later.

The principle comes out of the zettelkasten tradition. [Zettelkasten.de's guide to atomicity](https://zettelkasten.de/atomicity/guide/) frames the purpose plainly: an atomic note exists to zero in and create a close-up of a single idea, while structure notes provide the higher-level view. Andy Matuschak makes the same requirement of his own system in [Evergreen notes should be atomic](https://notes.andymatuschak.org/zNUaiGAXp21eorsER1Jm9yU), where notes are kept short and highly focused so they can be read on the spot and reused freely.

The argument for it is straightforward. A note about one idea can be linked from anywhere that idea comes up. A note about eleven ideas can only be linked from a place where all eleven matter, which is nowhere. Atomicity is what makes a knowledge graph combinatorial instead of a filing cabinet with prettier labels.

So the advice is good. It is just incomplete, and you can [try the missing half free](https://scribelet.app) if you would rather not read the argument first.

## Atomic notes vs zettelkasten permanent notes

People coming from a classic zettelkasten ask where atomic notes fit, and the answer explains a lot about why the collection ages the way it does.

Atomicity is a property, not a note type. In Sönke Ahrens' three-type model, [literature notes](https://scribelet.app/blog/literature-notes) capture what a source said, and permanent notes carry your own developed thought into [the slip-box](https://scribelet.app/blog/zettelkasten-with-ai). Atomicity is the rule you apply when promoting something into that permanent layer: one idea per card, or the card cannot be filed cleanly.

The consequence is that a classic permanent note is finished on purpose. Luhmann's slip-box grew by writing new notes that responded to old ones, not by editing the old ones. Staleness was baked into the contract, so an old card was read as a record of what you thought in 1974, not as a claim about the world today.

Modern atomic notes quietly dropped that contract while keeping the format. Practitioners in the [Obsidian community](https://forum.obsidian.md/t/debating-the-usefulness-of-atomic-notes-a-novel-pragmatic-obsidian-based-approach-to-pkm-strategies/38077) and on r/Zettelkasten have argued for years about whether atomic notes are worth the friction, with one widely read thread titled simply "Atomic notes are a trap." The complaints are usually about granularity: notes so small they lose context, hours lost to splitting, a graph that grows faster than your understanding.

The granularity critics are aiming at the wrong target. Splitting ideas finely is not the trap. The trap is that you now have four hundred independent assertions, each presented as settled, with no mechanism anywhere in the method for checking whether any of them are still true.

![Diagram comparing one long note holding ten claims against ten atomic notes, showing that atomicity multiplies the number of independently decaying claims](/blog/atomic-notes/atomic-decay-surface.svg)

## Atomicity multiplies your decay surface

Here is the arithmetic nobody runs before adopting the method.

Write one long note on a framework's authentication design and you have a single artifact holding ten claims. It is hard to link and hard to reuse, which is exactly why you were told to split it. Split it properly and you now have ten atomic notes: one on session validation, one on token lifetimes, one on the middleware order, one on rate limits, and so on. Each is linkable. Each is reusable. Each is also its own independently decaying object with its own version number, its own source link, and its own expiry date that you were never told.

Your decay surface just went up by an order of magnitude, and the tooling that helped you split the note gave you nothing to watch the pieces with. This is [knowledge decay](https://scribelet.app/blog/knowledge-decay) applied to a format that is unusually good at hiding it. The graph keeps looking healthy because graphs measure connections, not accuracy. A note with eleven backlinks and a dead source link renders exactly like a note with eleven backlinks and a live one.

It gets worse as the collection grows, because the rate at which claims go stale scales with how many claims you have, while the rate at which you personally revisit notes stays flat. Somewhere past a few hundred notes, those two lines cross. After that, your collection is decaying faster than you can possibly read it, which is the point where most people quietly stop trusting their own system and start googling things they already wrote down.

## Why a stale atomic note is more dangerous than a stale long one

The defining virtue of an atomic note is that it stands alone. That is also what makes it dangerous when it is wrong.

A long, messy note carries its own context. Dates, a half-finished thought, a "check this later" scrawled at the bottom, the surrounding paragraphs that make it obvious you were writing about version 4. When you reread it, all that context tells you how much to trust it. You can see the seams.

An atomic note has been deliberately stripped of exactly that. It says one thing, cleanly, in the present tense: "Validate sessions server-side before rendering." No hedging, no date, no visible age. It reads like a principle. Six months after the framework deprecated that middleware order, it still reads like a principle, and now it is teaching you a pattern that will fail in code review. The polish you added when you distilled it is doing active harm, because the note no longer looks like a snapshot from a specific afternoon. It looks like a fact.

This is the same failure mode [evergreen notes](https://scribelet.app/blog/evergreen-notes) run into, and for the same reason. The format's authority outlives the accuracy of its contents. The better you wrote the note, the more convincingly it lies to you later.

Consider a concrete atomic notes example. A researcher keeps a note titled "SSRI response rates plateau after eight weeks," distilled from a meta-analysis, linked from six project notes. The meta-analysis is later corrected. The note does not change, because nothing in any atomic-note workflow ever revisits a note after it is filed. It keeps feeding six downstream project notes a claim that its own source has walked back. Nobody notices, because noticing was never anybody's job.

## What an atomic collection actually needs

Strip away the tooling arguments and the upkeep an atomic collection needs is short. It needs three things done to every note, repeatedly, on no particular occasion.

Notes need to be **resurfaced**. An atomic note's whole value is being reusable in a future context, but reuse depends on the note showing up when that context arrives. If it only surfaces when you go looking, you will only ever reuse the notes you already remember writing, which is a small and shrinking fraction of the collection.

Claims need to be **re-checked against the world**. Every atomic note points outward at something: a version, a number, a study, a link. Those move. Keeping a collection trustworthy means periodically comparing what each note asserts against what is currently true, and seeing the difference rather than assuming there isn't one.

Notes need to be **re-linked** as the graph grows. A note written when you had 80 notes is under-connected once you have 400, because the adjacent ideas that should link to it arrived later. Dense linking is treated as a one-time act at creation. It decays like everything else.

This is the gap [every PKM method leaves open](https://scribelet.app/blog/personal-knowledge-management), and atomicity widens it: the finer you slice, the more objects there are to keep honest.

None of this is intellectually hard. It is relentless, and relentless is the specific thing humans are worst at and software is best at. The reason your atomic notes stopped evolving is not that you lack discipline. It is that the method assigned you a cron job and called it a habit. You can hand that job to something built for it and [see your first diff](https://scribelet.app).

## Automating the upkeep atomic notes assume

If a collection is going to be split into hundreds of independent claims, something other than your memory has to keep track of those claims. That is the layer Scribelet is built to be.

[Background verification](https://scribelet.app/learn/ai/ai-verification) checks a note's factual claims against the web on a schedule you set, then shows you a diff: green for what is new, red for what is now outdated, with the source that changed. You accept or dismiss, and the note updates. For an atomic collection this matters more than for any other format, because it scales the way the problem does. Checking four hundred small claims is a worse job for a person than checking forty large ones, and a better one for a background agent.

An auto-linker watches the graph and proposes connections a note could not have had when you wrote it, which keeps [wikilinks and backlinks](https://scribelet.app/learn/notes/wikilinks-backlinks) current with the collection instead of frozen at creation. A stale checker flags notes related to your recent work that have not been touched in months, which is the resurfacing trigger the method never supplied. If you prefer to drive it by hand, [a thirty-minute weekly review](https://scribelet.app/blog/keep-notes-up-to-date) does the same job manually. The background version does it while you are writing the next note.

Because this is AI touching your notes, control is part of the design. Scribelet works out of the box, and bringing your own OpenAI, Anthropic, or Gemini key is the optional path if you would rather your notes were checked by a provider you picked. Either way, every change arrives as a diff you approve before it lands. Nothing rewrites your thinking behind your back.

This is also the honest answer to the "atomic notes are a trap" argument. The friction people complain about is real, but the fix is not writing bigger notes. It is making the small ones cheap to maintain.

## Approaches to atomic notes, compared

Every approach here produces good notes on the day you write them. The difference shows up in year two.

| Approach | Notes are linkable | Resurfaces old notes | Keeps claims accurate | Holds up past ~300 notes |
|---|---|---|---|---|
| Long-form notes | Rarely, too coarse to link | No | No, but context reveals age | Yes, few notes to track |
| Manual atomic discipline | Yes | Only when you remember | No, nothing rechecks claims | Revisiting stalls first |
| Atomic plus a weekly review | Yes | Partly, on a fixed cadence | Only what you sample by hand | Coverage thins as it grows |
| Atomic plus background agents | Yes | Yes, by relevance and schedule | Yes, re-checked against sources | Yes, upkeep scales with agents |

The first three rows are where every guide on the method stops. The last row is the difference between a collection you keep and a collection you abandon.

## Atomicity is a writing principle, not a maintenance plan

Splitting your knowledge into single ideas is still the right call. It makes notes reusable, it forces you to actually understand what you read, and it is the only way a knowledge graph becomes more than decoration. Keep doing it.

Just be honest about what you bought. Every note you split off is another claim with its own expiry date, written in a format engineered to sound settled and to hide its age. Four hundred atomic notes is four hundred small promises about the world, and the method that talked you into making them has nothing to say about keeping them.

Write the note atomic. Then let something resurface it, re-check it, and re-link it, so the note you reach for next year still says something true. [Keep your atomic notes worth reusing](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>atomic-notes</category>
            <category>zettelkasten</category>
            <category>pkm</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Notion alternatives, sorted by what actually broke]]></title>
            <link>https://scribelet.app/blog/notion-alternative</link>
            <guid isPermaLink="false">https://scribelet.app/blog/notion-alternative</guid>
            <pubDate>Tue, 04 Aug 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The best Notion alternative depends on what broke: speed, AI everywhere, lock-in, or notes that quietly went stale. Honest picks for each reason. Try it free.]]></description>
            <content:encoded><![CDATA[
Nobody wakes up wanting a Notion alternative. Something specific sent you to the search bar. Maybe a page has been loading for thirty seconds and you're staring at a skeleton loader for the fourth time today. Maybe you opened the app and found AI offering to write things you didn't ask it to write. Maybe you built a gorgeous interlocking system of databases two years ago and haven't opened most of it since.

Here's what every "best Notion alternative" list gets wrong. They rank nine apps by popularity and leave you to work out which one fixes your actual complaint. The right pick for someone fleeing an AI-everywhere workspace is useless to someone who needs their team wiki self-hosted, or to someone whose real problem is that the workspace still works fine and the information inside it stopped being true.

So this guide is sorted by the reason you're leaving. We name the honest best pick for each one, including several that aren't ours. And we're upfront that one of them is ours, for a reason no other app on this list covers.

## What is a Notion alternative?

A Notion alternative is any tool that replaces some part of what Notion bundles together: a block-based document editor, relational databases, a team wiki, a project tracker, and lately an AI assistant. Because Notion is five products in a trench coat, there is no single replacement. The useful question is not "what is the best Notion alternative" but "which of those five things was I actually using, and what broke?"

That reframing is the whole guide. Answer it and the field narrows from thirty apps to about two.

## What actually pushes people off Notion

Spend ten minutes in [any Notion alternatives thread](https://www.reddit.com/r/productivity/comments/1n7ns8g/whos_still_using_notion_and_who_found_an/) and the same complaints repeat. They sort into four reasons, and the right alternative is completely different for each.

**It got slow.** Notion is a web app rendering blocks over the network, and the weight shows once your workspace is real. Pages that used to open instantly now hesitate. Search stalls. On a plane or a bad connection, a tool you rely on for everything becomes a spinner. This is the single most common complaint, and it is not something a workaround fixes.

**It became an AI workspace.** Notion repositioned hard around AI, and a real share of users did not ask for that. The queries tell the story: people search for `notion alternative without ai` and `notion alternative no ai` by name. If you want a quiet document tool and your document tool now suggests, drafts, and summarizes by default, that is a legitimate reason to leave.

**You don't own any of it.** Everything lives in Notion's cloud, in Notion's format. Export exists, but what comes out is a lossy approximation of the databases and relations you built. For anyone who wants self-hosting, offline access, or notes a vendor cannot read, that is disqualifying.

**You built a system instead of a knowledge base.** This is the reason that never makes the listicles. Notion is exceptionally good at helping you design structure, which is why so many people spend a weekend building an immaculate second brain and then quietly stop using it. The databases still look beautiful. Nothing in them has been checked in two years.

![Decision map matching each reason for leaving Notion to a best-fit tool: it got slow maps to Obsidian or Anytype, AI everywhere maps to AppFlowy or a markdown app, you don't own it maps to self-hosted AFFiNE or Docmost, and the contents went stale maps to Scribelet](/blog/notion-alternative/pick-by-reason.svg)

> **Notes that check themselves.** If your Notion workspace looks fine but you no longer trust what's in it, Scribelet runs background verification against live sources and shows you the diff. [Start free](https://scribelet.app) and point it at your worst page.

## If Notion got slow and heavy

This is the quiet majority, and the fix is a fundamentally lighter architecture rather than a better-optimized clone.

Obsidian is the usual landing spot. It reads and writes plain Markdown files on your own disk, so opening a note is a file read rather than a network round trip, and it stays fast at ten thousand notes. You trade Notion's databases for links, backlinks, and a graph. The cost is that you become the administrator of your own setup, and paid sync surprises some people. Our [Notion vs Obsidian comparison](https://scribelet.app/blog/notion-vs-obsidian) goes deeper on which one suits which brain.

Anytype is the closest thing to a like-for-like swap. It keeps Notion's block-and-object model, including relations, but stores everything locally and syncs peer to peer with end-to-end encryption. If you liked how Notion worked and hated where it ran, this is the shortest migration.

Capacities sits between the two, organizing by object type rather than folders, with a noticeably snappier editor than Notion's.

If you lean Obsidian-shaped but aren't sure it's the one, [Obsidian alternatives sorted by reason](https://scribelet.app/blog/obsidian-alternative) covers the same exercise for that app. And if you are still weighing the incumbents rather than ready to leave, [how Notion stacks up against OneNote](https://scribelet.app/blog/notion-vs-onenote) breaks down the structure-versus-canvas choice before you commit.

## If you don't want an AI workspace

The honest answer here is that most of the mainstream options are moving the same direction, so pick for the default rather than the feature list. What matters is whether AI is opt-in and out of the way, or on by default and in the editor.

AppFlowy is the strongest pick. It is open source, local-first, deliberately Notion-shaped, and its AI is something you switch on rather than something that greets you. AFFiNE is the other serious candidate, combining docs with an infinite canvas, also open source.

Below those, a plain Markdown editor removes the question entirely. There is no assistant because there is no platform. Our roundup of the [best markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) weighs each on portability and lock-in.

One distinction worth making before you flee the category: "AI in a note app" describes two very different things. Reactive AI drafts and summarizes when you prompt it, which is the kind most people are tired of. Proactive AI checks whether what you already wrote is still true, which nobody is tired of because almost nothing does it. Rejecting the first is reasonable. Rejecting the second means keeping the maintenance work yourself.

## If you want it open source or self-hosted

`open source notion alternative` and `self-hosted notion alternative` are among the highest-intent searches in this whole cluster, and the ecosystem here is genuinely good.

AppFlowy and AFFiNE both self-host. For a team wiki specifically, Docmost and Outline are purpose-built and considerably lighter than running a Notion clone. [It's FOSS keeps a maintained list](https://itsfoss.com/notion-alternatives/) of the privacy-focused options if you want to compare them side by side. If your requirement is really "my notes, my server, forever", Joplin with a self-hosted sync target is the least exciting and most durable answer.

Self-hosting solves ownership completely. It is worth being clear that it solves nothing else. A note you host yourself goes out of date on exactly the same schedule as a note in someone else's cloud.

## If you want notes a vendor cannot read

If the driver is confidentiality rather than ownership, you want zero-knowledge encryption, not self-hosting. Standard Notes and Notesnook both encrypt end to end, so the company hosting your notes cannot open them.

Before you commit, know the tradeoff you are buying. We laid out [which secure note app fits your threat model](https://scribelet.app/blog/secure-note-taking-app) in detail. The short version: zero-knowledge apps win on privacy precisely because they cannot read your notes, which is also why they cannot run any AI over them. You are choosing between an app that cannot see your notes and an app that can help you with them. That is a real fork, and worth taking on purpose rather than by accident.

## If you built a beautiful system and the contents went stale

Here is the reason that doesn't make the listicles, and the one Scribelet is built for.

Notion is a superb tool for designing structure. It is not a tool for maintaining truth. Every database, every linked relation, every carefully templated page shows you what you captured and tells you nothing about whether any of it is still accurate. The API you documented shipped a breaking change. The pricing you noted went up. The article you summarized was updated, or retracted. Notion renders all of it exactly as confidently as the day you wrote it.

That is not a Notion flaw specifically. It is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and it happens in every app, which is why switching apps never fixes it. It is also the step every framework leaves out, as we argue in [personal knowledge management is missing a step](https://scribelet.app/blog/personal-knowledge-management).

Scribelet adds the layer none of the others have. Background agents search the web on a schedule you set, compare what they find against what you wrote, and surface the difference as a diff: green for new information, red for what is outdated, with a source link on every change. You accept or reject each one. That is [how background verification works](https://scribelet.app/learn/ai/ai-verification).

Picture a research note you dropped into Notion two years ago citing a study that has since been retracted. According to [Retraction Watch](https://retractionwatch.com/), paper retractions have grown roughly tenfold since 2000, so this is not a rare edge case. In Notion the page still looks immaculate. With scheduled verification, the retraction arrives as a diff before you build on it again. Students run into the same decay in lecture notes and readings, which our guide to [which note app fits how you study](https://scribelet.app/blog/best-note-taking-app-for-students) covers for coursework.

You keep control of the AI itself. [Bring your own key](https://scribelet.app/blog/byok-ai) and route through OpenAI, Anthropic, or Gemini, with the key encrypted at rest. It is optional; the AI works out of the box, and the free plan includes ten verifications a month, which is enough to point at your ugliest Notion export before paying anything.

![Comparison of reactive AI, which only answers when you prompt it, and proactive verification, which searches the web on a schedule, checks your note against what it finds, and surfaces a diff for review](/blog/notion-alternative/reactive-vs-proactive.svg)

The honest tradeoff: Scribelet is not a project tracker, it has no relational databases, and it will not run your company's roadmap. If what you use Notion for is genuinely project management, ClickUp or Linear will serve you far better. Scribelet is for the notes half, and specifically for keeping that half true.

> **Stop being your own fact-checking department.** Start free, run one verification on your stalest page, and see what a diff actually catches. The [Pro plan](https://scribelet.app/pricing) is $8/mo or $79/yr when you want the full set.

## Comparison at a glance

| Alternative | Best for | Self-host | AI default | Keeps notes accurate |
|---|---|---|---|---|
| Obsidian | Speed, local Markdown, linking | Files are yours | None built in | No |
| Anytype | Closest Notion-shaped swap | Local-first, P2P sync | None built in | No |
| AppFlowy | Open source, AI kept opt-in | Yes | Opt-in | No |
| AFFiNE | Docs plus infinite canvas | Yes | Opt-in | No |
| Docmost / Outline | Team wiki, lighter than Notion | Yes | Minimal | No |
| Standard Notes / Notesnook | Zero-knowledge privacy | Notesnook: yes | None possible | No |
| Scribelet | Notes that stay true | No | Proactive verification | Yes |

## What Notion is still genuinely good at

It would be dishonest to write two thousand words on leaving without saying this. Notion remains the best tool in the category at one specific thing: letting a non-technical person build a relational system without writing code. Databases, linked relations, rollups, and filtered views are still unmatched by any app above. Team adoption is trivial because everyone already knows it.

If that is what you use it for, the correct move is probably not to leave. It is to stop asking Notion to be your knowledge base as well as your workspace, and to let something else own the notes that need to stay accurate.

## Is there a good free Notion alternative?

Yes, and this is one of the few categories where free is not a compromise. AppFlowy, AFFiNE, Obsidian for personal use, and Joplin are all free and, for most individuals, permanently sufficient. The paid tier usually buys hosted sync rather than features. If `free alternative to notion` is what brought you here, start with AppFlowy if you want Notion's shape and Obsidian if you want speed.

## Pick for the reason, not the ranking

Every list will tell you Coda, Obsidian, and Anytype. They are not wrong. They are just answering a question you did not ask.

If Notion got slow, go local: Obsidian or Anytype. If you want the AI out of your editor, go AppFlowy. If you want to own the server, self-host AFFiNE or Docmost. If you want notes nobody can read, take zero-knowledge and accept the tradeoff.

And if the workspace was never the problem, because it still works and you simply stopped trusting what's inside it, no amount of migration will help. That one needs a tool that checks. [Try Scribelet free](https://scribelet.app) and start with the page you'd be most embarrassed to have someone fact-check.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>notion-alternative</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>knowledge-decay</category>
            <category>privacy</category>
        </item>
        <item>
            <title><![CDATA[Internal documentation: nobody owns the second draft]]></title>
            <link>https://scribelet.app/blog/internal-documentation</link>
            <guid isPermaLink="false">https://scribelet.app/blog/internal-documentation</guid>
            <pubDate>Tue, 28 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Internal documentation fails months later, when nobody owns the update. Types, a copy-paste template, and a maintenance layer that keeps it true. Try it free.]]></description>
            <content:encoded><![CDATA[
Your company has more internal documentation than anyone will admit. There is a wiki three migrations deep, a Notion workspace nobody has pruned since the last reorg, and onboarding guides written with real care by people who have since left. The problem was never the writing. It is that the writing describes a company that no longer exists, and noticing was nobody's job.

You have probably concluded the fix is writing more of it. It isn't. Almost every team that complains about internal documentation has plenty. What they lack is the second draft: the update that has to arrive after the system changes, and that nobody owns.

This guide covers what internal documentation is, the types worth separating, what to document and what to skip, a page template you can paste in today, why it decays on a schedule set by your deploy pipeline rather than your writing habits, and what a maintenance layer looks like in practice.

## What is internal documentation?

Internal documentation is the written record an organization keeps for its own people rather than its customers: runbooks, onboarding guides, architecture notes, standard operating procedures, decision records, the [definition-of-done checklist](/blog/definition-of-done) a team holds itself to, and the service docs that explain one team's system to everybody else, which exist at all because [your architecture ends up shaped like your team structure](https://scribelet.app/blog/conways-law). It is the knowledge a company would have to rediscover if everyone quit on the same day. The narrower version of that risk, when one critical system depends on one person, is [your team's bus factor](/blog/bus-factor), and internal documentation is one of the few levers that reliably raises it.

External documentation is the opposite audience. API references, help centers, and release notes are written for customers. The difference that matters is not tone. It's feedback. External docs have users who file a ticket when something is wrong. Internal docs have colleagues who quietly work around the error and tell nobody.

That silence is the whole problem. A wrong page in your help center generates a support queue. A wrong page in your wiki generates a Slack thread at 2 a.m. and no edit.

## The types of internal documentation

Search engines surface a lot of "three types" and "four types" lists for this term, and they mostly describe the same buckets under different counts. The distinction worth keeping is not how many buckets there are. It is which documents are meant to last and which are written to be thrown away.

| Type | What it covers | Lifespan | Who reads it |
|---|---|---|---|
| Process docs / SOPs | How recurring work gets done: release checklists, on-call rotation, expense approvals | Durable, edited often | Whoever runs the process next |
| Onboarding docs | How a new hire gets productive without asking six people | Durable, decays silently | Each new hire, once |
| Runbooks and playbooks | Step-by-step operational procedures for a specific failure | Durable, read under pressure | On-call, at the worst moment |
| Architecture and decision records | Why the system is shaped the way it is | Durable, append-only | Anyone proposing a change |
| Specs and design docs | What a change is supposed to do before it ships | Disposable, expires at merge | The three people building it |
| Team docs | Goals, roles, ways of working | Durable, changes on reorg | The team and its neighbors |

The buckets are fine. They describe what to write, which is the part teams are already reasonably good at. Search for how to write technical documentation and you'll find a thousand competent answers. Search for how to keep it true and the advice thins out fast.

They also flatten a distinction that costs teams real time. Some of these documents are meant to last and some are not. [A design doc is written to be discarded](https://scribelet.app/blog/software-design-document) once the code ships, and treating it as a permanent wiki page is how durable content ends up in a disposable container. Specs sit in the same category: [the three readers a spec has](https://scribelet.app/blog/technical-spec) want incompatible things from it, and only one of them is still around a year later, which is why a shipped spec left in the wiki gets read as documentation long after it stopped describing anything.

If you want the shortest version of the quality checklist people quote as the "5 C's," it is this: documentation should be clear, concise, correct, complete, and current. Four of those five are properties you can get right on the day you publish, though "clear" is sneakier than it looks: a draft always reads as clear to the person who wrote it, which is [why experts write documentation nobody can follow](/blog/curse-of-knowledge). The fifth, current, is the one this entire piece is about, because it is the only one that decays on its own after you close the tab.

## What to document, and what to skip

The instinct after reading a best-practices post is to document everything. That produces a wiki so large nobody trusts any single page, which is the same failure as documenting nothing. The useful filter is whether a piece of knowledge is stable, load-bearing, and expensive to rediscover.

| Document it | Skip it (or put it elsewhere) |
|---|---|
| Steps only one person currently knows | Anything already enforced by code or CI |
| Procedures run under pressure (incidents, releases) | One-off decisions with no future reader |
| The reason behind a non-obvious choice | Meeting notes that will never be reopened |
| Interfaces other teams depend on | A screenshot-heavy walkthrough of a UI that ships weekly |
| Setup a new hire needs in week one | Personal scratch notes and drafts |
| Anything whose absence caused an incident | Content the vendor's own docs already own and maintain |

The right-hand column matters more than the left. Every entry there is a page that will go stale faster than anyone updates it, generate false confidence while it does, and dilute the pages that were worth keeping. A smaller set of documents that stay true beats an exhaustive set where half the pages are quietly wrong.

## A copy-pasteable internal documentation page template

Most templates you'll find online are about consistency of formatting. This one is about survival. The two fields at the top, Last verified and Drift triggers, are the ones almost no wiki has, and they are the ones that decide whether the page is still true in six months. Paste this into whatever tool you already use.

```text
Title: [what this document is, in plain words]

Owner: [team, not a person -- people leave]
Last verified: [YYYY-MM-DD -- the last time someone confirmed the claims below, not the last edit]
Drift triggers: [the specific changes that would make this wrong -- e.g. "Postgres upgrade", "vendor plan change", "the deploy repo is renamed"]

Purpose
[Why this exists and who should read it. One or two sentences.]

Steps / Content
1. [Each claim or step. Keep one assertion per line so a single change touches one line.]
2. [...]

Sources of truth
- [Claim] -> [where the real answer lives: repo path, dashboard, vendor doc, org chart]

Escalation / owner of last resort
[Who to ask when the steps do not work, by role.]
```

The template is doing one quiet thing the formatting-consistency versions do not. It separates a claim from its source of truth, and it names the trigger that would invalidate the claim while you still remember what that trigger is. A page built this way can be checked. A page that is just prose cannot.

## The first draft is the only draft anyone budgets for

Teams are not lazy about documentation. They are structurally biased toward version one.

Writing gets a slot. There is a docs week, a Notion migration, an onboarding revamp, a "let's finally write the runbooks" push after a bad incident. Every one of those produces a burst of pages with a real owner, a real deadline, and a real sense of accomplishment. What none of them produces is a mechanism for the next twelve months.

David Nunez, an early hire at Stripe and Uber, put the ownership question plainly in his [guide to internal documentation for startups](https://review.firstround.com/investing-in-internal-documentation-a-brick-by-brick-guide-for-startups/): everybody uses internal docs and almost nobody owns them. Documentation lands in the category of work that belongs to everyone, which reliably means it belongs to no one after the launch push ends.

The payoff for getting this right is large and well measured. Google's DORA program has found that [documentation quality](https://dora.dev/capabilities/documentation-quality/) amplifies every technical practice it studies rather than sitting beside them: teams with above-average documentation saw a 656% greater lift in organizational performance from continuous delivery, and 1,525% from trunk-based development.

Notice what that finding rests on, though. Quality is a present-tense property. A document that was excellent in March and wrong in July doesn't score as quality documentation. It scores as a trap with good formatting.

## Why internal documentation goes stale faster than you expect

Your documentation describes a system that changes on a deploy schedule. Your documentation changes on a human schedule. That gap is the entire mechanism of [knowledge decay](https://scribelet.app/blog/knowledge-decay), and it compounds quietly.

The useful move is to stop thinking about stale *pages* and start thinking about stale *claims*. A runbook isn't one fact that goes bad all at once. It's a stack of individual assertions, each with its own half-life and its own trigger. Documentation drift doesn't happen to a document. It happens one sentence at a time.

| Claim in a doc | What invalidates it | Rough half-life | How you find out today |
|---|---|---|---|
| "Run `deploy.sh --prod` from the release branch" | A rename or refactor in the deploy repo | Weeks | Someone runs it and it fails |
| "Postgres 14, single primary in us-east-1" | An upgrade or region migration | Months | Mid-incident, at the worst moment |
| "Ask the payments team in #payments-eng" | A reorg or a channel rename | Months | A new hire pings a dead channel |
| "Rate limit is 1,000 requests per minute" | The vendor changes plans or pricing | Unpredictable | A 429 in production |
| "We chose Kafka because of ordering guarantees" | A later decision supersedes it | Years | An argument in a design review |

Read the right-hand column again. Every discovery method on that list is an incident, a stumble, or a new hire's wasted afternoon. Your documentation has no expiry date and no test suite, so production is the test suite.

Code has a defense against this. Tests fail when an assumption stops holding. Prose doesn't fail. It just sits there, formatted and confident, being wrong.

![Chart showing the share of an internal document's claims still accurate falling over twelve months while the share anyone has re-checked stays flat, leaving a widening band of claims trusted because nobody looked](/blog/internal-documentation/documentation-half-life.svg)

This is the same failure we wrote about in [the doc rot problem](https://scribelet.app/blog/outdated-documentation), viewed from the team side rather than the individual one. Personal notes rot privately. Internal documentation rots in a place where four people will act on it.

## Ownership decays before the documentation does

Here's where the standard advice runs out. Every guide on internal documentation best practices converges on the same instruction: give every document an owner, and have that owner review it on a cadence.

Try holding that model against the actual lifespan of a role. People change teams, take the promotion, go on leave, or leave outright. Add reorgs and team splits to ordinary attrition and the practical half-life of "Owner: Dana" is a year or two at best, which is shorter than the useful life of most of the pages Dana owned. That is exactly why the template above puts a team in the owner field, not a name.

So the owner field is a claim like any other, sitting in the same page, decaying on the same curve as everything around it. When it goes stale it takes the review cadence down with it, silently, because a calendar invite for a quarterly doc review does not bounce when the assignee leaves. It just stops being accepted.

Consider a two-year-old onboarding doc with a former staff engineer's name at the top. A new hire follows it on day two, sets up a local environment against a database that was decommissioned last spring, loses most of a day, and asks in Slack. Someone answers in the thread. Nobody edits the page. Next month the next hire loses the same day. That doc has now cost more engineering time than writing it saved, and its owner hasn't worked here since 2024.

Pointing a check at something that cannot leave the company is what fixes this. Your repo, your changelog, your vendor's docs, and your dashboards are all still here. For code-adjacent claims, the [GitHub connector](https://scribelet.app/learn/ai/github-connector) verifies what a doc says against what your repository actually contains.

## What a maintenance layer looks like

A maintenance layer is not a bigger wiki or a stricter template. The [docs as code](https://www.writethedocs.org/guide/docs-as-code/) approach already gave engineering teams the best version of the tooling answer: docs in the repo, reviewed in pull requests, versioned with the thing they describe. The same repo-native instinct produces [a pull request template people actually fill in](https://scribelet.app/blog/pull-request-template), reviewed like code because it is code. It's a genuine improvement, and it still can't tell you that a claim expired, because nothing in a diff-based workflow fires when the world changes and the file doesn't.

What closes that gap is four habits, only one of which is about writing.

**Date the claim, not the page.** Almost every tool shows "last edited." That timestamp tells you when someone touched the formatting. What you need is "last verified": the last time somebody, or something, confirmed the assertion is still true. A page edited yesterday can be wronger than one verified last week.

**Name the drift trigger while you still remember it.** When you write "we run Postgres 14," you know exactly what would change that: an upgrade. Write the trigger down next to the claim. This is the discipline that makes [named drift triggers](https://scribelet.app/blog/architecture-decision-record-examples) work in architecture decision records, and it transfers cleanly to runbooks and service docs.

**Point each claim at a source of truth.** Version numbers live in the repo. Endpoints live in the API spec. Ownership lives in the org chart. Rate limits live in a vendor's docs. A claim that cannot be traced to a source is a claim nobody can check, which is a good reason to either delete it or promote it into a decision record where its rationale can live.

**Review as a diff, not a rewrite.** A rewrite is an afternoon and gets deferred forever; a diff is thirty seconds of judgment about one changed line. That is the difference between a doc audit nobody schedules and [a 30-minute weekly review](https://scribelet.app/blog/keep-notes-up-to-date) somebody actually finishes.

![Diagram contrasting a write-once internal documentation pipeline that ends at publish with a maintenance loop: date the claim, name the drift trigger, check the source of truth, accept or dismiss the diff](/blog/internal-documentation/maintenance-loop.svg)

## A 30-minute internal documentation review

The four habits above are only worth anything if they turn into a routine short enough that someone finishes it. Here is that routine as a checklist. Run it on your five most load-bearing documents, not the whole wiki, and run it on a fixed cadence rather than after the next incident.

```text
[ ] Sort by blast radius, not by age. Start with the docs an error would hurt
    most: runbooks, on-call, release steps, the day-one setup guide.

[ ] For each page, read only the claims, not the prose. One line at a time:
    is this still true today? Yes / No / I am not sure.

[ ] Every "No" gets a one-line diff, not a rewrite. Fix the sentence, move on.

[ ] Every "I am not sure" gets a source of truth attached, or the claim is
    deleted. An unverifiable claim is worse than a missing one.

[ ] Update "Last verified" to today on every page you touched, even the ones
    that needed no change -- "still true" is the most valuable signal here.

[ ] Anything that was wrong because a decision changed goes into a decision
    record, so the reason survives the next time someone asks.
```

The point of the checklist is not thoroughness. It is that a diff-sized review can be scheduled and finished, and a full audit cannot, so the review that actually protects your docs is the small one you repeat.

## How this works in Scribelet

The four habits above are doable by hand. They rarely survive a quarter, because the work arrives at the worst possible time and belongs to nobody in particular.

Scribelet runs them as background jobs. Your team's docs live in shared [team desks](https://scribelet.app/learn/organization/desks), and background agents re-check the factual claims in those notes against the web, your connectors, and your own repository on a schedule you choose. Want to see what an automated check on a page like that looks like? [Background checks](https://scribelet.app/learn/ai/ai-verification) run on a schedule you set and show you what stopped being true.

When something no longer matches, you get a diff: the sentence you wrote, what the source says now, and a citation, waiting for you to accept or dismiss it. The verified date moves when a check passes, not when someone fixes a typo.

Model choice is yours. Scribelet's AI works out of the box, and if you would rather route it through your own OpenAI, Anthropic, or Gemini key, bring your own and the key is encrypted at rest.

Be clear about the limits. Verification catches claims that can be checked against something external: a version, an endpoint, a limit, a deprecation. It cannot tell you that your team decided in a hallway to stop using the staging cluster. That kind of knowledge needs a decision record, written by a person, at the moment the decision happens. Nothing automates that, and any vendor telling you otherwise is selling.

## Where this bites first

Runbooks feel it hardest, because they are read under pressure and their claims are the most operational. On-call is the one context where a wrong internal document has a direct cost you can measure in minutes of downtime. It is also the only document type whose entire readership is concentrated in its worst possible moment, which is why [the runbook nobody re-checks](https://scribelet.app/blog/runbook) fails in a category of its own.

Onboarding docs come second, and their damage is invisible in the aggregate: every new hire pays the tax privately, in a lost afternoon they assume was their own fault.

After that it is infrastructure inventories, the perennial subject of r/sysadmin threads about what to use for internal documentation, where the tool is never the actual problem. Then internal service docs, the pages one team maintains so five others do not have to read the source, which decay fastest of all because the people harmed by the errors are not the people who can fix them.

## The second draft has to arrive on its own

Internal documentation is not a writing problem. It is an expiry problem wearing a writing problem's clothes, which is why every attempt to fix it with better templates, a nicer wiki, or one more documentation sprint produces another burst of pages that are accurate on the day they ship and quietly wrong by autumn.

Give your claims a verified date, a drift trigger, and a source they can be checked against, then let something other than a departed owner's calendar invite do the checking. Your docs stop being a museum of what used to be true. [Start free](https://scribelet.app) and point the first check at the runbook you trust least.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>documentation</category>
            <category>engineering</category>
            <category>knowledge-management</category>
            <category>teams</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Interstitial journaling: the log nobody reads back]]></title>
            <link>https://scribelet.app/blog/interstitial-journaling</link>
            <guid isPermaLink="false">https://scribelet.app/blog/interstitial-journaling</guid>
            <pubDate>Mon, 27 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Interstitial journaling clears your head between tasks, then the log rots unread. A copy-paste template, examples, and how to make it pay off. Try it free.]]></description>
            <content:encoded><![CDATA[
For a few weeks it was the best productivity habit you had ever kept. Every time you switched tasks you dropped a line in a running log with the time next to it: "10:42, finished the pricing draft, still unsure about the annual tier, next up answer Priya's thread." Interstitial journaling did exactly what it promised. Your head felt clearer between tasks, you stopped stalling before hard work, and for once you knew where the day actually went.

Scroll that log now. It is a wall of timestamps and half-sentences, hundreds of them, written to a version of you who was mid-context and needed none of it explained. "2:15, back from standup, the thing about the migration." What thing about the migration? You wrote it three months ago and you have not opened it since. The entries did their job for the ninety seconds after you typed them, and then they became sediment.

This is the quiet fate of the interstitial log. The method is genuinely good at the moment of writing and completely silent about everything that comes after. Every guide teaches you how to fill the log. None of them tells you what the log is for once the day is over. This guide gives you the template, the worked examples, and the answers to the questions people actually ask about the method, and then it covers the part everyone skips: what happens to the log after you stop writing it.

## What is interstitial journaling?

Interstitial journaling is the practice of writing short, timestamped notes in a single running log during the gaps between tasks, capturing what you just finished and what you plan to do next. It combines note-taking, a to-do list, and time tracking in one stream, and it is meant to be written in the small "interstitial" moments when you switch from one thing to another.

The term was coined by [Tony Stubblebine](https://betterhumans.pub/replace-your-to-do-list-with-interstitial-journaling-to-increase-productivity-4e43109d15ef) in 2017 and popularized for a wider audience by Anne-Laure Le Cunff, who describes it at [Ness Labs](https://nesslabs.com/interstitial-journaling) as the simplest way to combine notes, tasks, and time tracking in one workflow. The appeal is that it needs no special tool. A notebook works. A plain daily note in Notion, Obsidian, or Roam works. The habit is the whole method.

What it is not is a diary. You are not reflecting on your feelings at the end of the day. You are logging the transitions, in real time, as a way to steer the next hour.

## How interstitial journaling works

The mechanics fit in three moves, and you can learn them in a minute. Every time you finish something or switch context, you stop and write three things.

**Note the time.** Stamp the entry with the current time. Over a day this builds an honest record of where your hours actually went, which is usually nothing like where you thought they went.

**Reflect on what you just did.** One or two sentences on the task you are leaving: what you decided, what is unresolved, what you would tell yourself if you picked it up again tomorrow. This is the move that does the real work.

**Plan the tiny next action.** Write the literal first step of whatever comes next, small enough that starting feels trivial: "open the file and re-read the intro," not "write the report."

The reflection move is not busywork. Psychologist Sophie Leroy showed that when you switch tasks, part of your attention stays stuck on the last one, a drag she named [attention residue](https://doi.org/10.1016/j.obhdp.2009.04.002). Writing a closing line about the task you are leaving gives your brain permission to set it down, so you arrive at the next thing with a cleaner head. That is a real, measurable benefit, and it happens entirely in the moment of writing.

## An interstitial journaling template you can copy

You do not need an app to start, and you do not need to memorize anything. Every entry follows the same four-line shape. Paste this at the top of today's note and copy the block down each time you switch tasks.

```
[HH:MM]
Just finished: what you were doing, and the one thing worth remembering (a decision, an open question, a number).
Feeling: one word, optional, honest (focused / foggy / drained / wired).
Next: the smallest concrete first step, not the whole task.
```

That is the whole template. The "Just finished" line is where the value lives, so make it a sentence, not a label: "wrote the intro" is scaffolding you will delete later, but "wrote the intro, still unsure the opening stat is current, need to recheck the source" is a decision and an open question you will want back. The "Feeling" line is optional and takes one word, but over a week it quietly shows you when your focus actually breaks, which is rarely when you assumed. The "Next" line is the anti-procrastination lever: keep it small enough that starting is trivial.

If you keep the log in a tool that supports it, add one thing the paper version cannot give you: a way to mark the "Next" lines so they do not vanish into the scroll. In Scribelet a leading checkbox or an `@task` turns that line into something you can actually close later, which matters more than it sounds, for reasons the rest of this guide gets to.

## Interstitial journaling examples

The template is abstract until you see it running. Here are three real interstitial log entries from three different kinds of day, so you can copy the rhythm rather than the words.

**A product manager mid-afternoon.**

```
14:05
Just finished: vendor integration call. They can do it but not before Q3, so the launch date is at risk.
Feeling: tense
Next: draft two sentences to the team flagging the slip, send before I forget the reason.
```

**A writer between drafts.**

```
09:40
Just finished: first pass on the essay intro. The Leroy citation is doing a lot of work and I never checked the year.
Feeling: focused
Next: open the paper, confirm 2009, then write the second paragraph.
```

**A student with ADHD, switching subjects.**

```
16:20
Just finished: two problem sets, but I burned 40 minutes reorganizing the folder instead of starting.
Feeling: scattered
Next: read exactly one page of the reading, timer on, phone in the other room.
```

Notice what each entry preserves that a bare "done with the call" would have thrown away: the reason the launch date moved, the fact-check you owe yourself, the honest note that folder-tidying was procrastination. Those are the parts you will want back in a week. The timestamps and the "back from lunch" lines around them are not.

## What app can I use for interstitial journaling?

The honest answer is that any place you can type a timestamp works, and the method's founders wrote it for a plain notebook. The tool only starts to matter when you ask what happens to the log after the day ends, which most guides never do. Here is how the common options actually compare, on the day you write and the week after.

| Approach | Real-time capture | Reads the log back | Turns next-actions into tracked tasks | Keeps entries findable and current |
|---|---|---|---|---|
| Pen and notebook | Yes | No, by hand only | No | No, and not searchable at all |
| Notion or Obsidian daily note | Yes | Only if you reread it yourself | Manual, if you copy them out | Text search only, entries freeze at capture |
| Roam daily notes | Yes | No, links help but you still dig | No | Better linking, no accuracy check |
| A maintained system | Yes | Yes, digest surfaces decisions and themes | Yes, tasks extracted automatically | Yes, semantic search plus verification |

Pen and paper is the purest way to learn the habit and the worst way to keep the payoff. A daily note in [Notion, Obsidian, or a block-based outliner](https://scribelet.app/blog/obsidian-vs-logseq) is where most people land, and it is a real improvement: capture is fast and the log is at least text-searchable. The middle rows are where nearly every guide on the method stops. The last row is the difference between a log that became a record of what you actually decided and one that became a wall of timestamps you will never open again, which is the whole subject of the second half of this article.

## What are the three types of journaling?

People searching for interstitial journaling often land on this question, because it helps to know where the method sits. Broadly, journaling comes in three shapes:

- **Reflective journaling**, the classic diary: end-of-day, feelings-first, written to process what happened.
- **Structured or prompt-based journaling**, such as gratitude journaling or a bullet journal, where fixed prompts or a fixed format do the thinking for you.
- **Log-based journaling**, which is where interstitial journaling lives: written in real time, event-triggered, and aimed at steering the next hour rather than reflecting on the last day.

Interstitial journaling is the odd one out on purpose. It is not about the end of the day and it is not about a prompt. It is a running log you write while the work is happening, which is exactly why it captures decisions the other two miss and exactly why it piles up faster than either.

## What is the 3-3-3 journal method?

The 3-3-3 method is a short, structured routine, usually done in the morning: you write three of something across three categories, most commonly three things you are grateful for, three things that would make the day good, and three quick intentions or affirmations. It is a prompt-based practice, fixed in shape and done once a day.

That is the opposite of interstitial journaling, and the two solve different problems. The 3-3-3 method sets an intention before the day starts. Interstitial journaling steers the day while it runs and leaves a record of what actually happened. If you like both, run 3-3-3 at the top of your daily note and interstitial entries underneath it through the day. They stack cleanly, and the read-back problem this article describes applies to the combined log exactly the same way.

## Interstitial journaling for ADHD

A lot of the enthusiasm for this method comes from people with ADHD, and it is not an accident. Interstitial journaling gives three things an ADHD brain tends to want at once: structure, because every entry has the same shape; flexibility, because there is no schedule and you write only when you switch; and instant feedback, because the timestamp shows you, without judgement, where the time actually went.

The "Next" line is the part that earns its keep here. A task that feels too big to start is the classic ADHD wall, and writing down a first step small enough to be trivial is a known way over it. The "Feeling" line helps too: naming "scattered" or "wired" in one word is a cheap form of the self-awareness that makes the next choice a little easier. The catch is the same one everyone hits, only louder: the log that helped you get through Tuesday is not going to reread itself on Friday, and the person least likely to scroll back through a thousand timestamps is the person who found them useful precisely because they required no rereading.

## Why the method works, right up until it doesn't

Give interstitial journaling its due. In the moment, it delivers three things most productivity systems only promise.

It clears attention residue, so context switches cost you less. It kills procrastination, because a next action small enough to write down is small enough to start. And it produces an honest time log as a byproduct, without a single timer, so you can see that the "quick" review actually ate ninety minutes.

Every one of those benefits is consumed the instant it is produced. The residue clears now. The next action gets started now. The time log matters most for the day you are living. Interstitial journaling is a workflow optimized for the present tense, and that is exactly why the log itself gets abandoned. You were never writing it to read it later. You were writing it to get unstuck now.

So the entries pile up, each one perfectly useful for about a minute and then never again. This is the same [collect-and-forget archive](https://scribelet.app/blog/commonplace-book) that swallows highlights and reading notes, just running at a faster clock. A commonplace book rots over years. An interstitial log rots by Friday.

![Timeline diagram of a single day's interstitial journal entries stacking into a running log, with the real-time benefits (cleared attention residue, next action, honest time log) consumed at the moment of writing, and the accumulated log falling into an unread graveyard unless a read-back step distills it into outcomes](/blog/interstitial-journaling/interstitial-log-lifecycle.svg)

## What happens to the log after the day ends

Picture what you actually have after a month of diligent interstitial journaling. Thousands of lines. Every meaningful decision you made is in there somewhere, next to every "back from lunch" and every "quick break." The signal is real, and it is buried in noise you wrote on purpose.

That log is a record of how you spent your attention, which is to say it is one of the most valuable things you produce all week. It knows why you changed the launch date. It knows the objection the client raised that you swore you would remember. It knows which task you have restarted four Mondays in a row without finishing. A [work log that captured your actual decisions](https://scribelet.app/blog/ai-work-log) is gold at review time, in a retro, or the next time the same problem comes back around.

But only if someone reads it back. Left alone, the interstitial log is a diary of intentions that never becomes a record of outcomes. You logged "next: flag the slip to the team." Did you? The log captured the intention and then never checked. And the raw entries are exposed to ordinary [knowledge decay](https://scribelet.app/blog/knowledge-decay) on top of that: the link you dropped at 3pm rots, the "current" number you jotted gets superseded, the decision you recorded gets quietly reversed two weeks later and the old entry still says the opposite. The log fails twice, the same way collected notes always do. It fails forward, because you never distilled it into anything. And it fails in place, because even the record it preserved is going out of date while you assume it is safe.

## What an interstitial log needs after you stop writing it

Strip away the method and an interstitial log needs three unglamorous things done to it, on repeat, if it is going to be worth more than the day you spent building it.

It needs to be read back and distilled. Somebody has to walk the day's stream and pull out the parts that outlive the day: the decisions, the open questions, the commitments you made to yourself. The other ninety percent, the "back from lunch" scaffolding, can fall away. Without that pass, the outcomes stay trapped in the noise that surrounded them.

It needs its intentions turned into tracked actions. Half of what you write in an interstitial log is a next action. "Draft two sentences to the team." Those are the point of the method, and they are worthless if they live and die inside a timestamped line nobody revisits. They need to become things you can actually check off, not fossils in a scroll.

It needs to stay searchable by meaning. Six weeks later you will want "that call where the integration date slipped," not the timestamp, which you never knew. A log you can only read top to bottom is a log you will never read at all.

None of this is intellectually hard. It is just relentless, on no schedule, and the person who would have to do it is the same tired person who found the log too tedious to reread in the first place. This is [the step every note-taking method skips](https://scribelet.app/blog/personal-knowledge-management), and interstitial journaling skips it faster than most.

## Interstitial journaling without the graveyard

This is the part the method leaves to your discipline, and it is the part Scribelet is built to take off your hands. The principle is simple: if an interstitial log is only useful once something reads it back, do the read-back automatically instead of hoping you will.

In Scribelet, today's [daily note](https://scribelet.app) is the running log. You drop timestamped lines through the day the same way you would anywhere, in real time, with no extra ceremony, using the exact four-line template above. The difference is what happens overnight. A daily digest reads the day's entries back and returns the themes, the decisions, and the action items, so the outcomes lift out of the noise without you rereading a single line. The stream stays as your raw record, and the summary becomes the thing you actually keep.

The next actions you logged do not stay buried either. Scribelet pulls tasks out of your notes, so "draft two sentences to the team" becomes something you can track and close, not a line you scroll past. Semantic search means you find the call where the date slipped by describing it, not by remembering when you wrote it down. And because your notes point at the outside world, [background verification](https://scribelet.app/blog/keep-notes-up-to-date) can check the claims in them against the web on a schedule and show you a diff when something you logged has since changed.

Because this is AI reading your log, control is the point. Scribelet's AI works out of the box, and bringing your own OpenAI, Anthropic, or Gemini key is an optional path if you would rather your notes be read by the provider you choose than one we picked for you. Either way the digest is a summary you review, and every suggested change lands as a diff you approve, not a silent edit. You can watch it [read your first day back](https://scribelet.app) on a log you already keep.

## The log is a means, not a monument

The reason your interstitial log went nowhere is not that you journaled wrong. You almost certainly journaled well. The method simply handed you a stream that pays off in the moment and then left the far more valuable second payoff, the record of what you decided and did, to a future self who was never going to scroll back through a thousand timestamps to find it.

Treat the interstitial log as what it is: a means, not a monument. The point was never the stream. The point is the handful of decisions, questions, and commitments buried inside it, and those only surface if something [reads the day back for you](https://scribelet.app/blog/how-to-remember-what-you-read) and keeps them where you can find them. Write your log the way the method taught you, using the template above, and let a system turn it into a record of outcomes instead of a graveyard of intentions. [Start free](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>journaling</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>productivity</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Literature notes: the layer everyone abandons]]></title>
            <link>https://scribelet.app/blog/literature-notes</link>
            <guid isPermaLink="false">https://scribelet.app/blog/literature-notes</guid>
            <pubDate>Sun, 26 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What a literature note is, how to take one, a copy-paste template, three worked examples, and the maintenance step every method skips. Try it free.]]></description>
            <content:encoded><![CDATA[
You finished a good book last year and did the responsible thing. You kept literature notes as you read: the argument in chapter three you did not want to lose, two quotes worth stealing, the page where the author finally said the thing the whole book was building toward. It felt like real work, because it was.

Open that file now. It is a slab of half-context: page numbers pointing at an edition you no longer own, a quote with no memory of why you flagged it, a link to the author's blog post that now returns a 404. You have not looked at it since the week you wrote it, and you never will again. The literature note did its job for exactly one afternoon.

This is the strange fate of literature notes. They are the single most-taught step in every serious note-taking method and the single most-abandoned one in practice. The bridge between what you read and what you actually keep gets built by everyone and crossed by almost no one. This guide covers what a literature note is, how to take one, a template and three worked examples you can copy, and the one step that decides whether any of it was worth the effort.

## What is a literature note?

A literature note is a note you write in your own words while reading a source, capturing the ideas worth keeping and where they came from. It sits between a raw highlight and a finished idea: more considered than a margin scribble, less permanent than a concept you have made your own. Its job is to move an idea out of someone else's text and one step closer to your thinking.

The term comes from the [zettelkasten tradition](https://zettelkasten.de/introduction/) and was popularized for a modern audience by Sönke Ahrens in [How to Take Smart Notes](https://takesmartnotes.com/), his study of how the sociologist Niklas Luhmann worked. Ahrens splits note-taking into three types, and the literature note is the middle one.

The literature note is where reading turns into raw material. Get it right and your permanent notes have something to draw from, though [taking smart notes that stay true](https://scribelet.app/blog/how-to-take-smart-notes) asks one more thing of you after the permanent note is filed. Skip it and you are back to highlighting, which is to say back to nothing.

## The three types of notes: fleeting, literature, permanent

**Fleeting notes** are throwaway capture: a thought on a walk, a line you jotted so you would not forget it. **Literature notes** are what you write when you engage with a source, in your own words, with a reference back to it. **Permanent notes** are the ones you write for your future self, atomic and self-contained, that live in your [slip-box](https://scribelet.app/blog/zettelkasten-with-ai) and connect to everything else. Andy Matuschak describes literature notes as [secondary and separate](https://notes.andymatuschak.org/zKzUzQENhyEDnuwPUhh2EQM): a lightweight synthesis of observations collected while reading, deliberately kept apart from your own developed ideas.

The three types are easiest to hold side by side:

| Note type | What it is | When you write it | Lifespan | Where it goes next |
|---|---|---|---|---|
| Fleeting | A raw thought or reminder to yourself | The moment it occurs to you | Hours to a day, then discarded | Processed into a literature or permanent note, or deleted |
| Literature | A source's idea, in your words, with a reference | While reading or right after | Until you distill it (in theory) | Promoted into a permanent note |
| Permanent | Your own idea, atomic, standing on its own | When an idea has become yours | Years, if maintained | Linked into the slip-box forever |

![Horizontal flow diagram of the three zettelkasten note types moving from a source book through fleeting notes, literature notes, and permanent notes into the slip-box, with the literature-note stage marked as where most reading stalls and decays](/blog/literature-notes/note-types-flow.svg)

The middle row is the one that breaks. Fleeting notes are disposable by design and nobody mourns a lost one. Permanent notes, once written, tend to get used. Literature notes sit in between, written with care and then never promoted, and that accumulation is the problem this article is actually about. But first, the part every other guide covers.

## How to take literature notes

The mechanics are not complicated, and you can learn them in a paragraph. Read with a way to mark passages. When something matters, stop and write a sentence or two in your own words about what it says and why it is worth keeping, and note the source and location. Do not transcribe. If you are copying the author's sentence verbatim, you are making a highlight, not a literature note. The act of rephrasing is the whole point, because it forces you to understand the idea well enough to say it differently.

A literature note has four parts, and they fit on a small skeleton you can reuse for every source:

```
Source: [author, title, and the edition or URL]
Location: [chapter, page, timestamp, or section]
Claim: [the idea, in your own words, one or two sentences]
Why it matters: [what you would use this for, or what it changes]
```

Keep the claim short and in your voice. The "why it matters" line is what separates a literature note from a fancy highlight: it records the thought you had while reading, which is the thing you will actually lose. Fill the skeleton in while the reading is fresh, because "process this later" is a promise made to a version of you who has already moved on to the next book.

## Literature note examples

Theory is thin without a real one in front of you. Here are three worked literature note examples across the source types you read most: a book, a research paper, and a talk. Each shows the raw highlight first, then the literature note, so the difference is visible. For dense sources, [reading a paper in passes](https://scribelet.app/blog/how-to-read-a-research-paper) is what gives you a claim worth writing down instead of a page of highlights.

**From a book.** You are reading on habit formation and hit a claim that habits run on a cue, routine, reward loop.

- Highlight (verbatim): "The cue and reward become intertwined until a powerful sense of anticipation and craving emerges."
- Literature note:

```
Source: Duhigg, The Power of Habit (2012 paperback)
Location: Ch. 2, p. 47
Claim: Habits run as a three-part loop (cue -> routine -> reward). The
  leverage point for change is the cue, not willpower.
Why it matters: Reframes habit change as environment design. Useful for
  the note on why streak apps work and to-do lists do not.
```

**From a research paper.** You are reading a study on spaced repetition and want the finding, not the whole abstract.

- Highlight (verbatim): "Retention was significantly higher in the expanding-interval condition than in the massed condition at the two-week retention test."
- Literature note:

```
Source: study on spacing effect, J. of Applied Cognitive Psych (2019)
Location: Results, Table 3
Claim: Reviews spaced at expanding intervals beat cramming at two-week
  recall. Effect held across ages; sample was students, not general public.
Why it matters: Evidence for scheduling review by interval, not by mood.
  Note the sample limit before citing it as universal.
```

**From a talk or podcast.** You are listening to a conference talk and something lands.

- What you heard: the speaker argues that documentation rots because it is written once and never re-read.

- Literature note:

```
Source: engineering talk on internal docs (conf 2025), speaker's name
Location: ~18:30
Claim: Docs decay because writing is a one-time event with no re-read
  trigger. The fix is a review cadence, not better writing.
Why it matters: Same failure mode as literature notes. Connects to the
  knowledge-decay thesis; possible permanent note on "capture without
  a re-read step is landfill."
```

Notice the shape. Each note is short, in your own words, tied to a specific location, and carries a line about what you would do with it. That last line is the seed of a permanent note. The research-paper example also does something a highlight cannot: it flags the study's limit ("sample was students") so the future you does not overclaim. A good literature note is already thinking, not just filing.

## Literature notes vs. permanent notes

The question people keep asking, in every zettelkasten forum thread, is where the line falls between a literature note and a permanent note. The distinction is not about polish. It is about ownership.

A literature note still belongs to the source. It says "here is what this author argued, and here is where they argued it." It is tied to a book, a paper, a talk. A permanent note has cut that cord. It states an idea as yours, standing on its own, phrased so it makes sense years later without the book open next to you. You might read ten literature notes across four books and distill them into one permanent note that none of those authors would recognize as theirs anymore.

Fleeting notes are the easy case: they are disposable by design, meant to be processed within a day or two and then thrown away. The trouble is that most people's literature notes quietly behave like fleeting notes. They get written, they never get processed into anything permanent, and unlike fleeting notes they do not get thrown away. They just accumulate.

## Why literature notes are the layer everyone abandons

Here is the honest sequence. You read the book. You take careful literature notes. You feel productive. And then the reading ends, life resumes, and the literature notes sit there waiting to be turned into permanent notes by a future self who never shows up. The distillation step has no deadline and no trigger, so it never happens.

What you are left with is a growing pile of source-bound notes that were never meant to be permanent and never got promoted, either. This is a [commonplace book](https://scribelet.app/blog/commonplace-book) by accident: a collect-and-forget archive of other people's ideas, filed and never reread. It is also the reason so many people conclude that [remembering what you read](https://scribelet.app/blog/how-to-remember-what-you-read) is hopeless. The notes existed. They just went nowhere.

And they do not age well. A literature note is unusually exposed to [knowledge decay](https://scribelet.app/blog/knowledge-decay) because it is defined by its links to the outside world. The page number points at a specific edition. The source URL rots. The statistic you noted was superseded by a newer study. The framework the author described shipped a breaking change. A permanent note about your own reasoning can stay true for years. A literature note is only ever as current as the source it is chained to, and sources move.

So the literature note fails twice. It fails forward, because you never distilled it into anything permanent. And it fails in place, because even the raw record it preserved is quietly going out of date while you assume it is safe.

## What a literature note needs after you write it

Strip away the method-war arguments and a literature note needs three unglamorous things done to it, on repeat, if it is going to be worth more than the afternoon you spent making it.

It needs to be resurfaced. A note you never see again cannot become a permanent note, so something has to bring the right literature note back when you are working on a related idea, rather than waiting for you to go digging. The whole promotion step depends on the note showing up at the moment it is relevant.

It needs to be re-checked against its source. The claims in a literature note point outward, at a page, a link, a number. Keeping the note trustworthy means periodically comparing what it says to what the source says now, and seeing the difference when the source has changed. This is the part manual systems cannot do, because you would have to remember to reopen every book you have ever read.

It needs to be re-linked as your thinking grows. A literature note written when your slip-box held 80 notes is under-connected once it holds 400. New adjacent ideas have arrived that the old note was never wired to, and reading is only cumulative if those connections actually get made.

None of this is intellectually hard. It is just relentless, on no schedule, forever, which is precisely the kind of work humans quit and software does not.

## Keeping literature notes alive without the busywork

This is the step Ahrens leaves to your discipline, and it is the step Scribelet is built to take off your hands. The principle is simple: if a literature note is only useful when it resurfaces, stays accurate, and stays connected, let those three things run in the background instead of depending on you remembering to do them.

[Background verification](https://scribelet.app/learn/ai/ai-verification) checks a note's factual claims against the web on a schedule you set, then shows you a diff: green for what is new, red for what is now outdated, with the source. The literature note that summarized a since-corrected study surfaces the correction, instead of sitting there teaching you the old number. You review the change, accept or dismiss it, and the note updates. That is the "keep your sources current" chore turned into an event that arrives on its own.

An auto-linker watches your growing note graph and suggests connections a literature note did not have when you wrote it, which is how a source-bound note starts earning its way toward a permanent one. A stale checker flags notes that relate to your recent reading but have not been touched in months, giving you the resurfacing trigger the method never provided. Semantic search means you can find every literature note that touched an idea by meaning, not by remembering which book it was in.

Because this is AI reading your notes, control is the point. Scribelet's AI works out of the box, and bringing your own OpenAI, Anthropic, or Gemini key is an optional path if you would rather your notes be checked by the provider you choose than one we picked for you. Either way, every change lands as a diff you approve, not a silent edit. You can [see your first diff](https://scribelet.app) on a note you already half-trust.

## Approaches to literature notes, compared

Every method here gets you a decent literature note on the day you write it. The difference shows up a year later, in whether that note ever became knowledge or just became clutter.

| Approach | Captures source in your words | Resurfaces old notes | Keeps sources accurate | Promotes toward permanent notes |
|---|---|---|---|---|
| Highlights only (Kindle, Readwise export) | No, verbatim capture | Random resurfacing at best | No | No, highlights stay highlights |
| Plain markdown (Obsidian, Logseq) | Yes | Only if you search by hand | No, notes freeze at capture | Only when you remember |
| Classic zettelkasten discipline | Yes | No, by hand only | No, sources drift | Yes, if you keep the habit |
| A maintained system | Yes | Yes, by relevance and schedule | Yes, re-checked against sources | Yes, with linking and resurfacing done for you |

The middle two rows are where nearly every guide on the method stops. The last row is the difference between a literature note that became part of your thinking and one that became landfill.

## A literature note is a loan, not a keepsake

The reason your literature notes went nowhere is not that you took them wrong. You probably took them well. The method simply handed you a note that only pays off if you come back to it, distill it, and keep its sources honest, and then left all three jobs to a future self on no deadline.

Treat a literature note as what it is: a loan from a source that you intend to turn into something of your own. That only works if the note resurfaces while the idea is still live, stays accurate while its sources move, and finds its way to the [permanent notes and evergreen ideas](https://scribelet.app/blog/evergreen-notes) it was meant to feed. Reading compounds when that maintenance happens and rots when it does not, which is [the step every note-taking method skips](https://scribelet.app/blog/personal-knowledge-management). Let a system carry it, and start turning your reading into knowledge that lasts. [Start free](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>zettelkasten</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Evergreen notes: why yours stopped being evergreen]]></title>
            <link>https://scribelet.app/blog/evergreen-notes</link>
            <guid isPermaLink="false">https://scribelet.app/blog/evergreen-notes</guid>
            <pubDate>Sat, 25 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Evergreen notes are supposed to evolve. Yours haven't changed in a year. Here's the maintenance step the method skips, and how AI keeps notes green. Try it free.]]></description>
            <content:encoded><![CDATA[
You wrote a handful of genuinely good evergreen notes a year ago. Atomic, in your own words, linked to three or four related ideas. It felt like the moment your thinking finally started to compound. Open that folder now. Most of those notes have not changed a single character since the day you wrote them.

That is the quiet contradiction at the heart of the method. Evergreen notes are defined by the one thing almost nobody actually does to them: keep them evolving. The name promises a note that stays alive. What you usually get is a note that was alive for one afternoon and has been sitting still ever since, slowly drifting out of date while you assume it is still good.

This is not an argument against evergreen notes. The idea is one of the best things to come out of personal knowledge management. It is an argument that the method is only half a method, and the missing half is the reason your collection feels more like a museum than a garden.

## What are evergreen notes?

Evergreen notes are notes written and organized to evolve, accumulate, and build understanding over time, rather than sit as a one-time record of what you read or thought. The term comes from developer and researcher [Andy Matuschak](https://notes.andymatuschak.org/z5E5QawiXCMbtNtupvxeoEX), who framed them around four principles.

They should be **atomic**: one idea per note, so it can be reused and linked cleanly. They should be **concept-oriented**: titled and filed by idea ("Retrieval builds memory") rather than by source or date. They should be **densely linked**: connected to related notes so your knowledge forms a web instead of a pile. And they should be **evolving**: revised and expanded as your understanding grows.

Maggie Appleton, who did as much as anyone to popularize the approach, describes it in [Growing the Evergreens](https://maggieappleton.com/evergreens) as a system that "aspires towards cumulative personal knowledge, rather than simply information capture." That word, cumulative, is the whole promise. A good evergreen note is not a snapshot. It is a living statement of your best current thinking on one thing, and it is supposed to get better every time you touch it.

The first three principles are about how you write the note. The fourth is about what happens after, and it is the one that quietly decides whether any of this works. If you want to skip the theory and just have the evolving handled for you, you can [start free](https://scribelet.app) and come back to the argument.

## Evergreen notes vs. permanent notes: the zettelkasten question

People coming from the zettelkasten world constantly ask how evergreen notes differ from permanent notes, and the answer is exactly where the trouble hides.

In a classic zettelkasten, a [permanent note in a zettelkasten](https://scribelet.app/blog/zettelkasten-with-ai) is finished. Niklas Luhmann's slip-box treated a permanent note as a fixed atom: once you filed it, you did not rewrite it, you wrote a new note that responded to it. The system grew by accretion, not revision. That contract is also [why permanent notes stop being true](https://scribelet.app/blog/how-to-take-smart-notes) once the claims inside them come from a world that keeps moving.

Evergreen notes deliberately break that rule. They are fluid. The same note is meant to be reopened, rewritten, and deepened across months and projects, so the note you have on "spaced repetition" in 2026 is a richer version of the one you started in 2024.

That fluidity is the feature. It is also the liability. The [Obsidian community tends to summarize the distinction](https://forum.obsidian.md/t/evergreen-notes-vs-permanent-notes/19915) as permanent notes being fixed once filed and evergreen notes being living objects that change alongside your understanding. A permanent note is designed to be correct on the day you write it and then left alone, so staleness is baked into the contract and you know not to trust an old one blindly. An evergreen note makes the opposite promise. It says "this is my current thinking, kept current." When you stop keeping it current, and you will, the note keeps making that promise anyway. It looks maintained. It is not.

![Chart of a note's accuracy over a year: a maintained evergreen note stays green while a note written once and left frozen goes confidently out of date](/blog/evergreen-notes/evergreen-note-trajectory.svg)

## The principle everyone quotes and nobody keeps

Here is the honest version of how to take evergreen notes, based on how it actually goes. You learn the four principles. You write atomic, concept-oriented, densely linked notes. You feel great. And then the fourth principle, evolving, turns out to require something the first three never warned you about: coming back.

Coming back does not scale on willpower. Revisiting an old note has no trigger. Nothing tells you that the note you wrote on a web framework's auth pattern is now describing a deprecated approach, because the framework shipped a major version and you were not looking. Nothing flags that the study your note summarized was later corrected. Nothing notices that four of the note's links now 404. The note sits in your densely linked graph looking authoritative, and it is quietly, confidently wrong.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and it hits evergreen notes harder than almost any other format precisely because they promise the opposite. A messy daily journal never claimed to be current. An evergreen note did.

Consider a concrete evergreen notes example. A developer keeps a beautifully atomic note titled "Prefer server-side session validation for auth." It cites a framework's docs, links to three related security notes, reads like a distilled principle. Six months later the framework deprecates that middleware order. The note does not change. It is now teaching the developer a pattern that will fail in code review, and because it is an evergreen note, they trust it more than a random old bookmark. The format's authority has become a bug. This is also [why a stale atomic note is more dangerous](https://scribelet.app/blog/atomic-notes) than a stale messy one: the cleaner the note, the less it shows its age.

This is the gap [every PKM method leaves open](https://scribelet.app/blog/personal-knowledge-management). Capture, organize, connect, and then, in every framework from zettelkasten to PARA to [tending a digital garden](https://scribelet.app/blog/digital-garden), the instructions trail off right where maintenance should begin. Evergreen notes name the maintenance step out loud and still hand it to your future self as unpaid manual labor.

## What an evergreen note needs to actually stay green

Strip away the tooling and the maintenance an evergreen note needs is not complicated. It needs three things done to it, repeatedly, forever.

It needs to be **resurfaced**. A note you never see again cannot evolve, so something has to bring the right note back to your attention at the right moment, by relevance to what you are working on now, not just because you went looking.

It needs to be **re-checked against the world**. The claims in a concept note point at things outside the note: a framework version, a statistic, a source, a link. Those move. Keeping the note green means periodically comparing what it says to what is currently true, and seeing the difference.

And it needs to be **re-linked** as the graph grows. A note written when you had 80 notes is under-connected once you have 400. The dense-linking principle is not a one-time act at creation; it decays too, as new adjacent ideas arrive that the old note never got wired to.

None of this is hard. It is just relentless, and relentless is exactly what humans are bad at and software is good at. The reason your evergreen notes stopped evolving is not that you are undisciplined. It is that you were asked to be a cron job. You can hand that job to something built for it and [see your first diff](https://scribelet.app).

## How to keep evergreen notes evergreen, in practice

This is the part Matuschak's principles leave to you, and it is the part Scribelet is built to take off your hands. The idea is simple: if a note is supposed to evolve, let the evolving run in the background instead of depending on you remembering to do it.

[Background verification](https://scribelet.app/learn/ai/ai-verification) checks a note's factual claims against the web on a schedule you set, then shows you a diff: green for what is new, red for what is now outdated, with the source. You review, accept or dismiss, and the note updates. That is the "evolving" principle turned into an actual event that arrives, rather than a virtue you have to summon. The auth-pattern note surfaces the day the framework deprecates it, not the day it breaks production.

An auto-linker watches your growing note graph and suggests connections the note did not have when you wrote it, so dense linking keeps up with the collection instead of freezing at creation. A stale checker flags evergreen notes that relate to your recent work but have not been touched in months, which is the resurfacing trigger the method never gave you. If you would rather run the cadence by hand, [a thirty-minute weekly review](https://scribelet.app/blog/keep-notes-up-to-date) does the same job manually, and the background version does it while you are busy writing the next note.

Because this is AI touching your notes, control matters. Scribelet works out of the box, and bringing your own OpenAI, Anthropic, or Gemini key is an optional path if you want your notes checked by the provider you choose rather than one we picked for you. Either way you see every change as a diff before it lands. Evolving your notes should not mean handing them to a black box.

## Evergreen note methods, compared

Every approach to evergreen notes gets you a well-written note. The difference shows up a year later, in whether that note is still connected and still true.

| Approach | Writes atomic, linked notes | Resurfaces old notes | Keeps claims accurate | Scales past ~300 notes |
|---|---|---|---|---|
| Plain markdown (Obsidian, Logseq) | Yes | Only if you search by hand | No, notes freeze at creation | Manual upkeep gets heavy |
| Zettelkasten (permanent notes) | Yes | No, by design | No, permanent means fixed | Yes, but never revised |
| Manual evergreen discipline | Yes | Only when you remember | No, depends on willpower | Rarely, revisiting stalls |
| A maintained system | Yes | Yes, by relevance and schedule | Yes, re-checked against sources | Yes, agents do the upkeep |

The first three rows are where nearly every guide on the method stops. The last row is the difference between a note that says it is evergreen and a note that stays that way.

## An evergreen note is a promise to your future self

The reason your evergreen notes stopped being evergreen is not a discipline failure. It is that the method gave you four principles and only helped you with three, then quietly assumed you would perform the fourth by hand, on no schedule, forever. Nobody does that. The notes drift, the links rot, and the format's own authority turns your best old thinking into confident misinformation.

An evergreen note is a promise that this idea will still be your current, accurate thinking when you reach for it next year. Keep the promise with maintenance, not willpower. Write the note atomic and linked, and then let a system resurface it, re-check it, and re-link it so the version you find later is still the version that was true. [Keep your evergreen notes actually evergreen](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>evergreen-notes</category>
            <category>pkm</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[How to remember what you read when notes go stale]]></title>
            <link>https://scribelet.app/blog/how-to-remember-what-you-read</link>
            <guid isPermaLink="false">https://scribelet.app/blog/how-to-remember-what-you-read</guid>
            <pubDate>Fri, 24 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[You forget most of what you read because your notes decay, not just your memory. Here's a system that resurfaces and re-checks what you capture. Try it free.]]></description>
            <content:encoded><![CDATA[
You highlighted forty passages in a book three months ago. You could not quote one of them right now, and you have never once reopened the highlights. You did the thing the advice told you to do. You still forgot almost all of it.

This is the honest starting point for how to remember what you read: most people who forget what they read are not lazy readers. They took notes. They highlighted. Some of them even reviewed. And the material still slid out of reach within weeks. The usual guides blame your memory and stop there. Your memory is only half the problem.

The other half is that the notes you took to remember the reading are quietly going stale, and nobody tells you to check on them. This guide covers both halves: why reading does not stick, and how to build a reading system that actually holds, without turning your evenings into flashcard drills.

## Why you forget what you read

You forget what you read because reading feels like learning while it is happening and mostly is not. Passive reading moves words past your attention without forcing you to retrieve anything. Within a day, most of it is gone. This is the [forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve) that Hermann Ebbinghaus measured in the 1880s, and it has never stopped being true.

The trap is that rereading feels productive. The second time through a chapter, the words are familiar, so your brain reports "I know this." That familiarity is not memory. It is the fluency illusion, and it is why people close a book they have read twice and still cannot summarize it. Recognizing a sentence when you see it again is a much lower bar than producing the idea when you need it. If you would rather a tool do the remembering for you, you can [start free](https://scribelet.app) and skip to the system below.

Two techniques genuinely fight this, and both are worth doing. The first is active recall: closing the book and trying to reconstruct the argument in your own words before you look back. Retrieval is the act that builds memory, which is why [testing yourself beats rereading](https://www.retrievalpractice.org/) in study after study. The friction of dredging the idea up from nothing is the whole point. The second is spaced repetition, revisiting the idea just as you are about to lose it, at widening intervals, so each pass reinforces the trace instead of wasting effort on something you still hold.

Andy Matuschak put the uncomfortable version plainly in [Why books don't work](https://andymatuschak.org/books/): the medium assumes you absorb knowledge by looking at a page, and you don't. If you take one thing from the encoding half, take this. Recall beats rereading, and a note you had to write in your own words beats a highlight you swiped a marker across.

So do that. It is real, and it helps. It also is not enough, because there is a second reason the reading disappears that none of the top guides name.

## The part the advice skips: your reading notes go stale too

Say you take the advice seriously. You keep literature notes, [the layer between what you read and what you keep](https://scribelet.app/blog/literature-notes). You highlight in Readwise, you write summaries in Obsidian, you build the searchable archive everyone recommends. A year later you have four hundred notes and you still cannot remember what you read, because the notes have the same problem the reading did. They sit there, untouched, aging.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and it hits collected reading harder than almost anything. A book note you wrote captures your understanding on the day you wrote it. The framework it summarized has since been revised. The statistic you copied has been updated. The link to the source is dead. The note looks authoritative and is quietly wrong, and you will never notice, because reopening old notes is exactly the thing nobody does.

Picture a developer who read a book on a web framework in the spring and wrote a careful note on its recommended auth pattern. The framework shipped a major version in the summer and deprecated that pattern. The note did not change. It still reads like current best practice, and it will keep reading that way until it causes a bug. Or a researcher whose note summarizes a study that was later corrected. The summary is now confidently repeating a finding the field walked back. In both cases the reader remembered what they read perfectly. What they read stopped being true.

This is the oldest failure in note-taking. It is what happens to a [commonplace book](https://scribelet.app/blog/commonplace-book) full of passages you never read back, and it is the maintenance step that [every personal knowledge management system skips](https://scribelet.app/blog/personal-knowledge-management). Remembering what you read is not only an encoding problem. It is a maintenance problem. You have to keep the captured version alive, or the archive becomes a graveyard you feel guilty about instead of a memory you can use.

![Diagram comparing a highlight archive that decays over time against a maintained reading note that is resurfaced and re-checked](/blog/how-to-remember-what-you-read/reading-retention-decay.svg)

If you want the low-effort way to try this idea, [put your next book's notes somewhere that reads them back to you](https://scribelet.app).

## What is the 2-7-30 rule, and why intervals alone aren't enough?

The 2-7-30 rule is a spaced-repetition schedule: review new material after 2 days, again after 7, and again after 30, so each pass lands just before you would forget. It is a fine default, and it works for facts that stay fixed, like vocabulary or formulas.

It breaks for everything that changes. A fixed calendar assumes the note is still correct on day 30, which for anything tied to an external source is a bad bet. Reviewing a stale note on schedule just rehearses the wrong version more efficiently. What you want is not only review at intervals but resurfacing by relevance, the old note coming back when it connects to what you are reading now, and getting checked against the current source when it does.

## A system that resurfaces and re-checks what you read

Here is what a reading system looks like when it handles both halves. It has three moves, and only the first one is manual.

Capture in your own words, not the author's. If frequent pauses disrupt your concentration, build a short note-taking session into your [daily reading routine](https://ctrlgamers.com/daily-reading-made-easy-how-many-minutes-you-need), giving yourself five minutes afterward to summarize the main ideas. A note that says "the key claim is X, and it matters because Y" is a retrieval you already performed. A raw highlight is a photograph of a sentence you will not reread. This is the literature-note idea at the heart of a [zettelkasten](https://scribelet.app/blog/zettelkasten-with-ai), and it is the one step worth the friction.

Connect it, automatically. A note you can find is worth ten you cannot. When a new book note links to the three older notes it relates to, the ideas start reinforcing each other instead of decaying in isolation. Scribelet's auto-linker proposes those connections as you write, so the web builds itself instead of waiting for you to remember what you already saved.

Resurface and re-check, without you asking. This is the part manual systems cannot scale past about fifty sources. Background agents bring an old note back when it becomes relevant again, and [background verification](https://scribelet.app/learn/ai/ai-verification) searches the web, compares what it finds to what you wrote, and shows you a diff when the source has moved on. Green for new information, red for what is now outdated. You review, accept or dismiss, and the note you took eight months ago is still true today. It is the same maintain-it-for-you idea behind an [AI second brain that doesn't go stale](https://scribelet.app/blog/ai-second-brain-setup), applied to the specific problem of holding onto what you read.

Honest tradeoff: this pays off for reading tied to external sources, technical books, research, anything with facts that move. For a novel you read once for pleasure, a maintained note is overkill, and that is fine. Not everything you read needs to be remembered.

## Connect what you read to what you already know

There is a reason the same idea sticks the second time you meet it. Memory is associative. An isolated fact has nothing to hang on and slides off. A fact wired into things you already understand has a dozen handholds. This is why the strongest reading advice is not "review more" but "relate more," asking how the new idea fits, contradicts, or extends what you have already read.

The problem is that you cannot relate a new note to an old one you have forgotten you wrote. Nobody holds four hundred notes in their head well enough to notice that the chapter they just read answers a question they wrote down last year. This is where the connecting has to be done for you. Semantic search finds the older notes a new one relates to by meaning rather than by exact words, and a knowledge graph keeps those relationships so the next time you read something adjacent, the earlier thinking surfaces with it. The web of what you have read becomes navigable instead of a pile, and navigable is the difference between a note you can use and a note you technically own.

When you want to pull an idea back deliberately, you can also just ask. AI chat that searches your own notes answers "what did I read about spaced repetition" with the actual notes you wrote and a link to each, not a generic web summary. It is retrieval on demand from a library you built, which is a very different thing from a search engine.

## How to remember what you read without taking notes

Sometimes you finish a chapter on a walk and the last thing you want is to sit and write. You can still hold onto it. The trick is to capture the reaction, not transcribe the passage. Say the one idea out loud, in your own words, and let it become a structured note later. Speak "the argument here is that habits beat goals, and I want to use that for the onboarding rewrite," and voice transcription turns it into a titled, tagged note with the thought intact.

It is a lower bar than the highlight-everything approach, and it retains more, because the act of saying the idea in your own words is itself the retrieval that builds memory. When you do want the reviewing done for you, our [thirty-minute weekly review system](https://scribelet.app/blog/keep-notes-up-to-date) covers the manual cadence, and the background version does it while you read the next thing.

## Reading retention approaches, compared

Every method captures something. The differences show up months later, in whether the captured version is still there and still true.

| Approach | Captures the idea | Resurfaces it later | Stays accurate over time | Scales past ~50 sources |
|---|---|---|---|---|
| Highlights only | Weakly (a swipe, not a thought) | No | No | No |
| Flashcards (Anki) | Yes, if you make cards | Yes, on a fixed schedule | No, cards freeze on creation | Rarely (deck upkeep is heavy) |
| Manual second brain | Yes | Only if you review by hand | No, notes decay untouched | No |
| A maintained system | Yes, in your own words | Yes, by relevance and schedule | Yes, re-checked against sources | Yes, agents do the upkeep |

The first three columns are where most reading advice lives. The last two are why you still forget after doing everything right.

## You don't have a memory problem

The reason last year's reading is gone is not that your memory failed. It is that the notes you made to hold it were left to rot, and no advice about active recall fixes a note that nobody reopens. Encoding gets the idea in. Maintenance is what keeps it there.

Read actively, capture in your own words, and then let a system resurface and re-check what you saved so the version you reach for a year from now is still the version that was true. That is the half the guides skip, and it is the half that decides whether you remember what you read. [Start a reading system that reads itself back](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>reading</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[11 Google Keep alternatives in 2026, sorted by what you outgrew]]></title>
            <link>https://scribelet.app/blog/google-keep-alternative</link>
            <guid isPermaLink="false">https://scribelet.app/blog/google-keep-alternative</guid>
            <pubDate>Thu, 23 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The 11 best Google Keep alternatives in 2026, with a pick-it or skip-it verdict for each and a table showing what survives a Google Takeout export. Sorted by the reason you're leaving.]]></description>
            <content:encoded><![CDATA[
The Google Keep wall used to be two taps and done. Now it's four hundred colored cards deep, "I know I wrote that down" no longer means you can find it, and you're in the search bar looking for a way out. Something specific pushed you here. Maybe it's that scroll you can't navigate anymore. Maybe you're tired of Google reading everything you write and you want off the account entirely. Maybe you saw "is Google Keep being discontinued" trending and got nervous about trusting years of notes to a company famous for shutting things down.

Here's what most "best Google Keep alternative" lists get wrong. They hand you eight apps ranked by popularity and leave you to work out which one fixes your actual complaint. So this roundup is sorted by the reason you're leaving, not by a ranking. Every app gets a plain pick-it or skip-it verdict, there's an at-a-glance table so you can scan it in ten seconds, and there's a migration table showing what actually survives when you export from Keep. Several of the picks aren't ours. One of them is, for a reason no other app on this list covers.

## The 11 best Google Keep alternatives at a glance

| App | Best for | Where your notes live | Free tier | Checks accuracy |
|---|---|---|---|---|
| Simplenote | Pure fast text and lists | Simplenote's cloud | Yes | No |
| Apple Notes | The direct swap on Apple devices | Apple's cloud | Yes | No |
| Zoho Notebook | The closest visual match to the card wall | Zoho's cloud | Yes | No |
| Notesnook | De-Googled, encrypted, Keep-like | Encrypted, unreadable to host | Yes | No |
| Standard Notes | Long-term zero-knowledge privacy | Encrypted, unreadable to host | Yes | No |
| Joplin | Open source and self-hosting | Your own storage, encrypted | Yes | No |
| Obsidian | Local Markdown and linking | Local files you own | Yes | No |
| Microsoft OneNote | Free structured notebooks | Microsoft's cloud | Yes | No |
| Notion | Databases and structure | Notion's cloud | Yes | No |
| Bear | Markdown that looks good on Apple | iCloud | Limited | No |
| Todoist | If Keep was really your to-do list | Todoist's cloud | Yes | No |
| Scribelet | Notes that stay accurate over time | Encrypted, BYOK optional | Yes (10 checks/mo) | Yes |

That last column is the one every roundup leaves out, and it is the reason this article exists. More on it below.

![Decision map matching each reason for leaving Google Keep to a best-fit tool: outgrew the sticky-note wall maps to Notion or Obsidian, want off Google maps to Standard Notes or Joplin, afraid Google will kill it maps to a portable markdown app, and notes that stay accurate maps to Scribelet](/blog/google-keep-alternative/pick-by-reason.svg)

## What's actually pushing people off Google Keep

Spend ten minutes in any [Google Keep alternatives thread](https://www.reddit.com/r/degoogle/comments/1aec1to/google_keep_alternative_that_isnt_awful/) and the same complaints repeat. They sort into a handful of reasons, and the right alternative is completely different for each one.

The most common one is simply outgrowing it. Keep was built for speed, not scale: a flat wall of cards, colors, and labels, with no folders, no note-to-note links, and no backlinks. It's wonderful for a grocery list and hopeless for the two hundred ideas, meeting notes, and clippings you actually accumulated. A second group wants out of Google's orbit, because Keep gives you no end-user encryption and Google can read your notes. A third group is spooked by the [Google graveyard](https://killedbygoogle.com/) and wants a note format they can walk out with. And there's a fourth reason that rarely makes the lists, the one we built around: Keep shows you what you captured, but never tells you whether any of it is still true.

Sort by your reason and the field below shrinks to one or two real candidates.

## If you outgrew the flat wall of cards

### Notion

**Pick it if** you want real structure. Notion's pages, subpages, and databases give you the hierarchy and filtered views Keep's labels never could, and it's free for personal use.

**Skip it if** you want to open an app and just write. Notion asks you to design your system before it helps you, and your notes live in Notion's cloud rather than anywhere you own. It's also a stop plenty of people eventually leave, so read [what actually sends people looking for a Notion replacement](https://scribelet.app/blog/notion-alternative) before you rebuild your whole life there.

### Obsidian

**Pick it if** you want retrieval as a first-class feature. Instead of databases it gives you links, backlinks, and a graph, and it stores plain Markdown files on your own disk with no lock-in.

**Skip it if** you don't want to become the administrator of your own note-taking. The mobile app plus paid sync catch some Keep refugees off guard. Torn between the two structured picks? Our [Notion vs Obsidian comparison](https://scribelet.app/blog/notion-vs-obsidian) goes deeper on which one fits which brain. Either way, check [what true cross-platform note-taking takes](https://scribelet.app/blog/cross-platform-note-taking-app) first, because a painful share of migration regret is landing in a desktop-first app where mobile was an afterthought.

### Microsoft OneNote

**Pick it if** you want free, deep structure and you already live in Microsoft's world. Tabbed notebooks handle everything from a sticky note to an organized research binder, and it runs on every platform Keep does. If you're weighing the two directly, we sorted [the OneNote side of that decision](https://scribelet.app/blog/onenote-alternative) too.

**Skip it if** you want something light. OneNote's freeform canvas gets messy fast, and your notes sit in Microsoft's cloud, which is a lateral move if leaving Google's orbit was the point.

## If you loved the sticky-note wall and just want a better one

### Zoho Notebook

**Pick it if** the thing you liked about Keep was the visual card wall. Zoho Notebook is the closest look-and-feel match on this list: colored cards, quick capture, checklists, and free across platforms.

**Skip it if** you're leaving to escape big-company ecosystems. You're trading Google's account for Zoho's, and sync can be uneven on the free tier.

### Simplenote

**Pick it if** you want Keep's speed with none of the clutter. Simplenote is a free, fast, cross-platform app for plain text and lists that syncs everywhere and gets out of your way.

**Skip it if** you leaned on images, drawings, reminders, or color coding. Simplenote is text only, on purpose. It's minimalism as a feature, not an oversight.

### Apple Notes

**Pick it if** every device you own has an apple on it. It's the cleanest direct swap for iOS and Mac, free, fast, with folders, checklists, and scribble built in.

**Skip it if** you touch Android or Windows regularly. The web version is thin and there's no real cross-platform story, so you're trading Google lock-in for Apple lock-in.

## If you're trying to get off Google

This is the reason that fills r/degoogle. You want your notes out of a Google account and into something the vendor can't read.

### Notesnook

**Pick it if** you want a de-Googled notebook that still feels like Keep. Notesnook is open source and end-to-end encrypted, so the company hosting your notes literally cannot open them, and it runs across every platform Keep does with a genuinely usable free tier.

**Skip it if** you want AI help with your notes. The same encryption that makes it private means no server-side feature, including AI, can read your content. That's the honest tradeoff of zero-knowledge, and it's worth making on purpose.

### Standard Notes

**Pick it if** longevity is the point. Standard Notes is built to still be readable in twenty years, with zero-knowledge encryption and a deliberately boring, durable core.

**Skip it if** you want rich formatting for free. The free tier is plain text; the nicer editors and features sit behind a subscription.

### Joplin

**Pick it if** you typed "google keep self hosted alternative" into the search bar. Joplin is open source with end-to-end encryption and the option to run your own sync server, which is the real answer for full ownership.

**Skip it if** you want polish out of the box. The interface is utilitarian and self-hosting is setup work, not a toggle. Before you commit to any encrypted pick, it helps to know [which secure note app fits your threat model](https://scribelet.app/blog/secure-note-taking-app), because the strongest privacy choice is also the one that can never help you with your notes.

## If you mostly used Keep for reminders and lists

### Todoist

**Pick it if** you're honest that Keep was really your to-do list. Todoist is best-in-class for tasks, due dates, and recurring reminders, and it's far better at that job than Keep ever was.

**Skip it if** you actually keep notes, clippings, and long-form thoughts. Todoist is a task manager, not a notebook, and it will fight you the moment a note is longer than a line.

### Bear

**Pick it if** you're on Apple and you want writing that looks good. Bear is a fast, tag-based Markdown app with a clean design that Keep never attempted.

**Skip it if** you need Android or Windows, or a free sync tier. Bear is Apple-only and cross-device sync sits behind its subscription.

## If you're afraid Google will kill it, own a portable format

If the thing that drove you here was the fear that Keep will one day join the graveyard, understand what you're really protecting against: not a bad app, but a stranded archive. The defense isn't a specific competitor. It's owning your notes in a format you can walk out with.

That points at plain Markdown. A Markdown note is a text file you can read in any editor, on any operating system, for the next twenty years, with or without the app that made it. Our roundup of the [best markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) weighs each option on exactly this: portability, no lock-in, and whether the app puts export front and center. Pick for the exit, and it stops mattering whether any one company sticks around.

Plain text is the closest thing to an escape hatch this whole category offers. It keeps your notes portable. It does not, on its own, keep them true.

## The reason that isn't on the other lists: notes that stay accurate

If what you loved about Keep was firing a thought into a card in two seconds, and what wore you down is that "everything" became years of notes nobody weeds and nothing checks, the missing piece isn't a prettier grid or a folder tree. It's a tool that keeps your notes accurate without you auditing them by hand. That's the fourth reason, and the one Scribelet is built for.

Scribelet keeps the parts Keep users care about. Capture stays fast, notes connect with [wikilinks](https://scribelet.app/learn/notes/wikilinks-backlinks) instead of floating as isolated cards, and it runs natively on iOS, Android, and web, so there's no second-class platform. Then it adds the layer none of the others have: background agents search the web on a schedule you set, compare what they find against what you wrote, and surface the difference as a diff, green for new information, red for what's outdated, with a source link on every change. That's [how background verification works](https://scribelet.app/learn/ai/ai-verification).

Most AI in note apps is reactive. You ask a question, it answers from your notes. Google has started bolting Gemini onto Keep for exactly this kind of help. It's useful for drafting and search, but reactive AI only helps when you already suspect something is wrong and think to ask. The far more common case is the note you trust without checking, the one that quietly went stale months ago. Our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why this happens to every note, in every app, not just yours.

![Comparison of reactive AI, which only answers when you prompt it, and proactive verification, which searches the web on a schedule, checks your note against what it finds, and surfaces a diff for review](/blog/google-keep-alternative/reactive-vs-proactive.svg)

Picture a research note you dropped into Keep two years ago, citing a study that has since been retracted. According to [Retraction Watch](https://retractionwatch.com/), paper retractions have grown roughly tenfold since 2000, so this is not a rare edge case. In Keep the card still looks fine. With scheduled verification, the retraction shows up as a diff before you build on it again.

You can also keep control of the AI itself. [Bring your own key](https://scribelet.app/blog/byok-ai) and route through OpenAI, Anthropic, or Gemini, with the key encrypted at rest, so your notes go to the provider you trust rather than one Google chose for you. It's optional; the AI works out of the box, and the free plan includes ten verifications a month, enough to point at your ugliest Keep exports before paying anything.

> **Tired of being your own maintenance department?** Start free, run your first verification, and see what a diff actually catches. The [Pro plan](https://scribelet.app/pricing) is $8/mo or $79/yr when you want the full set.

The honest tradeoff: Scribelet isn't free the way Keep is, it isn't a zero-knowledge vault, and it isn't a folder of local files you mold with plugins. If a truly free app, self-hosting, or handwriting is the point for you, Keep itself, Joplin, or Obsidian will fit better. Scribelet is for people who want their notes to stay accurate, not just stay captured.

## Before you switch: what survives a Google Keep export

Here's the part that decides whether a migration is painless or a weekend lost. Google Keep has no in-app "export note" button. The only way out is [Google Takeout](https://takeout.google.com/), which hands you your notes as HTML and JSON files, one per note, plus your attachments in a folder. There is no format that carries everything across, so it pays to know what you'll lose before you pick a destination.

| Destination | Keep import path | What survives | What breaks |
|---|---|---|---|
| Notesnook | Built-in Google Keep importer (Takeout ZIP) | Note text, titles, labels become notebooks | Reminders, colors, note pinning |
| Joplin | Takeout via an importer or converter | Text and tags | Reminders, colors, layout |
| Obsidian | Community Takeout-to-Markdown importer | Text as Markdown, labels as tags, images as attachments | Reminders, colors, checkbox state can flatten |
| Notion | Convert Takeout HTML, then import | Text and basic structure | Labels (manual), image placement, reminders |
| Simplenote | Manual paste, or a text converter | Plain text only | Images, checklists, labels, colors |
| Apple Notes | Open Takeout HTML and copy, or a third-party tool | Text and most images | Labels, reminders, checkbox state |
| Scribelet | Import Markdown or plain text, then verify | Text, and background checks then flag anything stale | Colors and reminders (not the model), so re-tag on the way in |

The pattern is consistent: text always survives, and reminders, colors, and pinning almost never do. If those Keep extras matter to you, budget an hour to recreate them, and treat the move as the rare moment your whole archive is in front of you. That makes it the best chance you'll get to [audit your notes while you move them](https://scribelet.app/blog/evernote-alternative) instead of quietly rebuilding the same graveyard somewhere nicer.

## Is Google Keep being discontinued?

No. Despite the recurring rumors, Google Keep is not being discontinued. Google gave it a Material 3 redesign, folded it deeper into Workspace, and has been adding Gemini-powered features rather than winding it down. The "is Google Keep being discontinued" searches are driven by Google's reputation, not by any announcement.

That distinction is exactly why so many people are still shopping. You don't have to believe Keep is dying to want out of it. A tool you're nervous about trusting is a tool you've already half-left.

## Is there a better app than Google Keep?

There's no single better app, because "better" depends on the reason you're leaving. Keep is genuinely excellent at one thing: firing a short note or list into a card in two seconds, on any device, for free. If that's all you need, nothing here beats it. The apps above are better than Keep at structure (Notion, OneNote, Obsidian), at privacy (Notesnook, Standard Notes, Joplin), at looking like the old card wall (Zoho Notebook), at tasks (Todoist), and at keeping notes accurate over time (Scribelet). Match the app to your complaint and one of them is clearly better for you.

## What are the best Microsoft alternatives to Google Keep?

If you're leaving Google specifically for Microsoft's ecosystem, the answer is **Microsoft OneNote**, which is free, cross-platform, and far more structured than Keep. Windows also syncs its built-in **Sticky Notes** to your Microsoft account and across devices, which is the closest one-to-one swap for Keep's quick-capture cards. Both keep your notes inside Microsoft's cloud rather than Google's, so choose them if the goal is switching ecosystems, not escaping big-company clouds entirely.

## So which Google Keep alternative should you pick?

The right alternative is the one that fixes the specific reason you went looking. Sort by your reason, and the field of apps like Google Keep shrinks to one or two real candidates.

| Why you're leaving Google Keep | Best fit |
|---|---|
| Outgrew the flat wall of cards | Notion, Obsidian, or OneNote |
| Miss the card wall, just want it done right | Zoho Notebook or Simplenote |
| Want off Google entirely | Notesnook, Standard Notes, or Joplin |
| Want a free app you can self-host | Joplin |
| Afraid Google will shut it down | Any portable Markdown app |
| Really just needed a to-do list | Todoist |
| Notes that stay accurate over time | Scribelet |

The best Google Keep alternative isn't the one with the longest feature list or the most upvotes. It's the one that solves the exact thing that made you start searching. Sort by your reason first, and the choice gets a lot simpler.

If the thing that wore you out was watching a fast little capture app fill up with notes nobody ever checked, that's the reason worth fixing for good. [Start writing with background verification and see your first diff](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>google-keep-alternative</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>cross-platform</category>
            <category>knowledge-decay</category>
            <category>privacy</category>
        </item>
        <item>
            <title><![CDATA[The commonplace book was never meant to sit still]]></title>
            <link>https://scribelet.app/blog/commonplace-book</link>
            <guid isPermaLink="false">https://scribelet.app/blog/commonplace-book</guid>
            <pubDate>Wed, 22 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A commonplace book collects the ideas worth keeping, then goes stale. Here's how the 400-year-old method works, and how to keep yours alive. Try it free.]]></description>
            <content:encoded><![CDATA[
Somewhere in your notes app is a passage you copied out two years ago because it felt important. A line from a book, a definition you wanted to remember, an argument you meant to use. You have not reopened it since. That is a commonplace book, and that is exactly how most of them end: full, and never read back.

The method is having a moment. Search interest in the commonplace book is up more than fifty percent year over year, and the guides all promise the same thing, that copying out the best ideas you meet will make them yours. They are half right. The copying is the easy half. What almost nobody explains is what the collection is worth once it stops growing and starts aging, which it does the moment you close the cover.

This is a guide to the method, honestly. What a commonplace book is, what goes in one, how it differs from a journal or a zettelkasten, and the one thing four hundred years of keepers have never had a good answer for: a way to read the thing back.

## What is a commonplace book?

A commonplace book is a personal collection of quotes, passages, ideas, and observations gathered from your reading and experience into one place. It is not a diary of your own life. It is a curated store of other people's thinking that struck you as worth keeping, copied out in your own hand so it sticks.

The form is old. Enlightenment scholars kept them as a matter of course. John Locke published a formal indexing method for them in 1706. Marcus Aurelius, Montaigne, Francis Bacon, Thomas Jefferson, and Virginia Woolf all kept some version of one. The modern revival owes a lot to Ryan Holiday, whose essay on [how and why to keep a commonplace book](https://ryanholiday.net/how-and-why-to-keep-a-commonplace-book/) put index cards back in circulation, and to the plain fact that [the practice](https://en.wikipedia.org/wiki/Commonplace_book) predates the printing press and has outlived every note-taking fad since.

The appeal is real. Reading is leaky. You finish a book and keep maybe three ideas from it a month later, which is the whole problem of [how to remember what you read](https://scribelet.app/blog/how-to-remember-what-you-read). A commonplace book catches the ones you decided were worth catching, and the act of copying them out, slowly, in your own words or verbatim with attribution, does more for memory than a highlight ever will.

## What should be in a commonplace book?

Anything you want to be able to find again and think with later. There is no schema. Common entries include:

- **Quotes and passages** that stopped you mid-page, copied with their author and source.
- **Definitions** of terms you want to own, in words you understand.
- **Arguments and frameworks** worth reusing, stripped down to their bones.
- **Observations** of your own that belong next to what you are reading.
- **Questions** a book raised that it did not answer.

The famous commonplace book examples are less orderly than you would expect. Bill Gates is known for margin notes and reading logs. Ronald Reagan kept a box of index cards with quotes and jokes. The value was never in the tidiness. It was in having one place where the good stuff accumulated, so that a decade of reading became a resource instead of a fog.

How you organize it matters less than whether you can find things again. Locke's 1706 system indexed entries by the first letter and first vowel of a keyword, an ingenious workaround for a paper book with no search bar. That constraint is gone now, and its disappearance changes the method more than most guides admit. In a digital commonplace book the index is automatic. The effort that keepers used to spend on filing can finally go to the part that was always neglected: going back to what you filed. The same shift, from filing things away to being able to ask them questions, is what lets you [catalogue a collection of objects](/blog/how-to-catalogue-a-collection), not just a collection of ideas.

## Commonplace book vs journal vs zettelkasten

People searching for the method usually want to know how it differs from the two systems next to it. The short version: a journal holds your life, a commonplace book holds other people's ideas, and [the zettelkasten method](https://scribelet.app/blog/zettelkasten-with-ai) holds your own ideas, developed and linked. They answer different questions.

| System | What it holds | Written by | The missing step |
|---|---|---|---|
| Journal | Your days, feelings, events | You, about you | Rarely reread |
| Commonplace book | Quotes, passages, ideas you collect | Others, curated by you | Never resurfaced or checked |
| Zettelkasten | Atomic, developed notes, linked | You, thinking | Manual linking gets abandoned |
| Digital garden | Evergreen notes grown in public | You, tending | Everyone plants, nobody weeds |

The pattern down that last column is the point. Every one of these methods is excellent at capture and organization, and every one of them stops at the same place. None of them has a built-in answer for what happens to an entry after you file it. That gap is the [step every PKM system skips](https://scribelet.app/blog/personal-knowledge-management), and the commonplace book skips it hardest, because collection is the entire premise.

## The problem nobody mentions: it is a collect-and-forget archive

Here is the uncomfortable part the guides leave out. A commonplace book is a one-way street. Ideas go in. Almost nothing ever comes back out. You add the passage, you feel the small satisfaction of having caught it, and then it sits, unread, while you fill the next page.

![Two shapes side by side: a traditional commonplace book drawn as a one-way funnel where entries pour in and stop, and a living version drawn as a loop where entries are connected, resurfaced, verified, and pruned before returning to use](/blog/commonplace-book/collect-vs-maintain.svg)

Worse, the entries do not just sit still. They rot. A quote you copied is only as reliable as its source, and sources move, get corrected, get retracted, or vanish. Link rot is measurable and severe: writing in The Atlantic, Jonathan Zittrain reported that [a quarter of deep links in New York Times articles were already dead](https://www.theatlantic.com/technology/archive/2021/06/the-internet-is-a-collective-hallucination/619320/), and half the links in U.S. Supreme Court opinions pointed to nothing. The passage you trusted enough to copy is aging on the page, and a paper archive gives you no way to know.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay) in its oldest form. The commonplace book was built to fight forgetting, and it half-succeeds: it remembers the words, but not whether the words are still true, still sourced, still connected to the thing you were thinking when you wrote them down. Adding to a collection is not the same as maintaining it, the same way [adding to a garden is not the same as tending one](https://scribelet.app/blog/digital-garden).

## The digital commonplace book makes collecting easier and forgetting worse

The obvious fix is to go digital, and most people have. A digital commonplace book, whether it lives in a plain text file, Notion, Obsidian, or a folder of Markdown, removes every bit of friction from capture. You can clip a passage in two seconds from your phone. That is genuinely better than hunting for a pen.

But friction was doing quiet work. When copying a quote cost you a minute of handwriting, you copied only what mattered. When it costs two seconds, you collect everything, and the pile grows faster than any human will ever reread it. The modern commonplace book solves the capture problem so thoroughly that it makes the real problem, resurfacing and upkeep, dramatically worse. A digital archive also hides its own staleness better than paper does. A worn notebook at least looks old. A search result looks identical whether you saved it yesterday or five years ago.

## What the method has always been missing: a way to read it back

The commonplace book has needed one thing since Locke, and it is not a better way to write things down. It is a way for the collection to work while you are not looking at it. Three things, specifically.

**Resurfacing.** An entry you never see again might as well not exist. A living commonplace book brings old passages back into view when they are relevant to what you are reading or writing now, instead of waiting for you to remember they are there.

**Connection.** A quote gains meaning next to related quotes. In Scribelet, notes [connect with wikilinks](https://scribelet.app/learn/notes/wikilinks-backlinks), and background agents propose links between entries automatically, so a passage about attention from a neuroscience book finds the one you saved from a Stoic three years earlier. The collection becomes a graph instead of a stack.

**Verification.** This is the part no notebook can do. Background agents search the web on a schedule you set, compare what they find against what you saved, and surface the difference as a diff, green for new information, red for what is outdated, with a source link on every change. That is [how background verification works](https://scribelet.app/learn/ai/ai-verification). The retracted study you quoted, the statistic that has since doubled, the framework the author later walked back: they show up as a flagged change before you build on them again.

None of this asks you to abandon the habit that made the commonplace book worth keeping. You still read, you still copy out the lines that matter, you still decide what earns a place. The difference is only in what happens next. Instead of a collection that quietly ages the moment you look away, you get one that keeps working, connecting new entries to old ones and checking that what you saved is still worth having saved.

You keep control of the AI, too. Scribelet's AI works out of the box, and you can optionally bring your own key and route through OpenAI, Anthropic, or Gemini, encrypted at rest, so your notes go to the provider you trust rather than one we picked for you.

> **Your best passages deserve better than a drawer.** Start free, point verification at the quotes you most want to still be true, and see what a diff catches. The [Pro plan](https://scribelet.app/pricing) is $8/mo or $79/yr when you want the full set.

## How to keep a commonplace book that stays alive

The method still works. It just needs one habit the classic version never included: reading it back. A commonplace book that stays useful runs on a short loop.

1. **Capture** the passage, quote, or idea the moment it lands, without overthinking the filing.
2. **Attribute** it. Author, source, and a link if there is one, so the entry can be checked later.
3. **Connect** it to what it relates to, so it lives in a web, not a list.
4. **Resurface** it on a schedule. Let old entries come back into view rather than waiting to stumble on them.
5. **Verify** the ones that make factual claims, so a quote whose source has changed does not sit there looking authoritative.
6. **Prune** what no longer earns its place. A smaller collection you trust beats a huge one you do not.

Steps four through six are the ones every guide skips, and the only ones that keep the collection from becoming an archive. If you want the manual version, our [thirty-minute weekly review system](https://scribelet.app/blog/keep-notes-up-to-date) walks through doing it by hand.

## Did Marcus Aurelius keep a commonplace book?

Not exactly, but close enough that he is always in the conversation. Meditations reads like a private notebook of borrowed and refined ideas, what the Greeks called hypomnemata, personal notes-to-self drawn from his reading and reflection. It is the spirit of the commonplace book: collecting the best of what others thought, in order to live and think better with it. The irony is that his notebook survived because it was read back, endlessly, by everyone but him.

## Collect like it matters, because it does

The commonplace book is the oldest good idea in note-taking, and it has always been half an idea. Gathering the passages worth keeping is worth doing. But a collection that only ever grows is a collection that slowly stops being true, one dead link and one forgotten page at a time.

Keep the practice. Add the missing half. Let the ideas you collected come back to you, connect to each other, and get checked while you are busy reading the next thing. [Start a commonplace book that reads itself back](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>commonplace-book</category>
            <category>pkm</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[11 OneNote alternatives in 2026, sorted by why you're leaving]]></title>
            <link>https://scribelet.app/blog/onenote-alternative</link>
            <guid isPermaLink="false">https://scribelet.app/blog/onenote-alternative</guid>
            <pubDate>Tue, 21 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Eleven OneNote alternatives compared, then sorted by the reason you're actually leaving: a retired app, Microsoft lock-in, an unsearchable canvas, or notes that quietly went stale.]]></description>
            <content:encoded><![CDATA[
You didn't wake up wanting a OneNote alternative. Something specific sent you to the search bar. Maybe Microsoft retired the OneNote app you'd used for years and turned your notebooks read-only. Maybe the free-form canvas that felt liberating in 2015 turned into a swamp you can't search. Maybe you're just done keeping a decade of notes inside a proprietary format tied to a Microsoft account you'd rather not depend on.

Here's what every "best OneNote alternative" list gets wrong. They hand you ten apps ranked by popularity and leave you to work out which one fixes your actual complaint. A tool that's perfect for someone who wants a free open-source notebook is useless to someone who just needs their notes to work on Linux, or to stop quietly going out of date. And if your real question is OneNote against one specific rival rather than the whole field, [our Notion vs OneNote comparison](https://scribelet.app/blog/notion-vs-onenote) weighs those two round by round.

So here are eleven alternatives worth knowing, compared first on the things that decide a switch, then sorted by the reason you're leaving rather than by a ranking. We name the honest best pick for each reason, including several that aren't ours. And we're upfront that one of them is ours, for one reason no other tool on this list covers.

## The 11 OneNote alternatives at a glance

| App | Price | Platforms | Where your notes live | Checks accuracy | Best for |
|---|---|---|---|---|---|
| New OneNote app | Free with Microsoft 365 | Windows, Mac, web, mobile | Microsoft cloud (OneDrive) | No | Staying in the Microsoft world |
| Notion | Freemium | All, plus web | Notion's cloud | No | Structure and databases |
| Joplin | Free | All, including Linux | Your own storage, encrypted | No | OneNote's hierarchy, kept open |
| Obsidian | Freemium | Desktop and mobile | Local Markdown files you own | No | Plain files and linking |
| Zoho Notebook | Freemium | All, plus web | Zoho cloud | No | A free, OneNote-like feel |
| Standard Notes | Freemium | All, plus web | End-to-end encrypted cloud | No | Privacy above everything |
| Capacities | Freemium | Desktop, mobile, web | Capacities cloud | No | Object-based notes |
| Evernote | Freemium | All, plus web | Evernote cloud | No | Web clipping and deep search |
| Apple Notes | Free | Apple devices, web | iCloud | No | Fast capture on Apple |
| GoodNotes | Freemium | iPad, iPhone, Mac, Windows | GoodNotes cloud | No | Handwriting and stylus |
| Scribelet | Free tier, Pro $8/mo | iOS, Android, web | Encrypted, BYOK optional | Yes | Notes that stay accurate |

Read that table as a starting filter, not a verdict. The column that matters is the one attached to your reason for leaving, which is what the rest of this guide sorts by.

## What's actually pushing people off OneNote

Spend ten minutes in any [OneNote alternatives thread](https://www.reddit.com/r/OneNote/comments/1dw0rtb/onenote_alternatives/) and the same complaints repeat. They sort into a handful of reasons, and the right alternative is completely different for each one.

The loudest one right now is Microsoft's own doing. OneNote for Windows 10, the version millions of people actually opened every day, [reached end of support](https://support.microsoft.com/en-us/office/what-is-happening-to-onenote-for-windows-10-2b453bfe-66bc-4ab2-9118-01e7eb54d2d6) on October 14, 2025. It's now read-only: you can look at your notes, but you can't edit or sync them in that app, and there are no more updates or security patches. Microsoft consolidated everything into a single OneNote app on Windows. OneNote itself isn't dead, but for a lot of people a forced migration is a forced migration, and if you have to move anyway, you might as well shop around.

Others have a quieter, older complaint. OneNote stores your notes in a proprietary format synced through OneDrive, there's no clean way to export the whole thing to plain files, and there's still no native Linux app. The free-form canvas that lets you drop anything anywhere is glorious for a stylus and miserable for finding a note two years later.

There's a fifth reason that rarely makes the lists, and it's the one we built around. OneNote shows you notebooks, sections, and pages. It never tells you whether anything inside them is still true. If that resonates, our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why it happens to every note, in every app, not just yours.

![Decision map matching each reason for leaving OneNote to a best-fit tool: Microsoft retired the app to the new OneNote or Notion, done with the ecosystem to Obsidian or Joplin, a messy canvas to Notion or Obsidian, handwriting to GoodNotes, and notes that stay accurate to Scribelet](/blog/onenote-alternative/pick-by-reason.svg)

## If the Windows 10 app just went read-only

If your OneNote for Windows 10 notebooks went read-only overnight, you need somewhere to land that imports what you already have without a fight. Three picks cover the range from "least disruption" to "clean break."

### New OneNote app

The lowest-friction move is the one Microsoft wants: the current OneNote app on Windows, free with Microsoft 365, which imports your existing notebooks and keeps them syncing through OneDrive. Nothing to migrate, nothing to relearn.

**Pick it if** the retirement is your only complaint and you're otherwise happy in OneNote. **Skip it if** getting away from OneNote was the whole point, because this keeps you exactly where you were.

### Notion

Notion is the usual next stop for people who want structure. Its pages and subpages map loosely onto OneNote's notebooks and sections, and it adds databases OneNote never had. The tradeoff is that your notes now live in Notion's cloud rather than as anything you own, which is the exact thing a lot of OneNote refugees are trying to leave. Worth knowing before you commit: people leave Notion too, and [a Notion alternative that fits your reason](https://scribelet.app/blog/notion-alternative) is a different pick depending on whether it got slow, got loud with AI, or locked you in.

**Pick it if** you want more structure than OneNote gave you and you can live in the cloud. **Skip it if** file ownership or a proprietary format was the reason you started looking.

### Joplin

If you want to keep OneNote's notebook-section-page hierarchy without Microsoft, [Joplin](https://joplinapp.org/) is the closest match on this list. It's free, open source, keeps that tree structure, stores Markdown, syncs through your own cloud, and has end-to-end encryption built in. It looks and feels like the community project it is, but it does the job, and it has a genuine OneNote importer.

**Pick it if** you want OneNote's shape, your own storage, and no subscription. **Skip it if** a polished, consumer-grade interface matters more to you than openness.

## If you're done with Microsoft and the proprietary format

This is the reason that predates the Windows 10 retirement. You want your notes out of a proprietary format and off a Microsoft account, in something you can read without one specific app.

### Obsidian

Obsidian is the enthusiast's answer. Plain Markdown files on your own disk, no lock-in, and a plugin for almost anything. The cost is that you become the administrator of your own note-taking, and paid sync plus a slower mobile app catch some people out. To see exactly how it measures up against what you are leaving, we put [Obsidian and OneNote side by side](https://scribelet.app/blog/obsidian-vs-onenote) dimension by dimension. If that's where you're heading, we sorted the [Obsidian alternatives by reason for leaving](https://scribelet.app/blog/obsidian-alternative) too, and our roundup of the [best markdown note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) weighs each option on portability. Plain text is the closest thing to an escape hatch this category offers. It keeps your notes portable. It does not keep them true.

**Pick it if** owning plain files is the point and you don't mind assembling the setup. **Skip it if** you want it to work well on mobile the day you install it.

### Standard Notes and Notesnook

If encryption is the actual reason you're leaving, sort out [which secure note app fits your threat model](https://scribelet.app/blog/secure-note-taking-app) before you switch. Zero-knowledge apps like Standard Notes and Notesnook win on privacy precisely because they can't read your notes, which is also why they can't run AI over them or search inside an attachment. That's a deliberate tradeoff, not an oversight.

**Pick it if** default end-to-end encryption is non-negotiable. **Skip it if** you want search, AI, or anything that requires the app to read your content.

### Zoho Notebook

Zoho Notebook is the underrated one on this list. It's free, cross-platform, and it feels closer to OneNote's card-and-notebook metaphor than most of the Markdown tools do, which makes the mental jump smaller. Notes live in Zoho's cloud, and the free tier is generous.

**Pick it if** you want a OneNote-like experience without Microsoft and without paying. **Skip it if** local files or an export you fully control are the requirement.

## If the free-form canvas became impossible to search

OneNote's free-form page is a feature until you have a thousand pages. Then it's a liability. You remember writing something down, you just can't find where you dropped it on which page in which section. The fix is a tool with more structure and real search.

### Capacities

Capacities organizes around objects (people, books, meetings) instead of a blank canvas, so structure emerges as you write and retrieval becomes a first-class feature rather than a scavenger hunt. It's cloud-native and modern, and it reads as the spiritual opposite of a swampy OneNote section.

**Pick it if** you want your notes to self-organize by what they're about. **Skip it if** you'd rather own local files than trust another cloud.

### Evernote

Evernote is the old rival, and its web clipper and search are still genuinely strong, which is exactly what a lost-in-the-canvas OneNote user is missing. The catch is price: the useful tiers are a subscription, and the free plan is tight now. A migration is also the rare moment your whole archive is in front of you, which makes it the best chance you'll get to [audit your archive while you move it](https://scribelet.app/blog/evernote-alternative) instead of quietly rebuilding the same graveyard somewhere nicer.

**Pick it if** web clipping and deep search are what you actually need. **Skip it if** the subscription and the years of feature churn put you off.

### Apple Notes

If you live on Apple devices and the real problem was that OneNote was overkill, Apple Notes is fast, clean, and free. It syncs through iCloud, handles checklists and light sketching, and never asks you to configure anything. It is Apple-only in any way that matters, so it's a non-starter if you touch Windows, Android, or Linux.

**Pick it if** you're all-in on Apple and want frictionless capture. **Skip it if** you need it to work anywhere outside the Apple ecosystem.

Whichever of these you pick, check the platform story before you commit, because OneNote's cross-device sync is one of the things people miss most. A painful share of migration regret is someone landing in a desktop-first or Apple-only app and discovering the mobile experience was an afterthought. It's worth knowing [what true cross-platform note-taking takes](https://scribelet.app/blog/cross-platform-note-taking-app) before you move a decade of notes into something that only really works on one device. For the two tools people weigh most often, our [Notion vs Obsidian comparison](https://scribelet.app/blog/notion-vs-obsidian) goes deeper.

## If you take handwritten notes with a stylus

Let's be honest about a big slice of OneNote's audience. If you use it with a pen on a tablet, to sketch, annotate PDFs, or take handwritten lecture notes, most of the apps above will disappoint you. That's not their job, and it isn't ours either.

### GoodNotes and Notability

GoodNotes and Notability are the polished picks on iPad, with the smooth inking, PDF markup, and handwriting search that made OneNote's pen tools worth using in the first place. Both are freemium, and both are best on Apple hardware.

**Pick it if** handwriting and stylus input are the reason you loved OneNote. **Skip it if** you type your notes and don't own an iPad.

### Xournal++

Xournal++ is the free, open-source stylus option across Windows, Mac, and Linux, and it's the rare handwriting app that runs on Linux at all. It's utilitarian rather than pretty, but it annotates PDFs and takes ink notes without a subscription.

**Pick it if** you want free handwriting on a non-Apple machine, Linux included. **Skip it if** you want a consumer-grade, synced experience out of the box.

## How do I move my OneNote notebooks to another app?

This is the question the ranking lists and the AI overviews skip, and it's the one that actually decides whether a switch sticks. OneNote stores notes in a proprietary `.one` format, so "just export it" is rarely clean. Here's the honest migration path into each destination, and what tends to survive the move.

| Destination | How your OneNote notes get in | Handwriting and ink | The gotcha |
|---|---|---|---|
| New OneNote app | Automatic import of existing notebooks | Preserved | Keeps you in the Microsoft cloud |
| Notion | Export OneNote pages to Word or PDF, then import to Notion | Flattened to images | Free-form layout gets linearized |
| Joplin | Built-in OneNote importer, or export to `.md` first | Mostly lost | Community importer, expect some cleanup |
| Obsidian | Export to Word or PDF, convert to Markdown | Lost | You assemble the pipeline yourself |
| Evernote | Web clipper plus manual copy, or third-party tools | Flattened to images | No first-party OneNote importer |
| Zoho Notebook | Copy and paste, or import from Evernote as a bridge | Lost | No direct OneNote importer |

Two rules survive every row of that table. Typed text and images move; free-form canvas positioning and pen strokes usually don't. And whatever you carry over, a migration copies your notes without checking a single one of them, so a decade of clippings arrives in the new app exactly as stale as it left the old one.

## If you loved free capture but your notebooks became a graveyard

Here's the reason that doesn't make the listicles, and the one Scribelet is built for.

### Scribelet

If what you loved about OneNote was capturing everything in one place, and what wore you down is that "everything" became years of clippings, meeting notes, and half-finished project pages that nobody weeds and nothing checks, the missing piece isn't a prettier canvas. It's a tool that keeps your notes accurate without you auditing them by hand.

Scribelet keeps the parts OneNote users care about. Notes connect with [wikilinks](https://scribelet.app/learn/notes/wikilinks-backlinks). It runs natively on iOS, Android, and web, so there's no second-class platform. Then it adds the layer none of the others have: background agents search the web on a schedule you set, compare what they find against what you wrote, and surface the difference as a diff, green for new information, red for what's outdated, with a source link on every change. That's [how background verification works](https://scribelet.app/learn/ai/ai-verification).

Most AI in note apps is reactive. You ask a question, it answers from your notes. That's useful for drafting and search, and OneNote's own Copilot does it if you pay for it. But reactive AI only helps when you already suspect something is wrong and think to ask. The far more common case is the note you trust without checking, the one that quietly went stale months ago.

![Comparison of reactive AI, which only answers when you prompt it, and proactive verification, which searches the web on a schedule, checks your note against what it finds, and surfaces a diff for review](/blog/onenote-alternative/reactive-vs-proactive.svg)

Picture a research note you clipped into OneNote two years ago, citing a study that has since been retracted. According to [Retraction Watch](https://retractionwatch.com/), paper retractions have grown roughly tenfold since 2000, so this is not a rare edge case. In OneNote the page still looks authoritative. With scheduled verification, the retraction shows up as a diff before you build on it again.

You can also keep control of the AI itself. [Bring your own key](https://scribelet.app/blog/byok-ai) and route through OpenAI, Anthropic, or Gemini, with the key encrypted at rest, so your notes go to the provider you trust rather than one Microsoft chose for you. It's optional; the AI works out of the box, and the free plan includes ten verifications a month, enough to point at your ugliest imported notes before paying anything.

> **Tired of being your own maintenance department?** Start free, run your first verification, and see what a diff actually catches. The [Pro plan](https://scribelet.app/pricing) is $8/mo or $79/yr when you want the full set.

**Pick it if** the thing that wore you out was carrying notes nobody ever checked. **Skip it if** you want a folder of local files, a free self-hosted project, or a web clipper and handwriting to match OneNote's, because Joplin, Obsidian, or GoodNotes will fit those better.

## Is Microsoft phasing out OneNote?

Not entirely. OneNote for Windows 10, the older app that shipped with Windows 10, reached end of support on October 14, 2025 and is now read-only. OneNote itself continues as a single consolidated app on Windows, free and included with Microsoft 365. So OneNote lives on, but the specific version many people used does not.

That distinction is exactly why so many people are shopping. A forced move to a different OneNote app is the moment you ask whether you want to stay in OneNote at all.

## So which OneNote alternative should you pick?

The right alternative is the one that fixes the specific reason you went looking. Sort by your reason, and the field of eleven apps shrinks to one or two real candidates.

| Why you're leaving OneNote | Best fit |
|---|---|
| The Windows 10 app was retired | New OneNote app, Notion, or Joplin |
| Done with Microsoft and the proprietary format | Obsidian, Joplin, or Standard Notes |
| The canvas is impossible to search | Notion, Capacities, or Evernote |
| You want a free, OneNote-like feel | Zoho Notebook or Joplin |
| Handwriting and stylus notes | GoodNotes, Notability, or Xournal++ |
| Notes that stay accurate over time | Scribelet |

That last row is the one every listicle leaves out, and the reason this article exists. If you started on Google Keep rather than OneNote, we sorted [the Google Keep alternatives by what you outgrew](https://scribelet.app/blog/google-keep-alternative) the same way.

## Pick the fix, not the most popular app

The best OneNote alternative isn't the one with the longest feature list or the most upvotes. It's the one that solves the exact thing that made you start searching. Sort by your reason first, and the choice gets a lot simpler.

If the thing that wore you out was carrying a growing pile of notes that nobody ever checked, that's the reason worth fixing for good. [Start writing with background verification and see your first diff](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>onenote-alternative</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>microsoft</category>
            <category>cross-platform</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Secure note-taking apps: what you're actually protecting]]></title>
            <link>https://scribelet.app/blog/secure-note-taking-app</link>
            <guid isPermaLink="false">https://scribelet.app/blog/secure-note-taking-app</guid>
            <pubDate>Sun, 19 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Not every secure note-taking app defends against the same threat. See what encryption actually covers, the AI trade-off no one mentions, and how to choose. Try it free.]]></description>
            <content:encoded><![CDATA[
You searched for a secure note-taking app, and the answers came back fast and confident. Standard Notes. Notesnook. A Reddit thread swearing by both. Every one of them leads with the same two words: end-to-end encryption. Case closed, apparently.

Except "secure" is carrying a lot of weight in that sentence, and nobody stops to unpack it. Secure against whom? A thief who grabs your unlocked phone on a train? A company that quietly reads your notes to train a model? An engineer at the provider with database access? A breach that dumps the whole table onto a forum? Those are four different problems, and a single green padlock in the marketing does not tell you which ones an app actually solves.

This is a buying decision disguised as a feature checkbox. Before you pick, it's worth knowing what the word is hiding, where the real trade-offs live, and why the most private note apps are often the least useful for anything beyond storage.

## What does a secure note-taking app actually protect?

A secure note-taking app is one that encrypts your notes so that people who should not read them cannot, even if they reach the storage. The important question is not whether an app is encrypted. Almost all of them are, in some form. The question is *who holds the key*, because that decides who can read your notes when it matters.

There are three layers, and they are not interchangeable.

**In transit.** Your notes are encrypted while they travel between your device and the server, using TLS. Every credible app does this. It stops someone on the same coffee-shop Wi-Fi, and nothing else. On its own it is table stakes, not a security feature worth naming.

**At rest.** The server encrypts your notes before writing them to disk, so a stolen backup or a raw database dump is unreadable ciphertext. But the vendor holds the keys, because the server has to decrypt your notes to show them to you, index them, or run features over them. At rest protects you from a breach and from an outside attacker. It does not protect you from the vendor.

**Zero-knowledge, also called end-to-end.** Your notes are encrypted on your device before they ever leave it, with a key derived from your password that the server never sees. The provider stores ciphertext it genuinely cannot read. This is what Standard Notes and Notesnook mean by end-to-end encryption, and it is the strongest model: it protects you from a breach, an attacker, *and* the vendor.

So "are note-taking apps safe?" has no single answer. A note app can be safe from a network snoop and wide open to its own operator, or locked so tight that not even the company can help you if you forget your password. The word "secure" spans that entire range. Knowing which layer you actually need is the whole game.

![Table comparing three encryption models (in transit, encrypted at rest, zero-knowledge) against three threats: a network snoop, a server breach, and the vendor](/blog/secure-note-taking-app/encryption-layers.svg)

## Which note-taking app is most secure?

If your requirement is strictly "no one but me can ever read this, including the company," the most secure note-taking apps are the zero-knowledge ones. Here is the honest landscape, without pretending they are all the same.

| App | Encryption model | Who can read your notes | AI over your notes | Open source |
|---|---|---|---|---|
| **Standard Notes** | Zero-knowledge E2EE | Only you | No | Yes |
| **Notesnook** | Zero-knowledge E2EE | Only you | No | Yes |
| **Joplin** | Optional E2EE | Only you (if enabled) | No native | Yes |
| **Obsidian** | Local files, you control the disk | Only you | Plugins only | No (core) |
| **Apple Notes** | Locked notes are E2EE on iCloud | You, and Apple for unlocked notes | Apple Intelligence | No |
| **OneNote** | Password-protected sections | You and Microsoft | Copilot | No |

A few honest notes on that table. [Standard Notes](https://standardnotes.com/) and [Notesnook](https://notesnook.com/) are the purest picks: open-source, audited, encrypted before anything leaves your device. [Joplin](https://joplinapp.org/help/apps/sync/e2ee/) gives you the same guarantee but end-to-end encryption is opt-in, so it protects nothing until you turn it on. Obsidian keeps plain Markdown files on your own disk, which is a different kind of security: there is no cloud to breach because there is no cloud, though sync and backups become your responsibility. Local-first apps like Obsidian are covered in more depth in our [Obsidian alternative guide](https://scribelet.app/blog/obsidian-alternative).

Apple Notes and OneNote are the ecosystem defaults, and if you're leaving OneNote specifically, we sorted [an honest OneNote alternative guide](https://scribelet.app/blog/onenote-alternative) by reason. You can put a password on a note in both, which answers the common "can I put a password on my notes app?" question, but the lock covers individual notes or sections, not everything, and the vendor still processes the rest. The Freedom of the Press Foundation's [guide to secure note-taking for journalists](https://freedom.press/digisec/blog/note-taking-security/) is a good threat-model reference if your notes could put a source at risk. Google Keep sits in the same bucket, an ecosystem default with no end-user encryption controls, so if getting your notes off a Google account is the point, we sorted [the Google Keep alternatives by reason](https://scribelet.app/blog/google-keep-alternative) too.

Pick from that list and you get real privacy. You also, in almost every case, get a note that just sits there.

## The trade-off nobody mentions: encryption versus AI

Here is the part the roundups skip. Zero-knowledge encryption means the server only ever sees ciphertext. That is the entire security model, and it is also a hard ceiling on what the app can do with your notes.

You can't run semantic search over data you can't decrypt. You can't summarize it, cross-reference it, fact-check it, or chat with it. An AI feature that reads your notes needs to, well, read your notes, and a zero-knowledge server structurally can't. This isn't a gap Standard Notes or Notesnook will close with a future release. It's the direct cost of the promise that makes them secure.

So the most private note apps are also the least helpful with what is inside your notes. They are excellent vaults and deliberately nothing more. For a password, a recovery phrase, or a private journal, that is exactly right. For a working knowledge base you actually use, storage was never the hard part.

![Scatter plot of note apps by privacy from the vendor versus AI over your notes, showing the zero-knowledge apps clustered with no AI and the top-right private-plus-AI corner empty](/blog/secure-note-taking-app/security-ai-tradeoff.svg)

And there is a second cost that encryption does not touch at all. A note can be perfectly encrypted and quietly, confidently wrong. The API you documented shipped a breaking change. The pricing you noted went up. The recommendation reversed. Zero-knowledge encryption guards that stale note as faithfully as a true one, because encryption protects the bytes, not the accuracy. We wrote the long version of this as [knowledge decay](https://scribelet.app/blog/knowledge-decay): the slow rot that no lock prevents. A secure note you can't trust is still a liability, just a private one.

Which reframes the question. It was never "which app is most encrypted." It is "what am I willing to trade, and for what."

## A middle path: strong encryption plus AI you control

This is where Scribelet fits, and the honest thing is to draw the line clearly rather than blur it.

Scribelet isn't zero-knowledge. The server can decrypt your notes, because that's what makes verification, chat, and search over your content possible. If your single hard requirement is that not even the vendor can ever read a note, the pure end-to-end apps above are the correct choice, and you should stop reading here.

What Scribelet does instead is encrypt at rest, seriously. Note bodies, chat messages, memories, and verification results are field-level encrypted with AES-256-GCM. Each desk gets its own Data Encryption Key, and those keys are themselves wrapped by a Key Encryption Key held in [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#enveloping) (envelope encryption), so a database dump is useless on its own. That's real protection against a breach and against an outside attacker. It's a deliberate step down from zero-knowledge, taken so the app can actually help maintain what you write.

The trade is narrowed by three controls, not hand-waved away.

**You choose where the AI runs.** With [bring your own key](https://scribelet.app/blog/byok-ai), you connect your own OpenAI, Anthropic, or Gemini account, and your notes go to the provider you already trust rather than one we picked. We encrypt that key at rest and never see your prompts. It is optional, since AI works out of the box, but [connecting your own API key](https://scribelet.app/learn/ai/byok) takes about a minute and puts the data path in your hands. Without it, processing stays on our infrastructure and is not sold or handed to third-party model vendors.

**Your account is hard to reach in the first place.** [Passkeys and two-factor authentication](https://scribelet.app/learn/security/authentication) mean there is no password to phish, and stored secrets use Argon2id hashing. Encryption at rest is on the free plan, not gated behind a paywall.

**The notes get to stay correct.** Because the server can read your notes, background agents can [fact-check them against the web](https://scribelet.app/blog/ai-fact-checking-for-notes) on a schedule you set, and hand you a diff: green for what is current, red for what drifted, with a source for each change. That is the payoff you are accepting a decryptable model to get. A vault can't do it.

Be clear-eyed about the exchange. You give up "even the company cannot read this" and you get a note app that keeps your knowledge accurate instead of just stored. For some threat models that is the wrong trade. For a lot of working professionals, it is the one they actually wanted. Students weighing privacy against AI features can see where the trade sits among the [note apps for students compared](https://scribelet.app/blog/best-note-taking-app-for-students) in our student roundup.

## How to choose a secure note-taking app

Skip the badge comparison and start with the question the badges avoid. Work through these in order.

1. **Name your threat model.** Write down who you are actually protecting against: a device thief, the vendor, a breach, a network snoop, a subpoena. "Everyone" is not a threat model; it is anxiety.
2. **If the answer is "the vendor, always," go zero-knowledge.** Standard Notes or Notesnook. Accept that the app will not read, search, or maintain your notes, and that this is the point.
3. **If device theft is the real fear, you need a lock, not zero-knowledge.** Any app with a passcode or biometric app-lock plus encryption at rest covers it, even Apple Notes locking individual notes.
4. **If you want AI to work over your notes, accept a decryptable model, then raise your standards.** Demand encryption at rest, ask who holds the keys, insist on a no-training guarantee, and prefer bring-your-own-key so you control the data path.
5. **Read the encryption page, not the homepage.** "Bank-grade" and a padlock icon mean nothing. The security or docs page will tell you at rest versus end-to-end, and who can decrypt.
6. **For any zero-knowledge claim, check for open source or an audit.** A promise you cannot inspect is a promise you are taking on faith.
7. **Then confirm the note is still right.** The most secure note in the world is worthless if it is quietly out of date. Accuracy is part of security for anyone who acts on what they wrote.

## The word is a question, not a checkbox

A secure note-taking app is not a product category with one winner. It is a match between what an app protects and what you are trying to protect. Zero-knowledge apps win the "no one but me, ever" bracket cleanly and pay for it in capability. At-rest apps trade a slice of that guarantee for the ability to do something useful with your notes. Neither is wrong. They answer different questions.

Decide which question is yours before you install anything. And whichever side of the trade you land on, remember the part encryption was never going to handle: a locked note that's wrong is still wrong.

If you want strong encryption and an app that keeps your notes accurate instead of just sealed, [see how Scribelet's plans compare](https://scribelet.app/pricing). Encryption at rest is free.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>security</category>
            <category>encryption</category>
            <category>byok</category>
            <category>privacy</category>
            <category>note-taking</category>
        </item>
        <item>
            <title><![CDATA[Personal Knowledge Management Is Missing a Step]]></title>
            <link>https://scribelet.app/blog/personal-knowledge-management</link>
            <guid isPermaLink="false">https://scribelet.app/blog/personal-knowledge-management</guid>
            <pubDate>Sat, 18 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Every personal knowledge management system ends at retrieval. None of them keep your notes true. Here's the step they all skip. Try it free.]]></description>
            <content:encoded><![CDATA[
You did everything the guides told you. You set up a personal knowledge management system. You picked a method, you captured diligently, you linked your notes and tagged them and gave them a home. For a while it felt like building a second mind. Most people build it only for work, though [the rest of your life needs the same system](/blog/second-brain-for-personal-life) just as badly.

Then you went to use it. You opened the note you were sure you had, the one about the deployment process or the tax rule or the API you integrated last year, and you read it, and you hesitated. Was this still true? You couldn't tell. The note looked exactly as confident as the day you wrote it. That confidence was the problem.

This is the failure mode nobody in the personal knowledge management conversation talks about. Every system teaches you to capture, organize, and retrieve. Not one of them keeps what you captured accurate. So this post is about the missing step, where each of the popular systems stops, and what a knowledge system would have to do to actually earn your trust.

## What is personal knowledge management?

Personal knowledge management (PKM) is the practice of capturing, organizing, and retrieving the information you encounter so you can use it later. It covers your notes, references, ideas, and the connections between them. The goal is to turn scattered input into a body of knowledge you can actually think with.

The term goes back to work by Jason Frand and Carol Hixon at UCLA around the turn of the millennium, and the [Wikipedia entry on personal knowledge management](https://en.wikipedia.org/wiki/Personal_knowledge_management) still frames it the way most guides do: a process to gather, classify, store, search, retrieve, and share knowledge. Read a dozen modern PKM articles and you'll see the same pipeline under different names.

- **Capture**: get the idea, quote, or fact out of your head or off the web and into your system.
- **Organize**: file it, link it, tag it, so it can be found again.
- **Distill**: pull out what matters, summarize, connect it to what you already know.
- **Retrieve**: find it when you need it, ideally by meaning and not just keyword.

That pipeline is genuinely good. It is also where every system stops. Notice what it quietly assumes: that a note, once captured and filed, stays true. It doesn't, and that assumption is the crack the whole practice falls through.

![Diagram of the personal knowledge management pipeline showing capture, organize, distill, and retrieve, with a fourth maintain step missing](/blog/personal-knowledge-management/pkm-four-steps.svg)

Most of what breaks in a PKM system is not a filing problem. It is a decay problem, which is why we spend so much time here on [knowledge decay](https://scribelet.app/blog/knowledge-decay): the slow, silent drift of your notes away from reality while they sit there looking finished. [Scribelet](https://scribelet.app) exists because that step was missing everywhere we looked, including our own notes.

## The four PKM systems everyone actually uses

Before we get to the missing step, it helps to see how the popular systems handle the four they do cover. There are really only a handful of frameworks under all the blog posts, and each is good at something specific.

**Zettelkasten** is the slip-box method, built from [atomic notes](https://scribelet.app/blog/atomic-notes) that link to each other so ideas connect sideways instead of stacking by folder. Sönke Ahrens made it famous in *How to Take Smart Notes*, the book that split notes into fleeting, [literature, and permanent notes](https://scribelet.app/blog/literature-notes). Follow [the smart notes method](https://scribelet.app/blog/how-to-take-smart-notes) to the letter and you still hit the same wall, because the method ends the moment a note is filed. It is unmatched for developing thinking over years. Its weak point is upkeep: the linking is manual, and most people abandon the slip-box when the maintenance outpaces the payoff. That is exactly the gap [a zettelkasten that links itself](https://scribelet.app/blog/zettelkasten-with-ai) is meant to close.

**PARA and Building a Second Brain** organize by actionability instead of topic. Tiago Forte's [Building a Second Brain overview](https://fortelabs.com/blog/basboverview/) sorts everything into Projects, Areas, Resources, and Archives, which is a superb filing system. The catch is that filing is not maintaining, which is why [PARA has no maintenance step](https://scribelet.app/blog/para-method-with-ai): a note filed under Resources in 2024 is just as findable and just as wrong in 2026.

**Digital gardens** treat notes as plants that grow and get revised in public, moving from seedling to evergreen. The ethos is the most honest about upkeep of any system, since gardening is mostly weeding. The tooling almost never delivers it, which is the whole argument in [tending a digital garden](https://scribelet.app/blog/digital-garden): everyone plants, nobody weeds. The closely related [evergreen notes method](https://scribelet.app/blog/evergreen-notes) shares the blind spot exactly: notes meant to evolve almost never get revisited.

[**The commonplace book**](https://scribelet.app/blog/commonplace-book) is the oldest of the four, a curated collection of quotes and passages worth keeping, running from Marcus Aurelius to [Ryan Holiday's notecard system](https://ryanholiday.net/how-and-why-to-keep-a-commonplace-book/). It is wonderful for collecting wisdom that ages slowly. It was never designed for facts that change, which is most of what a working professional actually needs to keep current.

| System | Organizes by | Great for | Where it stops |
|---|---|---|---|
| **Zettelkasten** | Idea links | Developing thinking over time | Manual upkeep, then abandonment |
| **PARA / Second Brain** | Actionability | Fast capture and retrieval | Filing is not maintaining |
| **Digital garden** | Growth stage | Public, evolving notes | Weeding rarely happens |
| **Commonplace book** | Curation | Slow-aging wisdom | Not built for changing facts |

Every one of these is a real answer to capture, organize, and retrieve. Every one of them ends there. The reason isn't that their creators were careless. It's that maintenance was never something a notebook could do for you, so nobody built the practice around it. That was a reasonable limit for paper. It stopped being reasonable the moment software could search the web on your behalf.

## Where every PKM system quietly breaks

Here is the uncomfortable fact under all of this. Knowledge has a half-life. The complexity scientist Samuel Arbesman spent a whole book, [The Half-Life of Facts](https://arbesman.net/), showing that established knowledge decays at a measurable rate across fields, from medicine to engineering. What was true when you wrote it down has an expiration date, and you almost never see it expire.

Your notes inherit that half-life and then hide it. A blog post that goes stale at least looks old; the date is right there at the top. A note that goes stale looks exactly like a note that is still correct. It sits in your carefully organized system, findable and confident, and the first time you learn it is wrong is when you act on it in front of a client or ship it into production.

This is why the standard PKM pipeline fails in a specific, predictable way. Every step assumes the previous one produced something durable. Capture assumes the fact was true. Organize assumes it stays true long enough to be worth filing. Retrieve hands it back to you months later with no memory of how much the world moved in between. The system is optimized to preserve what you wrote, not to keep it correct, and those are very different jobs.

None of the frameworks are wrong about the first three steps. They are just incomplete. The honest version of the model has a fourth step, and it is the one that turns a pile of notes into knowledge you can rely on. This is the same argument we make about [the missing phase in note-taking](https://scribelet.app/blog/living-notes-method), applied to the whole category instead of a single method.

## What a self-maintaining PKM system looks like

Add the missing step and the pipeline reads: capture, organize, maintain, trust. The fourth step is maintenance, and trust is what it buys you. A note you know is being checked is a note you can actually use without re-verifying it by hand every time.

For most of PKM's history this step was impossible to automate, so the practice pretended it wasn't needed. It is needed now, and it is possible now, because the same tools that read and search the web can do it while you sleep. The principle is simple: a knowledge system should check its own accuracy instead of waiting for you to catch the error the hard way.

![Diagram contrasting the standard capture-organize-retrieve loop with a capture-organize-maintain-trust loop where AI verification checks notes against current sources](/blog/personal-knowledge-management/pkm-maintenance-loop.svg)

Concretely, maintenance means a few things running quietly in the background:

- **Verification against current sources.** The system periodically searches the web for the claims in a note and compares what it finds to what you wrote. When they disagree, it shows you a diff, green for new information and red for what's outdated, with a link to the source. You see [how background verification works](https://scribelet.app/learn/ai/ai-verification) and decide what to accept. Nothing changes your note without your say-so.
- **Connection, not just storage.** Instead of you hand-linking every atomic note, the system surfaces related notes by meaning, so the slip-box grows its links on its own.
- **Memory of your context.** The system learns the people, projects, and terminology you actually work with, so its checks and suggestions are about your world, not a generic one.

That is the difference between a filing cabinet and a maintenance layer. A filing cabinet holds what you put in it, exactly as you left it, decay included. A maintenance layer holds it and keeps an eye on it. If you have read this far you can already feel which of your own notes you would not trust today. That list is the argument.

## How to build a PKM system that maintains itself

You do not need to throw out your method. Zettelkasten, PARA, a garden, a commonplace book: keep whatever fits your brain. Maintenance is a step you add, not a system you switch to. Here is the shortest path.

1. **Keep your existing capture and organize habits.** Whatever gets notes into your system reliably is already working, whether that's a nightly brain-dump, a running [AI work log](https://scribelet.app/blog/ai-work-log), or [logging a line between tasks through the workday](https://scribelet.app/blog/interstitial-journaling). Don't reform it.
2. **Mark the notes that make checkable claims.** Anything with an external fact under it (an API reference, a pricing comparison, a process, a summary of a paper) is a candidate for maintenance. Pure reflection and half-formed ideas are not, and that's fine.
3. **Put those notes on a verification schedule.** Let the system re-check them against the web on a cadence you set, rather than auditing everything by hand.
4. **Review diffs, don't rewrite from scratch.** When something changed, you want to see exactly what changed and why, then accept or dismiss. This is far cheaper than re-reading your whole archive looking for rot.
5. **Do a light weekly pass on the rest.** Ten minutes on the notes that surfaced this week keeps the backlog from ever forming. The mechanics of that habit are in our [30-minute weekly review system](https://scribelet.app/blog/keep-notes-up-to-date).

If you want the fuller walkthrough of standing this up from nothing, including capture and organization, our guide to [building an AI second brain](https://scribelet.app/blog/ai-second-brain-setup) covers the whole flow with maintenance built in from the start.

A note on trust and control, because it matters for a system that reads your notes. Maintenance means sending note content to an AI provider to run the checks. You should get to choose which provider, and you do. Scribelet's AI works out of the box, and if you want provider control you can bring your own OpenAI, Anthropic, or Gemini key; it's encrypted at rest and your notes go to the provider you picked. Your keys, your models, your call.

## Which PKM system should you use?

If you are choosing a personal knowledge management app or method from scratch, match it to how you think. Pick Zettelkasten if you write to develop ideas over years. Pick PARA or a second brain if you capture fast and want everything findable by project. Pick a digital garden if you like revising notes in public. Pick a commonplace book if you mostly collect wisdom that ages slowly.

Then, whichever you pick, add the fourth step. The method decides how your knowledge is shaped. Maintenance decides whether you can still trust it in a year. Those are separate choices, and almost everyone makes only the first one.

## The reframe

Personal knowledge management was never really about capture. Capturing is the easy part; your phone does it in a second. It was never mostly about organizing either, or the perfect folder structure would have solved this a decade ago. The hard part, the part that decides whether the whole practice pays off, is keeping what you captured true long enough to matter.

That is the step the frameworks skip, not out of negligence but out of history. A notebook could not check itself, so the practice grew up around the three things a notebook could do. Software can do the fourth thing now. A system that captures and organizes and retrieves but never verifies is a very tidy way to store things that are slowly becoming wrong.

You already know which notes those are. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and point maintenance at them first.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>pkm</category>
            <category>personal-knowledge-management</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>second-brain</category>
        </item>
        <item>
            <title><![CDATA[LLM wikis: everyone compiles, nobody recompiles]]></title>
            <link>https://scribelet.app/blog/llm-wiki</link>
            <guid isPermaLink="false">https://scribelet.app/blog/llm-wiki</guid>
            <pubDate>Fri, 17 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Karpathy's LLM wiki compiles your sources into markdown once. Then the sources change and nothing tells you. Here's the missing step. Try it free.]]></description>
            <content:encoded><![CDATA[
[Karpathy's gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) was updated two days ago. A beginner setup guide for the pattern has 466,000 views. Google shipped a vendor-neutral standard for it this month. Somewhere in the last quarter, "point an LLM at your sources and let it write the wiki" went from a clever idea in a text file to the most-copied knowledge management pattern of 2026.

The pattern deserves the attention. It solves something real, and it solves it better than what most people were doing before.

Here is the question nobody in that pile of tutorials is asking: what does your LLM wiki look like in November?

Not the day you build it, when the concept pages are crisp and the cross-references are dense and the whole thing feels like cheating. Four months later. After the library you documented shipped two majors. After one of those papers got retracted. After the "current best practice" you compiled became the thing people migrated away from. The wiki will still be there, still well-organized, still reading like confident prose. It just won't be true anymore, and nothing in the pattern will have told you.

## What is an LLM wiki?

An LLM wiki is a personal knowledge base where you curate the raw sources and an LLM writes and maintains the synthesis on top of them. Instead of retrieving from raw documents on every question, the model compiles them once into a directory of interlinked markdown files (entity pages, concept pages, cross-references) that you read and it writes.

Karpathy's version has three layers:

1. **Raw sources.** Your immutable, curated collection: papers, articles, PDFs, transcripts. You choose what goes in. Nothing here gets edited.
2. **The wiki.** A directory of markdown files owned by the LLM. Entity pages, concept pages, a log. You read it; the model writes it.
3. **The schema.** Configuration (a `CLAUDE.md`, an `AGENTS.md`) telling the model how to ingest a new source, how to format pages, how to cross-link.

![The three layers of an LLM wiki: raw sources you curate, a markdown wiki the LLM owns and writes, and a schema file that tells it how](/blog/llm-wiki/three-layers.svg)

The insight underneath is a compiler metaphor, and it is a good one. You don't re-run your source code every time you want the program. You compile once and run the binary.

Retrieval-augmented generation makes the model re-read the sources on every question, reconstructing the same understanding from scratch each time. The LLM wiki compiles that understanding once and reads the artifact after that.

Anyone who has watched a RAG system confidently stitch together two chunks that had nothing to do with each other understands the appeal immediately.

If you want the fastest possible version of this: pick ten sources you actually care about, write a schema file describing the pages you want, and let a coding agent compile it. You will have something useful inside an hour. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) if you'd rather the compiling and the upkeep live in the same place.

## Is an LLM wiki better than RAG?

For a stable, curated body of knowledge, usually yes. For anything that changes underneath you, the answer flips, and that flip is the whole point of this article.

| | RAG | LLM wiki |
|---|---|---|
| **When it reads sources** | Every query | Once, at compile time |
| **Coherence across sources** | Poor. Stitches chunks with no global view | Strong. The model saw everything and reconciled it |
| **Cost per question** | Pays retrieval and comprehension every time | Pays once, reads cheap markdown after |
| **You can inspect it** | No. Retrieval happens in the dark | Yes. It's a folder of files you can read |
| **Freshness of sources** | Re-reads whatever is in the index now | Frozen at the moment you compiled |
| **Knows when a source changed** | No | No |

Notice the last two rows. RAG at least re-reads the index, so if you update a document, the next answer reflects it. The LLM wiki reads the compiled artifact, which means a source can change and the wiki will keep confidently telling you the old thing. The compiler metaphor is doing something the people who adopted it didn't intend: real compilers get re-run when the source changes, because a build system watches the files and knows the binary is stale.

The LLM wiki has no build system. There is no `make` for your knowledge base. Nobody is watching the sources.

## The compile step is a snapshot

This is the part the pattern gets wrong, and it is worth being precise about it rather than gesturing at it.

Compilation is a point-in-time operation. You compiled on April 12th. The wiki is an accurate synthesis of the world as your sources described it on April 12th. Every day after that, it is a slightly more confident and slightly more wrong account of a world that kept moving.

The failure mode is nastier than a plain stale note, for three reasons.

**The synthesis hides the source.** When you read your own note, you remember writing it, and you carry a rough sense of when and how sure you were. A compiled concept page has no such halo. It reads like reference material. It reads like a wiki, which is exactly what it was designed to read like, and reference material carries an implicit claim of currency that a scribbled note never made.

**The provenance thins out with every hop.** A concept page synthesizes six sources. An entity page cross-references four concept pages. By the time a claim reaches the page you actually read, it has been paraphrased, merged, and reconciled twice. Which underlying PDF is responsible for this sentence, and is that PDF still saying it? The pattern's own structure makes that progressively harder to answer.

**Confidence is uniform.** The model writes the shaky inference and the load-bearing fact in the same steady register. Nothing in the output distinguishes "three sources agreed on this" from "one preprint claimed this and nothing contradicted it."

None of this is unique to wikis. Any store an AI writes to has the same asymmetry: [memory is write-heavy and has no retraction step](https://scribelet.app/blog/ai-memory), so quality drops even when every individual write was correct on the day.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay) with better typography. Everything in your notes has an information half-life, and compiling it into cleaner prose doesn't extend that half-life by a single day. It just makes the decay harder to see.

## Three ways a compiled wiki rots

Abstractions are easy to nod along to, so here are the concrete ones.

**The source updated.** You compiled a page on a framework's auth flow from its docs in April. In June the framework deprecated the middleware order you documented. The docs changed. Your wiki did not. You will find out when you follow your own instructions and they fail, which is the single most expensive way to discover a stale note, because you trusted it enough to act on it. It is the same mechanism that rots every runbook an engineering team ever wrote, arriving now in a folder that looks far more authoritative than a runbook ever did.

**The source got retracted.** If your raw sources include papers, this is not hypothetical. [Retraction Watch](https://retractionwatch.com/) maintains a database of tens of thousands of retracted papers, and retractions frequently land years after publication and long after the finding has been cited downstream. Your wiki compiled the claim. The claim was withdrawn. The concept page still states it as fact, still cross-linked into four other pages, quietly load-bearing.

**The source was superseded.** Nothing was wrong and nothing was retracted. The field simply moved. The technique you compiled as current practice is now the thing people are migrating off. No error was made at any point, and the page is still wrong in the way that matters: it will lead you to do the wrong thing.

None of these three announce themselves. That's the shared property. A broken link is loud, a 404 tells you immediately. A silently superseded best practice is quiet for months and then expensive all at once.

![Compile-once versus a maintenance loop: the compiled wiki drifts from its sources over time, while a maintained wiki re-checks sources on a schedule and diffs them against what's written](/blog/llm-wiki/compile-vs-maintain.svg)

## What a maintenance step would actually require

Naming a gap is cheap. Here is the mechanism, because "the AI handles it" is exactly the kind of claim this pattern doesn't need more of.

A maintenance loop for an LLM wiki needs five things:

1. **Source addresses, not source copies.** The wiki has to know where each claim came from, as something re-fetchable. A URL, a DOI, a repo path. Not just "synthesized from the sources folder."
2. **A schedule.** Re-check runs on a cadence you set, not when you remember. The entire failure mode is that you don't remember, so any design that depends on you remembering has already lost.
3. **A diff.** Fetch the source again, compare it to what the wiki says, and show the delta. Not a rewrite. A diff, with the old text and the new text side by side.
4. **A citation.** Every flag points to the specific source that changed, so you can check the machine's work instead of trusting it. If the tool can't show you why it thinks a page is stale, it's asking for the same blind trust the compiled wiki already asked for.
5. **A human gate.** You accept or reject. An LLM that silently rewrites your knowledge base on a cron job has replaced a wiki that goes quietly stale with a wiki that quietly changes its mind, which is worse.

Look at that list and notice it's the same shape as the compile step, pointed backward. The compiler reads sources and writes pages. The maintainer re-reads sources and flags pages. Same three layers, same schema file, run on a loop instead of once. The pattern is one step away from being complete, and the step is not exotic.

This is what [AI verification](https://scribelet.app/learn/ai/ai-verification) does in Scribelet: background agents re-check what your notes claim against current sources on a schedule you set, then show you a diff with citations. Green for what's new, red for what no longer holds. You accept or dismiss. The same loop that [fact-checks notes before you reuse them](https://scribelet.app/blog/ai-fact-checking-for-notes) is the loop a compiled wiki is missing.

## This is a pattern of missing phases

If this argument feels familiar, that's because it keeps happening, and the repetition is the interesting part.

Zettelkasten has capture, atomize, and link, with no step for revisiting whether a permanent note is still true. PARA sorts by actionability, and filing is not maintaining. Digital gardens went furthest by borrowing a metaphor that is mostly weeding, then built tooling that only publishes, which is why [everyone plants and nobody weeds](https://scribelet.app/blog/digital-garden). [Every note-taking method is missing the same phase](https://scribelet.app/blog/living-notes-method).

The LLM wiki is the newest member of this family, and it arrives with a twist. Previous methods asked *you* to maintain and you didn't have time. The LLM wiki automates the part you were already doing (writing and organizing) and leaves un-automated the part you were already failing at (checking whether it's still true). It automated the wrong half. The half it automated was tedious; the half it skipped was the one that actually decides whether the artifact is worth anything in month six.

Karpathy's gist is explicit that it's an idea file, not a product. That's fair and it's honest. But the tutorials, the desktop implementations, and the standards proposals built on top of it have all inherited the same omission without inheriting the disclaimer.

## Two shapes of a self-maintaining knowledge base

There's a second axis here worth separating out, and we've written about it before: there are [two directions for a self-maintaining knowledge base](https://scribelet.app/blog/karpathy-llm-wiki-reaction).

Karpathy's direction is compiled external knowledge. You curate what to read; the LLM authors the synthesis. Scaled up, it converges toward a personalized copy of the internet.

The inverse direction is your own writing, maintained. You write the notes (the half-formed thoughts, the meeting fragments, what you actually decided on Tuesday), and the LLM never authors a first draft. It cross-references, flags contradictions, catches drift. Scaled up, it converges toward a persistent copy of your own thinking.

Both need the maintenance loop. Neither ships with one by default. And if you're building the first kind inside a vault, the [AI options for Obsidian](https://scribelet.app/blog/obsidian-ai) are worth understanding before you assume a plugin closes this gap, because most of them are compile-side too: they generate, summarize, and link. Generating more pages faster does not help a folder whose problem is that its pages quietly stopped being true.

## When you don't need any of this

Honest limits, because the pattern is genuinely good and this isn't a hit piece.

If your sources don't change, none of this applies. A wiki compiled from Marcus Aurelius is not going to drift. History, literature, closed corpora, a fixed set of interview transcripts, a finished project's documentation: compile it, enjoy it, ignore everything above. Stable sources are exactly the right use case for the pattern as written, and it's a strong one.

The maintenance problem shows up precisely where the pattern is most attractive: fast-moving technical fields, active research areas, anything where you picked the LLM wiki *because* there was too much to keep up with. The size of the reading pile is what makes the pattern appealing, and the churn rate underneath that pile is what makes the compiled artifact rot. Those are the same property. The wikis that most need compiling are the ones that most need recompiling.

## The step after the compile step

Build the LLM wiki. The pattern is good, the tooling is getting real ([open-source implementations](https://github.com/nashsu/llm_wiki) are shipping updates weekly), and a compiled synthesis genuinely beats re-reading a folder of PDFs forever.

Then put a date on it. Ask yourself, honestly, what happens to it in November, when the concept pages still read beautifully and a third of them are describing a world that moved on. Compiling is a build step. Nobody ships a build system that never re-runs.

Your wiki is going to keep telling you what was true in April. You already know which of those pages you'd be nervous to act on today. [Point AI verification at those first](https://scribelet.app/learn/getting-started/quick-start).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>llm</category>
            <category>pkm</category>
            <category>knowledge-management</category>
            <category>knowledge-decay</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Digital gardens: everyone plants, nobody weeds]]></title>
            <link>https://scribelet.app/blog/digital-garden</link>
            <guid isPermaLink="false">https://scribelet.app/blog/digital-garden</guid>
            <pubDate>Thu, 16 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A digital garden promises notes that grow and stay evergreen. Most get planted once, then abandoned. Here's what tending actually takes. Try it free.]]></description>
            <content:encoded><![CDATA[
Somewhere in your notes there's a page with a seedling emoji at the top. You planted it in 2023. It was going to grow into something. It is still a seedling.

That page is the honest state of most digital gardens. The idea is lovely and the writing about it is some of the best on the indie web: notes that grow in public, connected sideways instead of stacked by date, revised as your understanding deepens. What almost nobody writes about is the eighteenth month, when the garden has forty seedlings, no evergreen notes, six dead links, and a note near the front confidently describing an API that shipped a breaking change last spring.

The metaphor is not the problem. The metaphor is the most honest thing in the room. Real gardens are perhaps a tenth planting and the rest weeding, and the people who borrowed the word took the aesthetic and quietly dropped the labor. This post is about that missing labor: where gardens actually die, why no publishing tool saves them, and what tending would have to look like to survive contact with a real week.

## What is a digital garden?

A digital garden is a public collection of notes that grow and get revised over time, linked to each other by idea rather than ordered by date. It sits between a private notebook and a blog. A blog post is finished when you hit publish. A garden note is never finished; it is just at some stage of growth.

Most gardens borrow a maturity convention from [Maggie Appleton's history and ethos of the digital garden](https://maggieappleton.com/garden-history): a note starts as a seedling (a rough thought, barely defensible), becomes budding (developed, still soft), and eventually goes evergreen (something you'd stand behind), a stage that is [its own note-taking method](https://scribelet.app/blog/evergreen-notes) with the same maintenance blind spot. The stage is usually stamped right on the page.

The rest of the ethos follows from that. Gardens are non-linear, so a reader wanders instead of scrolling. They are anti-perfectionist by design, because publishing a seedling is allowed and lowers the cost of writing anything at all.

Joel Hooks put the distinction plainly in [his essay on why his blog is a digital garden](https://joelhooks.com/digital-garden/): the focus is the process and the care, not the finished showpiece. The practice got its mainstream introduction around 2020, when [MIT Technology Review covered digital gardens](https://www.technologyreview.com/2020/09/03/1007716/digital-gardens-let-you-cultivate-your-own-little-bit-of-the-internet/) as a reaction against the performance of social feeds.

Here's the difference that matters, and it's the one that creates the whole problem:

| | Blog | Digital garden |
|---|---|---|
| **Order** | Reverse chronological | Linked by idea |
| **Lifecycle** | Published once, then frozen | Revised indefinitely |
| **Unit** | The post | The note |
| **Done means** | Shipped | Nothing. There is no done |
| **Implied upkeep** | None. Old posts are archive | Continuous, forever |
| **What decay looks like** | An old post, obviously dated | A current-looking note that's wrong |

Read that last row again. A blog's decay is visible and forgiven, because a post from 2021 is understood to be from 2021. A garden's decay is invisible and unforgiven, because the whole promise is that the note is tended, and the note looks tended whether or not anyone tended it.

If that gap sounds familiar, we've made the same argument about note-taking systems generally in [the missing phase in note-taking](https://scribelet.app/blog/living-notes-method). Gardens are the version of that gap with the best vocabulary and the worst outcome, because they promised maintenance out loud.

## The metaphor already contains the answer

Ask anyone who actually gardens what the work is. It is not planting. Planting is the fun afternoon. The work is the weekly, unglamorous, slightly boring return: pulling what doesn't belong, cutting back what has overgrown, noticing the thing that's dying before it's dead, and deciding what earns its space this year.

Digital gardening kept the seedlings and the growth stages and the soft green language. It dropped the weeding, the pruning, and the compost pile. There's no shame in that; nobody set out to be dishonest. It's that the tools made planting take twenty seconds and left weeding as an unpriced manual chore that competes with your actual job.

So the metaphor is doing something unusual. It is not overselling. It is describing a discipline the software underneath it never supported.

## Where gardens actually die

Four failure modes, and they compound. They don't announce themselves, which is the point.

### Seedlings never get promoted

Growth stages are a status field that a human has to update by hand. Nothing in your setup knows that a note got better.

So the label freezes at whatever you typed the day you created the file. After a year, the stage tells you when you wrote it, not what it's worth. The taxonomy becomes archaeology.

### Links rot underneath you

A garden's value is its edges, and a meaningful share of them point outward. Pew Research Center found that [38% of webpages that existed in 2013 were no longer accessible a decade later](https://www.pewresearch.org/data-labs/2024/05/17/when-online-content-disappears/).

Your garden inherits that rate. The prose around the dead link stays confident and well-formed, which is exactly what makes it dangerous.

### Facts drift while the sentences hold still

This is the quiet one. The note doesn't break; the world moves. The library got a new major version, the pricing page changed, the recommendation reversed, the paper was retracted.

Your sentence is still grammatical and still wrong. We've written the long version of this as [knowledge decay](https://scribelet.app/blog/knowledge-decay), and gardens are its ideal habitat: lots of external claims, long shelf life, an explicit promise of freshness.

### The graph stops growing before the note count does

Early on you link everything, because there are nine notes and you remember all of them. At two hundred notes you no longer remember what's in there, so new notes arrive unconnected.

The graph view still looks impressive in a screenshot while the recent additions sit in a lonely ring around the edge. That's the same wall people hit with a slip-box, which is why we argued for [a zettelkasten that links itself](https://scribelet.app/blog/zettelkasten-with-ai) rather than one that depends on you recalling everything you've ever written.

![A digital garden's intended seedling to evergreen growth beside the real month 18 outcome: 41 seedlings, zero evergreen notes](/blog/digital-garden/growth-stages-promise-vs-reality.svg)

None of these need neglect to happen. They happen to gardens that are actively being added to. Adding is not tending. That's just as true of [a commonplace book that only ever grows](https://scribelet.app/blog/commonplace-book), the oldest collect-and-forget method, as it is of a garden.

## The tools publish gardens. They don't tend them.

Look at what the ecosystem actually gives you. Quartz and Obsidian Publish turn a folder of markdown into a browsable site. Capacities and Notion give you objects, backlinks, and databases. Eleventy and Jekyll will happily build whatever you hand them.

Every one of these is good at what it does, and what they all do is **publishing**. They take the notes you have and put them on the internet, quickly and attractively. Not one of them has an opinion about whether the note you published fourteen months ago is still true. There is no tool in that list whose job is to come back later.

That's not a flaw in the tools. It's a category that doesn't exist yet in most people's stack. Static site generators were never going to check your facts.

The plugin ecosystem gets closest and still stops short. If you keep your digital garden in Obsidian, you can bolt on AI through Copilot, Smart Connections, Text Generator, or a Model Context Protocol connection to Claude Code.

We catalogued [every way to add AI to Obsidian](https://scribelet.app/blog/obsidian-ai) and the pattern held across all of them: they help you write the note and search the vault. They are reactive. You ask, they answer. None of them wake up on their own and tell you that the thing you wrote in March stopped being true in June.

Reactive AI cannot fix a problem whose defining feature is that you don't know to ask.

## What tending actually takes

Strip the gardening language away and the maintenance job has four parts. This is what you'd be doing on that Sunday you keep not spending.

1. **Promote.** Decide which seedlings earned a stage change, and which have been seedlings so long they should be compost.
2. **Connect.** Find the notes that should link to each other and don't, especially the older ones you've forgotten.
3. **Verify.** Check the external claims. Which facts moved? Which links are 404s? Which recommendation reversed?
4. **Prune.** Remove or merge the notes that are redundant, abandoned, or wrong beyond repair.

Two of these are judgment and two are labor. Promoting and pruning are yours; they're about taste and what you think is worth standing behind, and no software should take them from you. Connecting and verifying are search problems. They're mechanical, they're tedious, and they're precisely the two that don't get done, because they scale with the size of the garden while your Sunday does not.

You can do this by hand. We've published [a 30-minute weekly review system](https://scribelet.app/blog/keep-notes-up-to-date) for exactly that, and it works, as long as you run it. The honest read on manual weeding is the same as the honest read on flossing: the people who need the routine most are the people who won't keep it.

![The four tending jobs: promote and prune stay human judgment, while connect and verify run automatically in the background](/blog/digital-garden/tending-jobs.svg)

## A garden that tends itself

This is where Scribelet fits, and it's a narrow claim, so let me make it precisely: we automate the two mechanical jobs and leave the two judgment jobs to you.

Background agents check your notes against the web on a schedule you set. When a claim in a note no longer matches what the sources say, you get a diff: green for what's current, red for what's outdated, with a source link for each change.

You accept it or dismiss it. Nothing is rewritten behind your back, because a garden where the plants move on their own isn't a garden you own. That's [AI verification](https://scribelet.app/learn/ai/ai-verification), and it's the weeding, running whether or not you showed up on Sunday.

The auto-linker handles the other half. It reads your notes semantically and surfaces connections you didn't make, including to notes you wrote two hundred entries ago and no longer remember. That's the edge growth that normally stalls at the exact moment the garden gets big enough to be interesting.

Because this involves sending your notes to an AI provider, you should get to choose which one. Bring your own key (BYOK) means you connect your own OpenAI, Anthropic, or Gemini account; we encrypt the key at rest and your notes go to the provider you picked, not the one we picked for you. The [BYOK setup](https://scribelet.app/learn/ai/byok) takes about a minute. It's optional, since AI features work out of the box on the free plan, but for a public garden built on the premise that it's your plot, choosing the provider is part of the point.

Here's the honest limit. Verification works on notes that make external, checkable claims: the API reference, the pricing comparison, the summary of a paper, the recommendation with a link under it.

A garden of personal reflection and half-formed essays has less for it to check, and it will tell you less. If your garden is mostly you thinking out loud, the auto-linker will earn its keep and verification mostly won't. That's a real tradeoff and it's better said out loud than discovered in month three.

## The reframe

The digital garden was never a publishing format. It was a promise about upkeep, made in a vocabulary borrowed from the one hobby where everyone already knows that upkeep is the entire activity. Then it got implemented as a publishing format, because publishing is the part software knew how to do.

A garden with no gardener isn't a garden. It's a lot. The plants are still there and the sign out front still says what it said, and that's precisely why it takes a while for anyone to notice, including you.

You already know which of your notes you'd flinch at if someone read it aloud today. That's the weeding list, and it's been sitting there getting longer. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and point it at those notes first.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>digital-garden</category>
            <category>pkm</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>evergreen-notes</category>
        </item>
        <item>
            <title><![CDATA[11 Evernote alternatives, ranked by what you're actually moving]]></title>
            <link>https://scribelet.app/blog/evernote-alternative</link>
            <guid isPermaLink="false">https://scribelet.app/blog/evernote-alternative</guid>
            <pubDate>Wed, 15 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A scannable roundup of 11 Evernote alternatives with a pick-it or skip-it verdict for each, a real .enex migration table, and the one question every other list skips.]]></description>
            <content:encoded><![CDATA[
The export finishes and you're staring at a single `.enex` file. Fourteen years of clipped articles, meeting notes, recipes, and API scratch pads. Four thousand notes, give or take. You haven't opened most of them since the year you wrote them.

Now comes the part every Evernote alternative guide gets wrong. They hand you a feature matrix and a price column, as if the only decision left is which app receives the file. That question is the easy one. The hard one is sitting inside the export: how much of this is still true?

This roundup does both halves. First the honest comparison you came for: eleven apps, an at-a-glance table, and a pick-it or skip-it verdict for each. Then a real migration table for the `.enex` file, and the question the feature matrices never ask.

## The 11 Evernote alternatives at a glance

| App | Best for | Evernote import | Free tier | What it costs you |
|---|---|---|---|---|
| **UpNote** | The closest 1:1 feel | `.enex` | Limited notes | Low feature ceiling |
| **Notesnook** | Privacy, encryption | `.enex` importer | Generous | Smaller ecosystem |
| **Zoho Notebook** | Visual notebooks, easy switch | Built-in migrator | Full | Web-first, needs an account |
| **Notion** | Databases, wikis, teams | Native importer | Full personal | Complexity; it's a workspace |
| **Obsidian** | Local files, linking, control | Importer plugin | Full (personal) | Setup time; paid sync |
| **Joplin** | Open source, self-hosted | `.enex` (built-in) | Full | Rough edges; you run the sync |
| **Microsoft OneNote** | Free, stylus, Office shops | Microsoft importer | No note cap | Free-form chaos; weak linking |
| **Amplenote** | Notes tied to tasks | `.enex` | Limited | Task model you may not want |
| **Bear** | Markdown on Apple | `.enex` | Basic only | Apple-only; sync is paid |
| **Apple Notes** | Apple-only, zero setup | Manual | Full | No Android, thin linking |
| **Scribelet** | Notes that get checked | Markdown import | 10 checks/mo | Newer; not a clipper |

Below is the pick-it or skip-it read on each, then the part no other list on this page covers: what actually survives the migration, and what happens to the notes after they land.

## The 11 apps, with a verdict each

### UpNote

**Pick it if** you want Evernote before it got expensive. UpNote mirrors the notebook-and-tag model closely, imports `.enex` directly, and is pleasant to use. A cheap lifetime licence is on offer.

**Skip it if** you wanted the switch to be an upgrade. UpNote won't do anything your notes didn't already do. It is a faithful copy of the thing you're leaving, minus the price.

### Notesnook

**Pick it if** privacy is the reason you're moving. Notesnook is end-to-end encrypted by default, open source, and its Evernote importer handles notebooks and attachments well. It is the answer the AI overview keeps naming for a reason.

**Skip it if** you lean on a huge third-party plugin ecosystem or deep integrations. The app is focused and clean, which is the point, but the surrounding tooling is thinner than Notion's or Obsidian's.

### Zoho Notebook

**Pick it if** you want the least painful switch on this list. Zoho Notebook ships a built-in Evernote migration tool, uses a familiar notebook-and-card model, and syncs across platforms for free.

**Skip it if** you want to work offline or stay out of another vendor's suite. It is web-first and pulls you toward a Zoho account you may not otherwise want.

### Notion

**Pick it if** your notes are really a wiki or a set of databases in disguise. Notion is superb at structure, has a native Evernote importer, and bundles Notion AI.

**Skip it if** you mostly clipped and searched. Notion is genuinely bad at being a shoebox. If capture-and-find is your whole workflow, it feels like being handed a CAD program to draw a shopping list. Our [Notion vs Obsidian breakdown](https://scribelet.app/blog/notion-vs-obsidian) walks that tradeoff properly, and if databases are the draw, the wider [Notion alternatives](https://scribelet.app/blog/notion-alternative) are worth a look first.

### Obsidian

**Pick it if** you want your notes as plain markdown on your own disk, with no lock-in and a plugin for everything. It is the enthusiast's pick and it earns the reputation.

**Skip it if** you don't want to be the system administrator of your own note-taking. Paid sync and a slower mobile app catch people out. If that is where you're heading, we sorted the [Obsidian alternatives by reason for leaving](https://scribelet.app/blog/obsidian-alternative) too.

### Joplin

**Pick it if** open source and self-hosted are hard requirements. Joplin really is free, really does end-to-end encryption, imports `.enex` cleanly, and syncs through storage you control.

**Skip it if** polish matters to you day to day. It looks and feels like the community project it is, and web-clip formatting can come across rough.

### Microsoft OneNote

**Pick it if** "free" is the whole brief. OneNote has no note cap, imports Evernote directly, and costs nothing extra if you already pay for Microsoft 365.

**Skip it if** you have thousands of notes to retrieve. OneNote's free-form canvas lets you put anything anywhere, which is liberating for a stylus and miserable for search at 4,000 notes. Plenty of people searching for [a OneNote alternative](https://scribelet.app/blog/onenote-alternative) are refugees from exactly that, so landing there from Evernote can be a lateral move.

### Amplenote

**Pick it if** your notes and your to-do list want to be the same thing. Amplenote connects daily notes to a task system and imports `.enex`.

**Skip it if** you just want a notebook. The task-centric model is opinionated, and if you don't work that way it adds friction rather than removing it.

### Bear

**Pick it if** you live on Apple hardware and want a beautiful markdown editor. Bear imports `.enex`, uses tags instead of notebooks, and is a genuine pleasure to write in.

**Skip it if** you need Android or Windows. Bear is Apple-only, and sync sits behind the paid tier. Cross-platform is not a footnote here, it is the deciding factor for a lot of people, which is why a [cross-platform note-taking app](https://scribelet.app/blog/cross-platform-note-taking-app) is worth checking before you commit.

### Apple Notes

**Pick it if** you're all-in on Apple and want zero setup and zero cost. It is fast, it is already installed, and it syncs through iCloud without a thought.

**Skip it if** you touch a non-Apple device or want real linking between notes. There is no Android app and the organisation model is thin. Importing `.enex` is a manual chore rather than a one-click job.

### Scribelet

**Pick it if** the reason you're moving is that you no longer trust what's in the archive. Scribelet imports your markdown and then does the thing none of the others do: it checks whether your notes are still true, on a schedule, against the live web.

**Skip it if** the web clipper is the reason you stayed on Evernote for fourteen years. Scribelet has no clipper that competes with Evernote's, and its OCR story is younger. That gap is real and you should weigh it. More on how the checking works below.

## What has happened to Evernote?

The exodus isn't nostalgia. It traces to a handful of specific decisions.

Evernote was acquired by the Milan-based app studio Bending Spoons, which then cut most of the original staff and moved operations to Europe. In December 2023 the free plan was capped at [50 notes and one notebook](https://techcrunch.com/2023/11/29/its-official-evernote-will-restrict-free-users-to-50-notes/). That limit turned a decade-old free account into a read-only museum overnight. Evernote's own [plan comparison](https://evernote.com/compare-plans) still lists the free tier at 50 notes, 1 notebook, 1 GB, and a single synced device.

Then the paid tiers were reshuffled. Personal and Professional were [retired in favour of Starter and Advanced](https://help.evernote.com/hc/en-us/articles/46317642175763-Discontinuing-Evernote-Personal-Professional-Introducing-Starter-Advanced-FAQ), with existing subscribers rolling into Advanced at renewal unless they actively downgraded. Advanced lands around $250 a year. For a tool many people used as a glorified shoebox, that's a real number.

So the searches make sense. "Evernote alternative free." "Evernote alternative open source." "Evernote alternative self hosted." Every one of them is someone doing the same arithmetic.

Fair credit where it's due. Evernote's web clipper is still one of the best ever shipped, its OCR reads text inside images, and its search is genuinely fast across huge archives. Those are the things you'll miss, and any honest list should say so.

## Is there an app like Evernote but free?

Yes, and the honest ranking is short. **OneNote** is the strongest genuinely free option: no note cap, direct Evernote import, and free with a Microsoft account. **Zoho Notebook** is free and has the smoothest migration tool. **Notesnook** is free, private, and open source. **Joplin** is free and self-hostable. **Apple Notes** and **Google Keep** are free if you live in their ecosystems, though Keep is really a sticky-note app rather than a notebook, which is why people outgrow it and start hunting for a [Google Keep alternative](https://scribelet.app/blog/google-keep-alternative) of their own.

The catch is the same one the feature tables hide: a free destination still receives the same slowly rotting archive. Free fixes the price. It does nothing for the contents.

## Moving the `.enex` file: what survives, what breaks

Here is the part no other guide on this page carries. Exporting from Evernote gives you a single `.enex` file (`File > Export Notes`). Where it lands changes what makes it across intact. Read this before you pick, not after.

| Destination | Import path | What comes across | What breaks or needs cleanup |
|---|---|---|---|
| **UpNote** | Built-in `.enex` import | Notes, notebooks, tags, attachments | Some rich formatting simplifies |
| **Notesnook** | `.enex` importer | Notes, notebooks, attachments | Complex tables, nested formatting |
| **Zoho Notebook** | Built-in Evernote migrator | Notes, notebooks, images | Inter-note links do not transfer |
| **Notion** | Native Evernote importer | Notes as pages, notebooks as sections | Deep nesting flattens; large imports are slow |
| **Obsidian** | Importer community plugin | Notes as markdown, attachments | Tags and notebooks need reorganising |
| **Joplin** | Built-in `.enex` import | Notes, notebooks, tags, attachments, dates | Web-clip HTML can look messy |
| **OneNote** | Microsoft Evernote importer | Notes into sections, images | Evernote tags are dropped |
| **Amplenote** | `.enex` import | Notes | Formatting and links vary |
| **Bear** | `.enex` import | Notes, some attachments | Notebooks become tags |
| **Apple Notes** | No `.enex`; manual or third-party tool | Text, images | Tags and structure; tedious at scale |
| **Simplenote** | Plain text only | Note text | Attachments and all formatting |

Two rules that hold across every row. Keep the original `.enex` forever, wherever you land: it is your rollback. And do not import all of it, which is the step people skip and regret. More on that below, because it is where the real decision lives.

![Bar chart of a 14-year Evernote export showing web clips and API notes go wrong fastest, your own thinking slowest](/blog/evernote-alternative/what-youre-moving.svg)

## The question every Evernote alternative list skips

Here's what fourteen years of notes actually contains.

Roughly a third of it is web clips whose source pages have changed, moved, or died. Another slice is technical notes pinned to versions that no longer exist. There are meeting notes about projects that shipped or got cancelled, phone numbers for people who changed jobs, and prices from a market that has moved twice since. The stuff that stays true is a minority: your own thinking, written in your own words.

Every guide in this SERP treats that archive as inert cargo. Import it, re-tag it, done. But the notes aren't inert. They're wrong, quietly, and they've been wrong for years. The reason you never noticed is that nothing ever told you.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and a migration is the one moment you're forced to look straight at it. You have the whole archive in one file. You're already deciding what deserves to come with you. It's the best audit opportunity you'll get for another decade, and every listicle tells you to skip it and compare pricing tables instead.

Consider what happens if you do skip it. A developer moves an engineering wiki out of Evernote into a cleaner, faster, markdown-based app. The notes look better immediately: nice typography, instant search, proper code blocks. Six months later someone follows the OAuth setup note and it fails, because the scope it documents was deprecated before the migration ever happened. The editor improved. The wrongness came along for the ride, reformatted.

Switching apps upgrades the container. It does nothing to the contents.

> Curious what it looks like when software checks whether a note is still true? [See how AI verification works](https://scribelet.app/learn/ai/ai-verification) before you pick a destination.

## How to migrate without carrying the rot with you

The mechanical part is easy. The judgment part is what makes the difference. Do it in this order:

1. **Export everything first.** `File > Export Notes` gives you the `.enex`. Keep that file forever, regardless of where you land. It's your rollback.
2. **Don't import all of it.** This is the step people skip and regret. A full import recreates the graveyard in a nicer building.
3. **Sort by last-opened, not by notebook.** Notebooks tell you how you organised in 2014. Last-opened tells you what you actually use. The long tail you haven't touched in five years is the part most likely to be both stale and unnecessary.
4. **Bring the notes you wrote, leave most of the clips.** Your own synthesis ages slowly. Somebody else's article aged the day it was published, and the original is still on the web anyway.
5. **Flag anything with a version number, a price, or a URL.** These are the notes that decay fastest. They're also the ones that hurt when they're wrong, because you'll act on them.
6. **Then import, and set something to watch the survivors.**

That last step has no equivalent in any other guide, because most tools have nothing to offer for it. On format, whatever you pick, [markdown-based note apps](https://scribelet.app/blog/markdown-note-taking-apps) give you the best odds that the next migration is easier than this one. Plain text is the closest thing to an escape hatch the category offers. It keeps your notes portable. It doesn't keep them accurate, which is the whole point of this article.

## What happens after the notes land

Scribelet's premise is that step six shouldn't be your job.

Background agents run on a schedule you set. They search the web, compare what they find against what your note claims, and show you a diff: green for what's new, red for what no longer holds, with a source link for each change. You accept or dismiss. The note updates or it doesn't. Nothing gets rewritten behind your back.

Point that at a freshly imported Evernote archive and the first pass is genuinely uncomfortable. The pricing note that's off by two increases. The setup guide whose middle three steps no longer exist in the current UI. The clipped article that has since been corrected by its own author. None of that surfaced in Evernote, and none of it would have surfaced in UpNote or Notion or Obsidian either, because checking isn't a thing any of them do.

The AI works out of the box, and the free plan includes ten verifications a month. That's enough to point at your worst imported notes and see whether the diffs tell you anything. If you'd rather route it through your own provider, [bring your own key](https://scribelet.app/learn/ai/byok) is there: OpenAI, Anthropic, or Gemini, your key, encrypted at rest, your data going to the provider you picked instead of the one we picked.

**Ready to compare on something other than a feature matrix?** The free plan includes AI verification, so you can point it at your ugliest imported notes before paying anything. [Compare plans](https://scribelet.app/pricing).

## What are the best Evernote alternatives in 2026?

There is no single winner, and any list that names one is selling something. Pick from the reason you're leaving:

- **Closest feel:** UpNote or Zoho Notebook.
- **Free with no cap:** OneNote.
- **Privacy and open source:** Notesnook or Joplin.
- **Structure and databases:** Notion.
- **Local control and linking:** Obsidian.
- **Apple-only and simple:** Apple Notes or Bear.
- **Notes you no longer trust:** Scribelet.

The reason the Evernote alternative question feels exhausting is that everyone answers it with the wrong variable. Feature matrices assume your notes are fine and only the software is wrong. But you've been carrying a slowly spoiling archive from tool to tool, and each migration polished the container while leaving the contents exactly as wrong as they were.

Pick your next app on what it does on day six hundred, not day one. On day one every option in that table looks good, because a fresh import always looks good. Day six hundred is when you find out whether anything in the system was ever going to tell you your notes stopped being true.

![Line chart showing a note app migration lifts how good the app feels while archive accuracy keeps declining](/blog/evernote-alternative/container-vs-contents.svg)

You already have the export file. That's the audit, sitting right there, waiting. [Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and point it at the notes you were least sure about.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>evernote-alternative</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>migration</category>
            <category>comparison</category>
        </item>
        <item>
            <title><![CDATA[Obsidian AI in 2026: The 4 Routes, Compared]]></title>
            <link>https://scribelet.app/blog/obsidian-ai</link>
            <guid isPermaLink="false">https://scribelet.app/blog/obsidian-ai</guid>
            <pubDate>Tue, 14 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Obsidian ships no AI. Four routes add it: plugins, coding agents like Claude Code, MCP servers, and copy-paste. Compared on setup, privacy, and upkeep.]]></description>
            <content:encoded><![CDATA[
Search "Obsidian AI" and you will find hundreds of tutorials, plugin roundups, and YouTube walkthroughs. What you will not find, on the app's own site, is an AI feature. Obsidian ships with no built-in assistant, no chat, no semantic search, no generation. That is not an oversight. It is the whole design: a fast, local-first Markdown editor that leaves everything else to a community plugin ecosystem.

So when people ask how to get AI into Obsidian, the honest answer is that you assemble it yourself. There are exactly four ways to do it, and they are not variations on one theme. They differ in what you install, how much of your vault leaves your machine, how long the setup takes, and what breaks when something upstream changes.

This guide compares all four, gives a verdict on each of the main plugins, and shows where every one of them stops. If your goal is a note system that stays accurate on its own rather than one that answers questions on demand, there is a structural gap worth naming before you invest a weekend in it.

## What is Obsidian AI?

Obsidian AI is not a product. It is the umbrella term for adding artificial intelligence to Obsidian through community plugins (like Copilot, Smart Connections, and Text Generator) or external tools connected to your Markdown vault. The core Obsidian app has no native AI; every capability comes from something you install and configure yourself. For the general, non-AI plugins worth keeping, see [a full roundup of the best Obsidian plugins](https://scribelet.app/blog/best-obsidian-plugins).

That distinction matters because it shapes everything downstream. In an app with native AI, the intelligence knows about your notes by default. In Obsidian, each piece is a separate bolt-on that you point at your vault, feed an API key, and update on its own schedule. You are the integration layer.

Obsidian itself is [free for personal use](https://obsidian.md), with paid Sync and Publish add-ons. The AI runs on your own accounts and keys. If you would rather skip the assembly entirely, [Scribelet's free plan](https://scribelet.app/pricing) ships AI in the box; the rest of this piece explains the tradeoff between the two paths.

![The Obsidian AI landscape: the core app has no AI, community plugins add chat and semantic search, external agents connect through MCP, and none of the layers close the maintenance gap that keeps notes accurate over time](/blog/obsidian-ai/obsidian-ai-landscape.svg)

## The four routes at a glance

Every Obsidian AI setup is one of these four, or a combination of them.

| Route | What you install | Setup time | API key | What breaks |
|---|---|---|---|---|
| **1. Community plugins** | A plugin from the directory | 10-20 min | Usually yes | Plugin abandonment, API changes |
| **2. Coding agents** | Claude Code, Cursor, or similar | 30-60 min | Yes (agent subscription) | Agent edits files you did not expect |
| **3. MCP server** | A server process in front of the vault | 1-2 hours | Yes | Server config drifts from the spec |
| **4. Copy and paste** | Nothing | 0 min | No | Nothing, but nothing scales either |

Read the setup-time column against what each route buys you. Routes 1 and 4 are the ones most people should start with. Route 3 is the one most people write about, which is not the same thing.

![Four routes to add AI to an Obsidian vault, compared by how much leaves your machine: copy-paste sends only what you paste, plugins send the notes used as context, coding agents read the whole vault folder, and MCP servers mediate that access through a defined interface](/blog/obsidian-ai/obsidian-ai-routes.svg)

## Route 1: Obsidian AI plugins

The Obsidian [community plugin directory](https://obsidian.md/plugins) lists thousands of extensions, and a growing slice of them add AI. Three do most of the heavy lifting, and they map to three different jobs. Install the one that matches the job you actually have, not all three.

### Copilot for Obsidian: pick it for chatting with your whole vault

[Copilot for Obsidian](https://www.obsidiancopilot.com/) is the closest thing to a native assistant. It gives you a chat panel that answers questions using your vault as context, summarizes notes, and runs multi-step agents. You bring an API key from OpenAI, Anthropic, or another provider, and the plugin does the orchestration.

**Pick it if** you want one panel that does most things and you are comfortable pasting in an API key. **Skip it if** you mainly want better search, because you will be paying per token for something embeddings do more cheaply.

### Smart Connections: pick it for semantic search and related notes

Smart Connections takes a different angle. Instead of chat, it computes embeddings for your notes and surfaces related ones as you write. That is search by meaning rather than by keyword, and it can run locally against your files.

**Pick it if** your vault is large enough that you have stopped finding your own notes, or if you want the least cloud exposure of any plugin here. **Skip it if** your vault is small, where the folder tree and search still work fine.

### Text Generator: pick it for inline drafting from prompts

Text Generator covers the pure writing side: prompt templates that draft, expand, or rewrite text inline, without a chat panel in the way.

**Pick it if** you write in Obsidian and want the model in the document. **Skip it if** you mostly read and retrieve, where a chat panel fits better. Whichever you install, the persona and rules it sends ahead of your text do more work than the sentence you type, and [the four layers an instruction can live in](https://scribelet.app/blog/system-prompt) decide which of them survives past the current session.

Here is how the plugin options compare, including the row people forget.

| Plugin | What it does | Needs an API key | Where it runs |
|---|---|---|---|
| **Copilot for Obsidian** | Chat with your vault, summaries, agents | Yes (your provider) | Local plugin, cloud model |
| **Smart Connections** | Semantic "related notes" and search | Optional (local embeddings possible) | Mostly local |
| **Text Generator** | Inline drafting and rewriting from prompts | Yes (your provider) | Local plugin, cloud model |
| **Obsidian core** | Editing, backlinks, graph view | No AI at all | Fully local |

Read the bottom row again. The base app you fell in love with contributes nothing to the AI column. Everything above it is scaffolding you own and operate, on three separate update cycles, with keys stored in three separate settings panes.

## Route 2: Claude Code and the coding agents

This is the route that has changed most since the plugin ecosystem settled, and it skips plugins entirely. Because an Obsidian vault is just a folder of Markdown files, any coding agent that can read a directory can read your notes. People point Claude Code or Cursor at their vault and get an agent that can search, rewrite, cross-reference, and reorganize hundreds of notes in one pass.

What makes this different from a chat plugin is scope. A plugin answers a question about a note. An agent runs a task across the vault: retag everything from a project, find every note that contradicts a decision you just made, split a 4,000-word dumping ground into atomic notes with links between them. It is the only route on this list that changes many files at once.

That is also the risk. An agent with write access to your vault will do exactly what you asked across files you forgot were in scope.

**Pick it if** you already live in a terminal and a coding agent is your daily driver. **Skip it if** you are not going to back the vault up first, because an agent's mistake arrives at the scale of the whole folder rather than one paragraph. Commit the vault to git before the first run and the whole route becomes reversible.

One thing worth knowing before you start: the agent begins every session knowing nothing about your vault. What it retains between runs is whatever you write down for it, which is a different problem from the one [AI memory](https://scribelet.app/blog/ai-memory) solves in an app that persists context on your behalf.

## Route 3: MCP servers

The connective tissue for the agent route is the [Model Context Protocol](https://modelcontextprotocol.io), an open standard for giving AI models structured access to tools and data. With an MCP server in front of your vault, the agent does not just read raw files; it queries and updates them through a defined interface.

The practical difference is precision. Raw file access means the agent globs the folder and reads whatever it finds, spending its context on files that turned out to be irrelevant. An MCP server exposes operations instead: search notes, read one, append to another. The agent asks for what it needs.

**Pick it if** you are already on Route 2 and the agent keeps reading the wrong files, or you want to expose your vault to more than one tool through the same interface. **Skip it if** you have not run Route 2 yet, because this is optimization for a problem you have not hit. It is the most technical option here and the one whose setup instructions go stale fastest.

## Route 4: copy and paste

Nobody writes tutorials about this one, and a large share of people do it anyway: select the relevant note, paste it into ChatGPT or Claude, ask the question there.

It deserves its place on the list because it is the only route with no install, no key, no config, and no standing access to your files. You decide what leaves your machine every single time, one paste at a time.

**Pick it if** you ask your notes a question occasionally rather than continuously, or your vault holds anything you would not hand to a third party wholesale. **Skip it if** you are doing it twenty times a day, at which point you have manually rebuilt Route 1 at a much worse exchange rate.

## Where your notes actually go

The privacy question is the one every route answers differently and few tutorials state plainly. What follows is what leaves your machine on each route, assuming a default setup.

| Route | What leaves your machine | Local-only option |
|---|---|---|
| **Copy and paste** | Only the text you pasted | Yes, use a local model |
| **Community plugins** | The notes sent as context, plus your prompt | Partly (local embeddings for search) |
| **Coding agents** | Whatever the agent reads, which can be the whole folder | Only with a locally hosted model |
| **MCP server** | What the server exposes, which you define | Yes, if the model behind it is local |

Two things fall out of that table. First, the routes are ordered by exposure in the reverse of how they are usually recommended: the most-written-about route sends the most. Second, "local" is a property of the *model*, not the route. A plugin running on your laptop that calls a cloud API is not a local setup, whatever the install location suggests. If keeping the key relationship in your own hands matters, that is a [bring your own key](https://scribelet.app/blog/byok-ai) question rather than a plugin question.

## What every Obsidian AI setup still cannot do

Here is the pattern across all four routes. Plugins chat with your notes. Agents rewrite your notes. Embeddings connect your notes. Every one of these acts on the note as it exists right now, treating whatever you wrote as ground truth.

None of them check whether what you wrote is still true.

That is the gap. Your notes reference a moving world: an API that ships a breaking change, a pricing page that goes up, a framework that deprecates the pattern you documented, a citation that gets retracted. The note sits in your vault looking exactly as authoritative as the day you wrote it while the thing it describes drifts out from under it. This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and a bolt-on AI layer is structurally blind to it, because chat and generation are reactive acts and decay is a continuous one.

You can see the shape of the problem in what each route optimizes. Copilot makes it faster to ask a question. Smart Connections makes it easier to find a related note. Claude Code makes it faster to restructure a hundred of them. Not one runs on a schedule, searches the live web, and tells you that the answer you saved six months ago no longer holds. The most sophisticated agent setup in the world will happily summarize an outdated note into a confident, outdated brief. Garbage in, eloquent garbage out.

This is not a knock on the plugins or the agents. It is a limit of the architecture. A folder of static Markdown files plus an on-demand model is a great writing environment and a poor maintenance system, because nobody in that loop is responsible for the notes staying correct while you are not looking.

## What native AI note-taking looks like

Start with the principle, not the product. A note system that fights decay has to do something no route above does: revisit its own contents on a schedule and tell you when reality has moved. When AI is native rather than bolted on, that becomes a default behavior instead of a plugin you hope keeps working.

In Scribelet, the AI is not a panel you install. Chat, semantic search, and memory are built in, and the piece the plugin stack is missing runs automatically: [background verification](https://scribelet.app/learn/ai/ai-verification). On a schedule you set, it searches the web, compares what it finds to what a note claims, and hands you a diff: green for new information, red for what no longer holds. You review it, accept or dismiss, and the note updates. The intelligence is not just answering questions about your notes; it is keeping them worth answering from.

Two honest tradeoffs, because the sovereignty crowd deserves them straight. First, Scribelet is not local-first plain files the way Obsidian is. Your notes live in an encrypted, synced store you can export, not a folder on your disk, and for some people that alone settles it in Obsidian's favor. Second, verification helps most for notes that reference an external, checkable world; a private journal entry does not need fact-checking, and the system leaves it alone.

What Scribelet keeps from the Obsidian ethos is control over the model. You can bring your own key for OpenAI, Anthropic, or Gemini, so your prompts go to the provider you chose rather than one we picked for you. And if you like the agent workflow, Scribelet exposes its own [MCP server](https://scribelet.app/learn/ai/mcp-server) too, so Claude Code and Cursor can drive your notes the same way they drive a vault, with a maintenance layer underneath.

**See what AI-native notes feel like without assembling a stack.** [Set up your first desk in a few minutes.](https://scribelet.app/learn/getting-started/quick-start)

## Which route fits you?

There is no universal answer, so match the route to what you actually want.

1. **Copy and paste** if you ask your notes a question now and then. Zero setup, zero standing access, and it is not the embarrassing answer people assume.
2. **Stay and plug in** if the tinkering is the reward. Keep your Markdown vault and add Copilot for chat or Smart Connections for search. You will spend setup time, juggle keys, and get exactly the system you configured.
3. **Go agent-first** if you live in a terminal. Pointing Claude Code at your vault gives you the most raw power and the widest blast radius. Put the vault in git first.
4. **Switch to native** if you want AI that maintains, not just generates. If the goal is notes that stay accurate on their own and you would rather not run a stack, a tool with verification, chat, and memory in the box gets you there without the assembly. We put [the four ways to build an AI second brain](https://scribelet.app/blog/ai-second-brain-setup) side by side, including what each one costs you in upkeep once the novelty wears off.

Three of these keep you in Obsidian, and that can absolutely be the right call. If you are weighing a move, we wrote separately about how [the best Obsidian alternative depends on why you are leaving](https://scribelet.app/blog/obsidian-alternative), and about the deeper [Notion versus Obsidian](https://scribelet.app/blog/notion-vs-obsidian) split between a cloud database and a folder of files. The AI question sits on top of that older one; the base tool still shapes what the AI can do.

## The AI Obsidian left to you

Obsidian's decision to ship no AI is defensible and, in its way, admirable. A lean local-first editor plus an open plugin market is a legitimate answer, and for people who enjoy building their own system it is the best answer there is. The plugins are good. The agent route is genuinely powerful. The [portability of plain Markdown](https://scribelet.app/blog/markdown-note-taking-apps) is real.

Just be clear-eyed about what you are signing up for. You become the integration layer, you decide on every route how much of your vault leaves your machine, and the whole stack still leaves the hardest job undone, which is keeping the notes true after you file them. If assembling that appeals to you, assemble it well. If it does not, the alternative is an app where the intelligence and the maintenance come standard, so the question stops being how to add AI to your notes and becomes what you want to do with the ones that stay accurate. [Start writing with a note app that keeps its own notes current. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>obsidian</category>
            <category>obsidian-ai</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>ai</category>
            <category>mcp</category>
        </item>
        <item>
            <title><![CDATA[The PARA method has no maintenance step]]></title>
            <link>https://scribelet.app/blog/para-method-with-ai</link>
            <guid isPermaLink="false">https://scribelet.app/blog/para-method-with-ai</guid>
            <pubDate>Mon, 13 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The PARA method files every note into Projects, Areas, Resources, and Archives but never checks if they're still true. Here's the step it skips. Start free.]]></description>
            <content:encoded><![CDATA[
A year ago you set up PARA. Four folders, one clean decision tree, and for a few weeks it felt like your digital life finally had a shape. Projects for what you're working on, Areas for what you maintain, Resources for what might matter later, Archives for what's done. Every note had a home. And it was meant to hold everything, not just your job, because [the parts of your life that aren't work](/blog/second-brain-for-personal-life) generate just as much to keep track of.

Open that system today. Projects still looks alive. Areas is mostly current. But Resources has become a drawer you're afraid to open, full of notes that were accurate the day you filed them, and Archives is worse: a sealed room of things you decided were finished and never looked at again. The PARA method told you exactly where to put each note. It never told you which of those notes stopped being true.

This is the quiet flaw in the most popular organizing system in personal knowledge management, and it has nothing to do with the four categories being wrong. They're good categories. The problem is that PARA is a system for deciding where a note goes, and there is no step for deciding whether a filed note is still worth trusting. This piece walks through what PARA does well, where it breaks down over months, and what a note-taking setup looks like when maintenance is built in instead of assumed.

## What is the PARA method?

The PARA method is a system for organizing digital information into four categories by how actionable it is: Projects (short-term efforts with a goal), Areas (ongoing responsibilities), Resources (topics of future interest), and Archives (inactive items). It was created by Tiago Forte and popularized through his book [Building a Second Brain](https://www.buildingasecondbrain.com/para).

The appeal is real. Most organizing schemes sort by topic, which forces you to invent a taxonomy and then fight it forever. PARA sorts by actionability instead, which maps to how you actually work: things you're doing now, things you tend, things you might need, things you're done with. You use the same four buckets across every tool, so a note, a file, and a task all follow one rule. Forte lays out [the full framework on his blog](https://fortelabs.com/blog/para/), and it deserves its reputation as the fastest way to go from chaos to a workable structure.

But look closely at what those four categories describe. Every one of them is a statement about *placement*. Where does this belong right now? None of them is a statement about *accuracy*. Is this still correct? PARA is a brilliant answer to the first question and silent on the second, and over a long enough timeline the second question is the one that costs you.

## PARA is a filing system, not a maintenance system

Here is the assumption baked into every PARA tutorial: a note's value is fixed once you file it correctly. Put it in the right bucket and the job is done. That assumption holds for a physical filing cabinet, where a document is a frozen artifact. It does not hold for the kind of notes knowledge workers actually keep.

Your notes reference a moving world. The API you documented ships a breaking change. The pricing you saved from a competitor goes up. The onboarding process you wrote down gets three new steps. The paper you cited gets a correction.

None of that changes where the note lives in PARA. The note sits exactly where you filed it, looking as authoritative as the day you wrote it, while the thing it describes drifts out from under it. This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and a filing system is structurally blind to it, because filing is a one-time act and decay is a continuous one.

That blind spot is not unique to PARA. It's the same gap we've written about across every popular method: they all optimize the moment of capture and organization, and then [none of them include a maintenance phase](https://scribelet.app/blog/living-notes-method). PARA just makes the gap especially visible, because its whole promise is a place for everything. A place for everything, and no mechanism to check whether the things in those places are still true.

If you want the short version of the fix before the long one: [Scribelet's free plan](https://scribelet.app/pricing) keeps the four-bucket structure you already like and adds the checking step PARA leaves out. The rest of this explains why that step matters and how it works.

![The PARA method's four buckets (Projects, Areas, Resources, Archives) decay at different rates, and the missing maintenance step checks whether each note is still true](/blog/para-method-with-ai/para-maintenance-gap.svg)

## Where PARA quietly breaks: Resources and Archives

Projects and Areas mostly take care of themselves, because you touch them. An active project gets revisited constantly, so a wrong note in it surfaces fast. An area you maintain gets the same attention by definition. The decay problem concentrates in the two buckets you stop looking at.

Resources is the first casualty. It's the catch-all for "interesting, might need it," which means it accumulates faster than anything else and gets reviewed least. A year in, Resources is where you saved the deployment steps, the tax rule, the framework comparison, the vendor's rate card. Every one of those was a snapshot of a moment. Half of them have moved. You won't find out which half until you reach for one under pressure and build on information that expired six months ago.

Archives is the more insidious one, because PARA actively encourages you to forget it. The entire point of the Archive is to get inactive things out of sight so your workspace stays clean, and that's genuinely useful for focus. But "out of sight" and "no longer true" are a dangerous pair.

A project you archived as complete leaves behind notes, decisions, and references. When a similar project starts, you pull those archived notes back into active use, trusting them precisely because they represent finished, settled work. That's exactly when their age bites. The Archive is where accurate notes go to quietly rot, and PARA's design guarantees you won't notice until you've already relied on one.

## PARA vs Zettelkasten: two methods, one blind spot

People often frame this as a choice. PARA organizes by actionability; the [Zettelkasten method](https://scribelet.app/blog/zettelkasten-with-ai) organizes by connection, linking atomic notes into a web of ideas. Sönke Ahrens made the case for the latter in [How to Take Smart Notes](https://www.soenkeahrens.de/en/takesmartnotes), and the two camps argue about which structure produces better thinking.

The argument misses what they have in common. Both are systems for arranging notes, and neither has anything to say about keeping the content of those notes correct over time. A Zettelkasten with a dense, beautiful link graph can be a dense, beautiful graph of outdated claims. A PARA system with perfect bucket discipline can be perfectly organized misinformation. Structure is orthogonal to accuracy. You can have flawless organization and still be reading something false, because organization tells you where a note is, not whether it holds up.

That's the reframe worth carrying: the method you pick decides how your notes are shaped, not whether they stay true. Shape is a one-time design decision. Truth is an ongoing maintenance problem, and every method on the market leaves it to you.

## What a self-maintaining PARA system looks like

Start with the principle, not the product. A note system that fights decay has to do something no filing method does: revisit its own contents on a schedule and tell you when reality has moved. Not reorganize them. Re-check them. The buckets can stay exactly as PARA designed them. What changes is that something is watching the notes inside them.

In Scribelet, that watching is [background verification](https://scribelet.app/learn/ai/ai-verification). On a schedule you set, it searches the web, compares what it finds to what a note claims, and hands you a diff: green for new information, red for what no longer holds. You review it, accept or dismiss, and the note updates. The Resources drawer stops being a place things go to expire, because the expiring ones raise their hand. The Archive stops being a sealed room, because a note you pull back into active work gets checked before you build on it. This is the same maintenance discipline behind a working [AI second brain](https://scribelet.app/blog/ai-second-brain-setup), applied to the buckets you already sorted.

Here is how the four categories change when maintenance is part of the system rather than an afterthought you never get to.

| PARA bucket | What PARA does | What decays over time | What a maintenance layer adds |
|---|---|---|---|
| **Projects** | Holds active, goal-bound work | Little; you touch it constantly | Auto-links related notes as the project grows |
| **Areas** | Holds ongoing responsibilities | Slowly; standards and contacts shift | Flags a note when its facts change |
| **Resources** | Catch-all for future reference | Fast; snapshots go stale unreviewed | Scheduled checks surface what expired |
| **Archives** | Stores finished, inactive items | Silently; nobody rereads it | Re-verifies a note before you reuse it |

Read the last column top to bottom and it describes the step PARA is missing across all four buckets: not a better place to put the note, but a way to know the note is still worth having. None of this asks you to abandon PARA. It asks the system to do the part of the job the method quietly handed back to you.

The honest caveat: verification helps most for notes that reference an external, checkable world. A note documenting a library's API, a market rate, a policy, or a process gets real value from it. A private journal entry or a rough idea does not need fact-checking, and the system leaves those alone. Maintenance is for the notes whose truth lives outside your head.

## PARA across every device and every tool

Forte's original pitch for PARA is that you run the same four buckets everywhere: your files, your tasks, your notes, all under one structure. That consistency only pays off if the notes themselves are consistent across devices, which is its own quiet failure point. A note that's stale on your laptop is stale on your phone the moment it syncs, faithfully copied to every screen you own.

So the tool you run PARA in matters more than the tutorials admit. It should keep the structure identical on [every device you use](https://scribelet.app/blog/cross-platform-note-taking-app), sync without losing edits, and run the maintenance checks regardless of where you opened the note. PARA gives you one organizing rule; the app should give you one accurate copy of each note under that rule, not five copies of the same expired snapshot.

**Try the version of PARA that checks itself.** Keep Projects, Areas, Resources, and Archives exactly as you like them, and let background verification handle the part the method skips. [Get set up in a few minutes.](https://scribelet.app/learn/getting-started/quick-start)

## Is the PARA method worth it?

Yes, with one adjustment. As a way to decide where a note, file, or task belongs, PARA is close to the best system there is: fast to learn, flexible across tools, and free of the taxonomy wars that sink topic-based schemes. If you have no structure today, adopting PARA is a clear upgrade and you should do it.

Just don't mistake it for a complete knowledge system. PARA is the placement half, and [what a PKM system actually needs](https://scribelet.app/blog/personal-knowledge-management) is a maintenance half to go with it. It answers "where does this go?" and stops, and it was never designed to answer "is this still true?" Treat that second question as your responsibility, and either run a periodic review of your own Resources and Archives by hand, or use a tool that runs the check for you. The method plus a maintenance habit beats the method alone, every time.

## The bucket PARA forgot

PARA divides everything you know into four categories, and there's a fifth idea it left out that matters more than any of them: whether the note in the bucket is still accurate. Organization was the hard problem a decade ago. It's a solved problem now, and PARA solves it well. The unsolved problem is decay, and no amount of clean filing touches it.

So keep the four buckets. They earned their place. Then add the step they assume you'll do yourself and almost never do: check that what you filed is still worth trusting. [Start writing with a system that keeps your notes accurate, not just organized. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>para-method</category>
            <category>pkm</category>
            <category>note-taking</category>
            <category>second-brain</category>
            <category>knowledge-management</category>
        </item>
        <item>
            <title><![CDATA[The Best Markdown Note-Taking App in 2026: 11 Compared]]></title>
            <link>https://scribelet.app/blog/markdown-note-taking-apps</link>
            <guid isPermaLink="false">https://scribelet.app/blog/markdown-note-taking-apps</guid>
            <pubDate>Sun, 12 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Eleven markdown note-taking apps compared, with a five-minute portability test you can run before you commit to any of them. Try it free.]]></description>
            <content:encoded><![CDATA[
You picked markdown for a good reason. You were tired of notes trapped inside a proprietary format, tired of an app that could disappear and take your writing with it, tired of copy-pasting out of a rich-text box that mangled the formatting. Plain text with a little structure felt like the honest choice, and it was.

So you go looking for a markdown note-taking app and find a crowded field, each tool promising the cleanest editor and the truest plain-text soul. Most roundups rank them on the same three traits: does it store real `.md` files, does it sync, does the editor feel nice.

Those traits matter, and this guide covers them app by app. But it also gives you something the comparison tables leave out: a five-minute test you can run on any candidate to find out whether "supports markdown" actually means your notes are portable. Several popular apps fail it. And at the end there is the question none of the eleven answers, which is the reason we built [Scribelet's Free plan](https://scribelet.app/pricing) the way we did.

## What is a markdown note-taking app?

A markdown note-taking app is a note tool that stores your writing as plain text using markdown syntax: `#` for headings, `*` for emphasis, `-` for lists, `[ ]()` for links. Because the underlying file is plain text, you can read it in any editor, move it between tools without conversion, and keep it long after the app that made it is gone.

That last part is the real appeal. Markdown is a format you own. It was published by John Gruber in 2004 as a way to write structured text that stays readable as plain text, and it has since been standardized as [CommonMark](https://commonmark.org/), which means a heading you write today parses the same way in ten years. No vendor controls it. No subscription unlocks it. Your notes are a folder of text files, and text files outlive every app.

The catch, which the next section will make concrete, is that "markdown app" describes two quite different things. Some tools keep a folder of `.md` files you can open in any editor. Others store notes in a database and let you *type* markdown syntax. Both are marketed identically. Only one of them gives you the portability you came for.

## The best markdown note-taking apps at a glance

| App | Platforms | Real `.md` files on disk | Sync | Price | Best for |
|---|---|---|---|---|---|
| **Obsidian** | Mac, Win, Linux, iOS, Android | Yes | Paid add-on | Free personal use | Power users who want plugins and a graph |
| **Logseq** | Mac, Win, Linux, iOS, Android | Yes | Paid or self-host | Free, open source | Outliners and block references |
| **Joplin** | Mac, Win, Linux, iOS, Android | Export only | Your own backend | Free, open source | End-to-end encryption you can audit |
| **Bear** | Apple only | No, database | iCloud | Subscription | The prettiest editor on Apple devices |
| **Typora** | Mac, Win, Linux | Yes | None built in | One-time purchase | Pure inline editing, one file at a time |
| **iA Writer** | Mac, Win, iOS, Android | Yes | iCloud or Dropbox | One-time purchase | Long-form drafting |
| **Inkdrop** | Mac, Win, Linux, iOS, Android | No, database | Built in | Subscription | Developers who want code-first notes |
| **Notable** | Mac, Win, Linux | Yes | None built in | Free | A free desktop app over a folder you own |
| **Zettlr** | Mac, Win, Linux | Yes | None built in | Free, open source | Academic writing with citations |
| **Simplenote** | Mac, Win, Linux, iOS, Android, web | Export only | Built in, free | Free | The lightest cross-platform option |
| **Scribelet** | iOS, Android, web | Markdown source of truth | Built in, offline queue | Free tier | Notes that have to stay accurate |

Read down the third column and the field splits in a way no marketing page admits. Three of these eleven do not put a `.md` file anywhere you can reach it.

## The 11 best markdown note-taking apps, compared

Each of these is genuinely good at something. The verdicts below say who should pick it and, more usefully, who should not.

### Obsidian: best for power users who want plugins and a graph

Obsidian is the default recommendation for a reason. It points at a local folder of `.md` files, has the largest plugin ecosystem in the category (which is also where [the AI plugins for Obsidian](https://scribelet.app/blog/obsidian-ai) live, since it ships none natively), and its graph view made networked note-taking mainstream.

The tradeoffs are real. The desktop app runs on [Electron](https://www.electronjs.org/) so it is heavier than it looks, the mobile app is a separate and less-loved build, and reliable syncing between devices runs through a paid add-on.

**Pick it if** you want the deepest customization available and you enjoy assembling your own setup.
**Skip it if** you want something that works well on day one without plugins, or if paying for sync on top of a free app annoys you. We wrote a guide to picking [an Obsidian alternative](https://scribelet.app/blog/obsidian-alternative) sorted by exactly why people leave.

### Logseq: best for outliners and block references

Logseq takes the outliner path. Everything is a bullet, notes are block-referenced rather than page-linked, and it stores local markdown. If you think in outlines, it fits your head better than anything else here.

Its 2.0 direction moves the canonical copy of your notes into a database rather than files, which matters a great deal if plain text is the reason it is on your list.

**Pick it if** you think in nested bullets and want block-level linking.
**Skip it if** you think in documents, or if the database shift worries you. Read [what Logseq's database switch changes](https://scribelet.app/blog/obsidian-vs-logseq) before committing, and see [what to use instead of Logseq](https://scribelet.app/blog/logseq-alternative) if it is a dealbreaker.

### Joplin: best open-source app with end-to-end encryption

Joplin is the option you can audit. It is open source, supports end-to-end encryption, and syncs through a backend you choose: Dropbox, OneDrive, S3, WebDAV, or its own paid cloud. The web clipper is the best in this list.

The honest caveat is storage. Joplin keeps notes in a local database and writes markdown on export, so the folder-of-files experience is not what you get day to day.

**Pick it if** encryption and self-hosting outrank editor polish for you.
**Skip it if** you want to open your notes folder in another editor without exporting first, or if a utilitarian interface will bother you.

### Bear: best-looking markdown app on Apple devices

Bear is the most beautiful note app on Apple platforms. The typography is careful, the nested-tag organization is elegant, and it feels native because it is.

Two walls. It is Apple-only, so the moment an Android phone or a Windows laptop enters your life it is off the table. And it stores notes in a database using its own markdown-flavored markup, so what you have is markdown-*style* writing with an export button, not a folder of files.

**Pick it if** you are entirely inside Apple's ecosystem and want the nicest writing experience money buys.
**Skip it if** you have any non-Apple device, or if you want to reach your notes without opening Bear.

### Typora: best pure markdown editor

Typora renders markdown inline as you type, with no split preview pane, and the result is close to writing in a clean document while producing real `.md` files. It is a one-time purchase after a trial, which is increasingly rare.

It is not an organization system. There is no sync, no linking layer, no library. It edits files, beautifully.

**Pick it if** you already have a folder structure and a sync method and just want the best editor to sit on top of them.
**Skip it if** you want the app to organize anything, or if you need your notes on a phone.

### iA Writer: best for long-form drafting

iA Writer is the writer's markdown app: focused, distraction-free, opinionated about typography and about keeping you in the text. Focus mode and syntax highlighting for parts of speech are genuinely useful when you are drafting something long. It writes real `.md` files and syncs through iCloud or Dropbox.

**Pick it if** most of what you write is prose that will eventually be published somewhere.
**Skip it if** you want a sprawling knowledge base with hundreds of interlinked notes. It is a writing tool, not a library.

### Inkdrop: best markdown note-taking app for developers

Inkdrop is built for people who paste code into notes. Multi-language syntax highlighting, a vim mode, a plugin API, and cross-platform apps that all sync through its own service without configuration. If your notes are half snippets, it is the most comfortable option in this list.

It is subscription-only with no free tier, and notes live in its database rather than a folder you browse.

**Pick it if** you take code-heavy notes on several machines and want sync that just works.
**Skip it if** you want a free option or file-level access to your own notes.

### Notable: best free desktop app over a folder you own

Notable works directly on top of a local folder of `.md` files, with no proprietary database in between, which means you can edit the same notes in any other editor at any time. It is free, and it is the plainest expression of the "your notes are just files" idea in this list.

It is desktop-only, and development has been quiet for a while. That is survivable precisely because the notes are plain files: if it stops, nothing is trapped.

**Pick it if** you want a free, honest desktop editor over a folder you already control.
**Skip it if** you need mobile access or you want a tool under active development.

### Zettlr: best for academic writing and citations

Zettlr is the one built for researchers. It connects to Zotero and other citation managers, handles citeproc references properly, exports through Pandoc to PDF, Word and LaTeX, and stores everything as local markdown. If you are writing a thesis rather than keeping a work log, it is the only tool here designed for the job. If you are still in coursework rather than writing a thesis, our guide to [the best note-taking app for students](https://scribelet.app/blog/best-note-taking-app-for-students) weighs these markdown tools against handwriting and flashcard apps.

**Pick it if** you write anything that needs a bibliography.
**Skip it if** you do not, because the citation machinery is most of the point.

### Simplenote: best free cross-platform option

Simplenote is the lightest thing here. It is free with no paid tier, runs everywhere including the web, syncs instantly, and has excellent version history. Markdown rendering is a per-note toggle rather than the foundation, and there are no folders, no attachments, and no images.

**Pick it if** you want fast, free, everywhere plain-text capture and nothing more.
**Skip it if** you need images, attachments, or any structure beyond tags.

### Scribelet: best for notes that have to stay accurate

Scribelet keeps markdown as the source of truth, the same portable text you would get from Obsidian or Typora, and runs natively on iOS, Android and web with sync included rather than sold as an add-on. What it adds is the layer described further down: background verification that checks whether your notes are still true.

**Pick it if** your notes contain facts that go stale, which is most technical and professional notes.
**Skip it if** you want a desktop-first app with a plugin ecosystem. That is Obsidian's job and it does it well.

![Markdown solves the portability layer of a note, but leaves the accuracy layer empty; Scribelet fills it with maintenance](/blog/markdown-note-taking-apps/markdown-portability-vs-accuracy.svg)

## The five-minute portability test

Every app above claims markdown support. That claim is doing a lot of work, and it hides the difference between a tool that keeps your notes in files and a tool that keeps them in a database that speaks markdown. Run these five checks on any candidate before you move a year of notes into it. It takes about five minutes and it is the only test in this guide that costs nothing to be wrong about.

1. **Find a note on disk.** Write one note, then go looking for it in Finder or Explorer without the app's help. If you land on a `.md` file you can read, the app passes. If you find a `.db`, a `.sqlite`, or a folder of numbered blobs, it does not.
2. **Edit it from outside.** Change that file in a plain text editor, save, and switch back. A file-based app shows the change, usually within a second. A database app either ignores it or overwrites you.
3. **Move one note to another app.** Copy the file into a second markdown editor and look at what breaks. Wikilinks, callouts, embedded queries and tag syntax are where the damage shows up. This is the dialect problem, and the table below covers it.
4. **Check an attachment.** Add an image, then find it. Is it a real file next to the note with a relative link, or did the app absorb it into storage you cannot browse? Attachments are where "just markdown" quietly stops being true.
5. **Do the uninstall test.** Imagine the company shuts down tomorrow and the app will not launch. Can you still read, search and use your notes with nothing but a text editor? If the honest answer is no, you have a nice editor, not a portable archive.

Three of the eleven apps above fail step one. That is not a reason to avoid them, and Bear in particular is a joy to use. It is a reason to know which promise you are actually buying.

## Not all markdown is the same: the dialect problem

The second thing comparison tables miss is that markdown is a base standard with a pile of app-specific extensions layered on top. The base is portable. The extensions, which are the features you will use most, frequently are not.

| Syntax | Example | Portable? |
|---|---|---|
| Headings, emphasis, lists, links | `# Heading`, `**bold**` | Yes, everywhere. CommonMark. |
| Tables, fenced code blocks, task lists | `- [ ] todo` | Mostly. GitHub-flavored markdown, widely supported. |
| YAML frontmatter | A `tags:` block fenced by `---` at the top of the file | Usually preserved, but read differently by each app. |
| Wikilinks | `[[Another note]]` | No. Obsidian, Logseq and Scribelet understand these. Typora and iA Writer render them as literal text. |
| Inline tags | `#project` | No. Some apps index them, some treat them as a heading, some as plain text. |
| Callouts and admonitions | `> [!note]` | No. Obsidian syntax. Elsewhere it is a blockquote with odd brackets in it. |
| Block references | `((block-id))` | No. Logseq-specific and meaningless outside it. |
| Embedded queries | Dataview, and similar | No. These are plugin output, not content. They export as the query, not the answer. |

![Three tiers of markdown syntax: CommonMark basics move everywhere, GitHub-flavored extensions mostly move, and app-specific syntax like wikilinks and callouts does not move at all](/blog/markdown-note-taking-apps/markdown-dialect-portability.svg)

The practical rule: the more a feature does for you, the less portable it is. That is not an argument against using wikilinks or callouts, both of which are worth it. It is an argument for knowing which parts of your notes are text and which parts are a bet on one vendor's parser, so a future move is a decision rather than a discovery.

## The best markdown note-taking app for Android, Mac and Windows

Platform is the filter that quietly eliminates most of this list, and it is the one people apply last instead of first.

**On Android**, the field shrinks hard. Obsidian, Logseq, Joplin, iA Writer, Inkdrop and Scribelet ship real Android builds. Bear does not and will not. Typora, Notable and Zettlr are desktop-only. If you carry an Android phone, filter for a real Android app before you compare anything else, because a beautiful desktop editor you cannot reach on the train is not a note system.

**On Mac**, everything here works and the choice comes down to taste, so let the portability test decide rather than the screenshots. Bear and iA Writer are the most pleasant; Obsidian and Logseq are the most capable; Typora and Notable are the most honest about being editors.

**On Windows**, drop Bear and everything on that list still stands. Obsidian, Logseq, Joplin, Typora, Notable, Zettlr and Simplenote all have native Windows builds, and iA Writer has one too.

**Cross-platform is a sync question, not an app question.** Most of the pain people report is not about editors, it is about two devices disagreeing. Scribelet [runs natively on iOS, Android and web](https://scribelet.app/blog/cross-platform-note-taking-app) from a single codebase with offline-first sync and conflict detection, which is the specific problem being solved.

## Do you need to pay for a markdown note-taking app?

No, not to start. Several of the best markdown note-taking apps are free at the level most people use them. Logseq, Joplin, Notable, Zettlr and Simplenote are free, Obsidian is free for personal use, and Typora and iA Writer are one-time purchases rather than subscriptions. The costs hide in two places: sync and platform.

Sync is where the free label frays. Obsidian is free, but reliable syncing across your devices is a paid add-on, and that is the single most common reason people go shopping for something else. If an app is free on the desktop but charges to make your phone and laptop agree, price the sync, not the app.

Platform is the other catch, and it bites hardest on Android, for the reasons above.

Scribelet's Free plan covers unlimited notes, the full markdown editor, wikilinks, tags, and sync across iOS, Android and web, with no add-on to make your devices talk. The paid tier adds the maintenance layer below. You pay for the part that does work no other markdown app does, not for the basics.

## The question no markdown note-taking app answers

Here is the thing every roundup skips, including the version of this one we published first. Markdown guarantees your note is *portable*. It says nothing about whether your note is *right*.

Open a markdown file you wrote eighteen months ago about a library's API, a pricing tier, a deployment runbook, a config flag. The text is pristine. The syntax parses. iCloud synced it flawlessly to every device. And the content is wrong, because the API shipped a breaking change, the price went up, the flag was renamed, and the note never heard about any of it.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and it is the quiet failure mode of every plain-text system. Markdown solved the problem of the format rotting. It did nothing about the *facts inside the format* rotting, which is the problem that actually costs you: acting on a note you trusted and finding out too late it went stale. Plain text is a fantastic container. A container does not check its own contents.

Notice that none of the eleven apps claim to. Obsidian will store the stale note forever. Bear will render it beautifully. Typora will let you edit it cleanly. They are editors and libraries, and they have decided, reasonably, that keeping your facts current is your job. The trouble is that nobody does that job, because auditing a folder of hundreds of notes by hand is exactly the chore no human keeps up with.

## Markdown plus a maintenance layer

So keep the part that works. You should not give up plain text to fix this, and you do not have to.

Scribelet keeps markdown as the source of truth, the same portable, standards-based text you would get from Obsidian or Typora, and it passes its own portability test. On top of that it adds the layer the others leave blank: it watches your notes for decay. [Background verification](https://scribelet.app/learn/ai/ai-verification) periodically searches the web, compares what it finds against what your note claims, and shows you a diff, green for what is new, red for what is outdated, with a source link. You review, accept or dismiss, and the note stays correct without you auditing anything by hand.

The AI works out of the box. If you would rather route it through your own provider, [bring your own key](https://scribelet.app/blog/byok-ai) for OpenAI, Anthropic, or Gemini, so your prompts go to the model you chose and your keys are encrypted at rest. That is a choice, not a setup requirement.

If you are weighing the two biggest incumbents while you shop, our [breakdown of plain files versus a database](https://scribelet.app/blog/notion-vs-obsidian) covers that fork in more detail than a table can.

## How to choose a markdown note-taking app

Skip the agonizing. Match the tool to the need:

1. **You want the biggest ecosystem and do not mind tinkering.** Obsidian, and budget for Sync.
2. **You think in outlines and block references.** Logseq.
3. **You want open source and encryption above all.** Joplin.
4. **You live entirely on Apple and want the prettiest editor.** Bear, knowing it is a database.
5. **You just want to write, one clean file at a time.** Typora or iA Writer.
6. **Your notes are mostly code.** Inkdrop.
7. **You want free and file-based on the desktop.** Notable or Zettlr.
8. **You want the lightest possible capture everywhere.** Simplenote.
9. **You want portable markdown that also stays accurate, on every device.** Scribelet.

Run the five-minute portability test on your top two before you migrate anything. It is the cheapest hour of research in this whole category, and it is the difference between choosing an app and choosing a format.

Markdown made your notes portable. It is a good foundation, and most of these tools will not trap your writing. But a note that is portable everywhere and wrong everywhere is still wrong. If you want the plain-text foundation with a maintenance layer on top, [set up your first desk in five minutes](https://scribelet.app/learn/getting-started/quick-start) and see what your notes look like when something keeps them current.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>note-taking</category>
            <category>markdown</category>
            <category>productivity</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[11 Cross-Platform Note-Taking Apps That Work on Every Device (2026)]]></title>
            <link>https://scribelet.app/blog/cross-platform-note-taking-app</link>
            <guid isPermaLink="false">https://scribelet.app/blog/cross-platform-note-taking-app</guid>
            <pubDate>Fri, 10 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[The 11 best cross-platform note-taking apps, rated for late 2026 on native quality, sync, and offline handling, plus the one thing every roundup skips. Try it free.]]></description>
            <content:encoded><![CDATA[
*Updated November 2026: refreshed picks, a quick-answer shortlist by situation, and the current state of free sync across all eleven apps.*

You jot a half-formed idea into your phone while waiting for coffee. Two hours later you want to expand it at your desk, and that evening you reach for it again on a tablet on the couch. Three devices, one thought, and somewhere in that handoff the friction shows up: the note synced late, the mobile app choked on the formatting, or the thing you wrote on the laptop simply is not there yet on the phone.

That handoff is the whole promise of a cross-platform note-taking app, and it is exactly where most of them quietly break. "Runs on iOS, Android, and web" sits on every feature page. Whether it runs *well* on all three, syncs without drama, and keeps the note usable once it is there is a much shorter list.

This piece is for anyone who works across more than one device and is tired of a note app that treats one platform as the real product and the rest as afterthoughts. Below are 11 well-known options rated on what actually decides a handoff, plus the one thing every "works everywhere" checklist leaves out. If you want to skip the reading and just try one, [Scribelet's Free plan](https://scribelet.app/pricing) runs natively on all three from a single codebase.

## Cross-platform note app quick picks (2026)

If you want the short answer, match the row to your main constraint and read that app's section below.

- **Best free all-rounder:** OneNote. Native-enough everywhere, free OneDrive sync, strong handwriting.
- **Best for local files and Linux:** Obsidian. Plain Markdown you own, though sync is a paid add-on.
- **Best for privacy:** Standard Notes. End-to-end encrypted, free syncing on every platform.
- **Best open source:** Joplin. Markdown, your own encrypted cloud, every OS.
- **Best quick-capture inbox:** Google Keep or Simplenote. Instant, free, and light.
- **Best native mobile with notes kept accurate:** Scribelet. One codebase across iOS, Android, and web, plus background checks that flag stale notes.

The rest of this guide is why each of those picks lands where it does, and the two columns (safe offline sync, and whether a note stays *accurate* everywhere) that decide it once every app clears the "runs on all my devices" bar.

## What makes a note app truly cross-platform?

A truly cross-platform note-taking app runs natively on each operating system, syncs reliably with offline support and conflict handling, and gives every platform the same features. Not a web page in a desktop shell, not a crippled mobile port. The same app, working the same way, wherever you open it.

That definition matters because the marketing version stops at "available on." Availability is cheap. A company can wrap its website in a desktop window and ship a thin mobile app in a weekend, and technically it now runs everywhere. What you feel a month later is the gap between running and running well: the mobile version that lags, the desktop app that eats a gigabyte of memory, the feature that exists on web but not on your phone.

Three things separate the real thing from the checkbox. Native performance, so each platform feels like it belongs there. Sync you can trust, so switching devices mid-thought is invisible. And feature parity, so you never learn the phrase "you can only do that on desktop."

Picture the test that actually exposes an app: you draft a meeting agenda on the web, add three action items on your phone during the walk to the room, then reorder everything on a tablet once the meeting starts. If the app is truly cross-platform, none of those switches register as events. If it is not, one of them costs you a reload, a lost edit, or a formatting mess you fix by hand. The difference never shows up on a feature comparison page, because every app claims all three platforms. It shows up in the seconds you lose during a handoff, every day, for as long as you use the thing.

![The four layers of a cross-platform note app: availability on all devices, native performance, reliable offline sync, and keeping notes accurate](/blog/cross-platform-note-taking-app/cross-platform-layers.svg)

## Why most cross-platform note apps fail when you switch devices

The failures cluster into a few recognizable shapes. Knowing them makes the shopping much faster, because you can spot each one from the pricing page.

The first is the wrapper problem. Notion and Obsidian both ship their desktop apps on [Electron](https://www.electronjs.org/), which bundles a full Chromium browser with every install. That is why the desktop apps can feel heavy and why the mobile experience is a separate build with its own quirks. Electron is a reasonable engineering choice for shipping fast, but it means "cross-platform" is really "one web app in several costumes," and the seams show most on the device with the least memory to spare: your phone.

The alternative is a genuinely native stack. Scribelet is built on [React Native](https://reactnative.dev/), which compiles to real iOS and Android UI components instead of rendering a bundled browser, and runs the same core on the web. The practical result is that the phone app is a first-class citizen rather than a port, so a long note scrolls smoothly on a three-year-old Android the same way it does on a new laptop.

The second is the second-class mobile port. An app can be genuinely good on the desktop and merely tolerable on mobile, which is a problem if mobile is where you capture. Obsidian is the classic case: the desktop app is beloved, the mobile app works, and reliable syncing between them runs through Obsidian Sync, a [paid add-on](https://obsidian.md/sync) on top of the free app. Plenty of people go looking for [an Obsidian alternative](https://scribelet.app/blog/obsidian-alternative) for exactly this reason.

Then there is platform lock-in dressed up as simplicity. Apple Notes is fast, native, and free, and it does not exist on Android. The moment one device falls outside the walled garden, "cross-platform" is off the table. Google Keep goes the other way: it runs on Android, iOS, and the web, but a flat wall of colored cards is all you get, which is why so many people go looking for [a Google Keep alternative](https://scribelet.app/blog/google-keep-alternative) once the wall fills up.

The last failure is the sync itself, the least visible one and the one that costs you actual work. An app that is cloud-first with weak offline support will happily let you edit the same note on two devices and then pick a winner for you, silently discarding the other version. A notes app with offline support worth trusting does the opposite: it queues your edits locally, syncs when you reconnect, and detects conflicts instead of guessing. Students feel this acutely, moving between a shared campus computer and a personal laptop, which is why our pick of [a note-taking app for students](https://scribelet.app/blog/best-note-taking-app-for-students) weighs device reach and safe sync into every recommendation.

## The 11 best cross-platform note-taking apps at a glance

Every app below runs on more than one platform. What separates them is *how well*: whether the mobile build is native or a port, whether sync is free or a paid add-on, and whether offline editing is safe. Start with the table, then drop to the app that fits how you work.

| App | Platforms | Native or wrapper | Free sync | Best for |
|---|---|---|---|---|
| **OneNote** | Win, Mac, iOS, Android, Web | Mostly native | Yes (OneDrive) | Free all-rounder, handwriting |
| **Obsidian** | Win, Mac, Linux, iOS, Android | Electron desktop | No (Sync is paid) | Power users, local Markdown |
| **Notion** | Win, Mac, iOS, Android, Web | Electron, web-based | Yes | Workspace, databases |
| **Joplin** | Win, Mac, Linux, iOS, Android | Native-ish, open source | Yes (bring your own) | Open source, encryption |
| **Standard Notes** | Win, Mac, Linux, iOS, Android, Web | Cross-platform | Yes | End-to-end encryption |
| **Simplenote** | Win, Mac, Linux, iOS, Android, Web | Lightweight native | Yes | Fast, free, plain text |
| **Evernote** | Win, Mac, iOS, Android, Web | Native, heavy | Limited on free | Legacy libraries |
| **Apple Notes** | Apple devices + iCloud web | Native (Apple only) | Yes (iCloud) | All-Apple households |
| **Google Keep** | Android, iOS, Web | Web-based | Yes | Quick capture |
| **Bear** | Apple devices only | Native (Apple only) | Yes (paid) | Markdown on Apple |
| **Scribelet** | iOS, Android, Web | Native (React Native) | Yes | Native mobile, kept-accurate notes |

### OneNote

**Pick it if** you want the strongest free cross-platform option and you write by hand. OneNote runs on Windows, Mac, iOS, Android, and the web, syncs through OneDrive at no cost, and its infinite canvas plus stylus support make it the default recommendation on almost every forum thread and in Google's own AI overview for this query. Offline works, and 5 GB of free OneDrive storage covers most personal use.

**Skip it if** you want plain Markdown files you own, or a fast, minimal editor. OneNote's notebook-section-page hierarchy is heavier than a plain list, its notes live in Microsoft's format rather than portable text, and the Mac and mobile builds trail the Windows one. If OneNote is the app you are leaving, we sorted [the OneNote alternatives by why you are leaving](https://scribelet.app/blog/onenote-alternative).

### Obsidian

**Pick it if** you want a local-first Markdown vault, wikilinks, and a graph view, and you mostly work on desktop. Obsidian stores notes as plain `.md` files on your machine, so you own them outright, and it is free for personal use across every major OS.

**Skip it if** mobile is where you capture and you would rather not pay to sync. Reliable syncing between the loved desktop app and the workable mobile app runs through Obsidian Sync, a paid add-on, and the mobile build is a step behind the desktop one. That specific gap, the phone half plus paying to close it, is why so many people shop for an alternative.

### Notion

**Pick it if** your notes are really a workspace: databases, project boards, wikis, and shared pages. Notion runs everywhere, syncs for free, and its flexible page model is unmatched for structured team content. It also writes with AI on request.

**Skip it if** you need dependable offline access or a fast mobile capture. Notion is cloud-first: offline support is limited and historically flaky, and the Electron desktop app plus web-based mobile can feel heavy. For a full head-to-head on the two biggest names here, we wrote [an honest Notion vs Obsidian comparison](https://scribelet.app/blog/notion-vs-obsidian) that goes past the feature grid.

### Joplin

**Pick it if** you want an open-source, Markdown-based app you can sync through your own cloud (Dropbox, OneDrive, or a self-hosted server) with end-to-end encryption. Joplin runs on every desktop and mobile platform and costs nothing.

**Skip it if** you want polish out of the box. Sync setup is more hands-on than a hosted service, and the interface is functional rather than refined. It is the tinkerer's pick, and a good one.

### Standard Notes

**Pick it if** encryption is the point. Standard Notes is end-to-end encrypted by default, runs on every desktop, mobile, and web platform, and syncs across all of them on the free tier. For anyone who wants notes that are private first and cross-platform second, it is the cleanest option on this list.

**Skip it if** you want rich formatting, inline images, and a fast writing surface without paying. The free editor is deliberately plain, and the features that make it feel like a modern notes app sit behind a subscription.

### Simplenote

**Pick it if** you want the fastest, lightest, genuinely-free way to sync plain-text notes everywhere. Simplenote runs on all desktop and mobile platforms plus web, syncs instantly, and never asks for money. For quick text that has to be on every device in a second, nothing here beats it.

**Skip it if** you need formatting, attachments, or any structure beyond tags. Simplenote is plain text and proud of it, which is the feature and the limit at once.

### Evernote

**Pick it if** you already have years of clippings and notebooks in it and you are not ready to move. Evernote still runs on Windows, Mac, iOS, Android, and the web, and its web clipper and search remain strong.

**Skip it if** you are starting fresh. The free tier now limits devices and syncing, the app is heavy, and pricing has climbed. Most people evaluating it today are actually looking for the exit, which is why we mapped [the Evernote alternatives worth switching to](https://scribelet.app/blog/evernote-alternative).

### Apple Notes

**Pick it if** every device you own is Apple. On a Mac-plus-iPhone-plus-iPad setup, Apple Notes is fast, native, free, and syncs invisibly through iCloud, and it is hard to beat inside that garden.

**Skip it if** a single Windows laptop or Android phone is anywhere in your life. Apple Notes does not exist on Android, and the iCloud web version is a fallback, not a real app. The moment one device sits outside the walled garden, it fails the cross-platform test by definition. If you are weighing the jump from Apple Notes to a portable vault, our [Obsidian vs Apple Notes](https://scribelet.app/blog/obsidian-vs-apple-notes) comparison covers that exact trade.

### Google Keep

**Pick it if** you want frictionless quick capture, checklists, and voice notes synced across Android, iOS, and the web for free. As a capture inbox it is excellent.

**Skip it if** you are building anything you will keep. There are no real documents, no linking, and no structure beyond colored cards, so it fills up and stops scaling, at which point people go looking for something with more depth.

### Bear

**Pick it if** you live on Apple hardware and want a beautiful Markdown editor with tags and a calm writing surface. Bear is a genuine pleasure to write in.

**Skip it if** you need Windows or Android. Like Apple Notes, Bear is Apple-only, so it is a cross-platform app only within Apple's platforms, and its sync sits behind a subscription.

### Scribelet

**Pick it if** you want a note app that is native on iOS and Android, shares one codebase with the web, and does something none of the others do: keeps your notes accurate over time. Sync is free, offline editing queues locally and reconciles on reconnect, and wikilinks plus a backlinks panel work the same on every platform.

**Skip it if** you need handwriting or a mature template gallery today. Scribelet is typed-note-first and younger than OneNote or Evernote, so a stylus-heavy workflow is better served elsewhere for now.

**Ready to feel the difference?** Start a note on your phone and finish it on the web. Scribelet shares one codebase across iOS, Android, and web, so the handoff has no seam to catch on. [Get set up in five minutes.](https://scribelet.app/learn/getting-started/quick-start)

## What note-taking app syncs across devices without losing edits?

Almost all of them sync. The question that actually matters is what happens when two devices edit the same note, or when you write offline and reconnect. That is where cross-platform apps quietly differ, and it is the column no roundup fills in. Here is how the genuinely cross-platform picks handle the hard part.

| App | How sync works | Offline editing | Conflict handling |
|---|---|---|---|
| **OneNote** | OneDrive cloud sync | Solid offline, syncs on reconnect | Merges, can create duplicate pages |
| **Obsidian** | Local files + paid Obsidian Sync | Offline-first (files are local) | Sync add-on flags conflicts |
| **Notion** | Cloud-first | Limited; recent edits can lag | Last write can win silently |
| **Joplin** | Your own cloud, encrypted | Offline-first | Creates conflict copies |
| **Standard Notes** | Encrypted cloud sync | Offline, syncs on reconnect | Conflict versions preserved |
| **Simplenote** | Instant cloud sync | Basic offline | Keeps version history |
| **Scribelet** | Cloud sync, native clients | Offline queue, auto-save | Detects conflicts, no silent overwrite |

The pattern is worth internalizing before you commit to anything. The local-first tools (Obsidian, Joplin) are safe offline because the file already lives on your device. The cloud-first tools (Notion, Google Keep) are the ones to test carefully: turn on airplane mode, edit a note, reconnect, and confirm nothing was lost or silently overwritten. An app that picks a winner for you without saying so is the one that will eventually cost you a paragraph you never knew you wrote.

## The part every cross-platform list skips: does your note stay accurate everywhere?

Sync solves one problem and hides another. Once a note is on all your devices, we treat it as done. But a note that is wrong on your laptop is now wrong on your phone and your tablet too. You did not fix the information. You replicated it, faithfully, to every screen you own.

This is the layer the roundups never reach, because it has nothing to do with which operating systems an app supports. It is about what happens to the content over time. The React setup you documented last spring, the pricing you noted from a competitor, the API endpoint you saved for a side project: all of it looked right when you wrote it, and some of it has [quietly gone stale](https://scribelet.app/blog/knowledge-decay) since. Perfect sync makes the stale version more available, not less.

The tools built to fight this treat maintenance as a feature, not an afterthought. Scribelet runs [background verification](https://scribelet.app/learn/ai/ai-verification) on a schedule you set: it searches the web, compares what it finds to what you wrote, and shows you a diff, green for new information and red for what no longer holds. You review, accept or dismiss, and the corrected note syncs everywhere, the same way the wrong one used to.

A concrete version: you keep a note documenting a payment provider's webhook fields, written cleanly six months ago and synced to every device. The provider deprecates one field and renames another. Your note keeps looking authoritative on all five screens until the day you build against it and hit an error. A verification pass catches the change while the note is idle, hands you a diff, and the fix propagates before it costs you an afternoon.

The point is not that sync is unimportant. It is that a cross-platform note app that only moves your notes around, without any sense of whether they are still true, has solved the easy half of the problem and left you the hard half.

## How to choose a cross-platform note app

Once you stop grading on availability alone, the decision gets simpler. Run any candidate through these six questions and the field narrows fast.

1. **Is it native, or a wrapper?** Check whether the desktop app is Electron and whether mobile is a real build. Open the mobile app and scroll a long note. Sluggishness now is sluggishness forever.
2. **Can it sync notes across devices without you thinking about it?** Free and built in beats a paid add-on. Test the handoff before you commit, on your actual devices.
3. **Does offline actually work?** Turn on airplane mode, edit a note, reconnect, and confirm nothing was lost or silently overwritten.
4. **Is there feature parity?** If a capability lives on desktop only, assume you will need it on your phone at the worst possible moment.
5. **Does it connect your notes?** Wikilinks and backlinks turn a pile of notes into something you can navigate. Scribelet builds these with [wikilinks and a backlinks panel](https://scribelet.app/learn/notes/wikilinks-backlinks) on every platform.
6. **Does it keep your notes accurate?** This is the tiebreaker almost nobody offers. If two apps sync equally well, the one that also flags stale information is the one worth keeping.

Weight the questions by how you work. If you capture on mobile and refine on desktop, questions one through three decide it. If you are building a knowledge base you will lean on for years, questions five and six matter more than any sync benchmark. If you care most about owning portable files, we also compared [the markdown-first note-taking apps](https://scribelet.app/blog/markdown-note-taking-apps) that keep your notes in plain text.

## The bar is higher than "runs everywhere"

Every note app in this comparison can technically follow you from phone to laptop to tablet. That was the hard problem a decade ago and it is table stakes now. The apps still competing on it are competing on the wrong thing.

The bar that matters is whether the handoff is invisible, whether offline is safe, and whether the note you carry across five devices is still worth carrying. Get those right and cross-platform stops being a feature you shop for and becomes something you never think about again, which is the entire point. [Start writing on every device you own, and let AI keep the notes accurate. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>note-taking</category>
            <category>cross-platform</category>
            <category>mobile</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Zettelkasten with AI: the slip-box without the busywork]]></title>
            <link>https://scribelet.app/blog/zettelkasten-with-ai</link>
            <guid isPermaLink="false">https://scribelet.app/blog/zettelkasten-with-ai</guid>
            <pubDate>Sat, 04 Jul 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Most zettelkasten systems die when the manual linking gets tedious. See what changes when AI links your atomic notes and flags what's gone stale. Try it free.]]></description>
            <content:encoded><![CDATA[
You set one up once. A clean Obsidian vault, a folder for atomic notes, a plugin to mint unique IDs, maybe a template with the three note types laid out. For a week or two it felt like your thinking finally had a home. Then the linking got tedious, the daily upkeep slipped, and the vault turned into a drawer of orphan notes you never open.

That arc is the most common thing that happens to a zettelkasten. The method promises a connected web of ideas that generates insight. What it hands most people is a second job, and the part that quietly kills it is not the writing. It is the manual maintenance the method was built to require.

This piece is for anyone who admires the idea of a zettelkasten but has watched their own system stall. We'll cover what the method actually asks of you, why so many slip-boxes die in the first month, which parts of it were only ever a workaround for paper, and what changes when AI does the linking and the upkeep instead of you.

## What is a zettelkasten?

A zettelkasten is a note-taking system where every idea lives on its own small note, and those notes link to each other to form a network. The German word means "slip-box." The sociologist Niklas Luhmann built the most famous one, filling roughly 90,000 paper slips over several decades and crediting the system for dozens of books.

The mechanics of zettelkasten note-taking are simple to describe. You write in atomic notes, [one idea per note](https://scribelet.app/blog/atomic-notes), in your own words. You give each note a way to be referenced. Then you link it to the notes it relates to, so structure emerges from the connections rather than from a folder hierarchy you decided in advance.

Most modern practitioners also sort notes into three rough types, a framing popularized by Sönke Ahrens in [*How to Take Smart Notes*](https://takesmartnotes.com/): fleeting notes you jot in the moment, literature notes you take while reading a source, and permanent notes that capture a developed thought you want to keep. The permanent notes are the ones that compound. We walk that workflow step by step, and the point where it quietly stops paying out, in [how to take smart notes](https://scribelet.app/blog/how-to-take-smart-notes). Their more fluid cousin, [the evergreen note](https://scribelet.app/blog/evergreen-notes), makes the same promise and breaks it the same way. They're also the ones that quietly go wrong, which is where most of this article is headed.

What makes the method different from a folder of documents is emergence. You never design the outline. You write small, connect honestly, and after a few hundred notes a shape appears that you couldn't have planned, because it reflects how your ideas actually relate rather than how you guessed they would. That payoff is real. It just sits on the far side of a lot of manual effort that most people never get through.

It's also what separates a slip-box from [the commonplace book, its older cousin](https://scribelet.app/blog/commonplace-book): a commonplace book collects other people's words worth keeping, while a zettelkasten asks you to develop them into ideas of your own.

## Why most zettelkasten systems die in three weeks

Search the note-taking forums and you'll find the same confession on repeat: the system looked beautiful and then became a chore. One of the pages that ranks for the method is literally an Obsidian forum thread arguing that zettelkasten is too complex for most people. That's the honest signal underneath the tutorials.

The failure isn't laziness. It's that the method front-loads work that never ends. Every new note needs an ID, and every note needs you to remember what it relates to and go create the links by hand. Every so often you're supposed to review the whole thing to keep it coherent. Do that across 40 notes and it's a pleasant hobby. Do it across 400 and it's unpaid labor.

Then there's the slower failure, the one nobody warns you about. A permanent note you wrote 18 months ago can still be linked, still be tagged, still look authoritative, and be flatly wrong. The link works. The idea inside no longer holds. This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and a slip-box has no defense against it. Luhmann's notes referenced sociological theory that shifted over decades. Yours probably reference an API, a paper, or a market that shifts over months.

> Curious what a maintenance-first approach looks like in practice? Our writeup on the [living notes method](https://scribelet.app/blog/living-notes-method) covers the phase every note-taking system skips.

So a zettelkasten dies two ways. It dies fast when the manual linking exhausts you, and it dies slow when the notes that survived stop being true. That slow death is [the step PARA leaves out](https://scribelet.app/blog/para-method-with-ai) too: every organizing method files a note without ever checking whether it still holds. Both problems come from the same root: the method assumes a human will do all the connecting and all the checking, forever.

## The part of the method that was always a workaround

Here's the reframe. Luhmann's most-copied techniques were not the point of a zettelkasten. They were compensations for the limits of paper.

Unique numeric IDs existed because a paper slip can't be searched. If you wanted to find a note again, or point one note at another, you needed an addressing scheme, so Luhmann invented an intricate one.

Manual links existed because index cards can't discover their own relationships. A card sits in a box, inert, until a person physically threads a connection between it and another card. The daily discipline of reviewing and re-filing existed because paper has no way to resurface a relevant old note at the right moment.

Strip those away and what remains is the actual insight, the thing worth keeping: atomic notes in your own words, connected by meaning, so that structure emerges instead of being imposed. That principle is excellent. The [Wikipedia entry on the method](https://en.wikipedia.org/wiki/Zettelkasten) and the community reference at [zettelkasten.de](https://zettelkasten.de/introduction/) both center it, and it holds up.

The mechanics around it were a tax Luhmann had to pay because he worked with cardboard. You don't. A digital system can search itself, connect itself, and resurface its own notes. The question is whether your tool actually does that work, or just hands you a nicer-looking box and the same manual job.

## The zettelkasten method with AI doing the linking

This is where an AI-native notebook changes the math. The single most tedious part of the practice, finding and creating the links between notes, is exactly the part a machine is good at.

| The zettelkasten job | On paper or manual Obsidian | With AI doing the work |
|---|---|---|
| Addressing a note | Unique IDs you assign by hand | Full-text and semantic search, no IDs |
| Linking | You find and create every link | Auto-linker suggests connections by meaning |
| Resurfacing old notes | Scheduled manual review | Daily digest and backlinks bring them back |
| Keeping notes true | Nothing catches decay | Background verification flags stale claims |

![Diagram contrasting a manual zettelkasten, where a person draws every link between index cards, with an AI-assisted one where the auto-linker suggests connections between notes](/blog/zettelkasten-with-ai/manual-vs-ai-linking.svg)

Write an atomic note in Scribelet and the auto-linker reads it for meaning, then surfaces the existing notes it relates to and suggests [wikilinks](https://scribelet.app/learn/notes/wikilinks-backlinks) you can accept or ignore. You still decide what connects to what. You just stop doing the manual search that made people quit. A backlinks panel shows every note that points at the one you're reading, so the web is visible instead of imagined.

The connections don't stop at links you approve. Scribelet builds a per-desk [knowledge graph](https://scribelet.app/learn/ai/ai-memory) from the facts and relationships in your notes, mapping how people, projects, and terms relate. That graph is the modern version of Luhmann's numbered index, except you never number anything. Ask a question and the AI chat searches across your slip-box and answers from your own notes with citations, rather than making you re-read 30 cards to reconstruct a thread.

Consider the common case of the abandoned import. Someone moves 300 old notes into a fresh vault, fully intending to link them, and never does, because linking 300 notes by hand is a weekend nobody has. An auto-linker builds the web they were never going to build. The zettelkasten they wanted becomes the zettelkasten they have.

> **Want to see the auto-linker and knowledge graph on your own notes?** [Start free](https://scribelet.app/learn/getting-started/quick-start) and connect your first few notes in a couple of minutes.

## Keeping a zettelkasten accurate, not just connected

Linking solves half the problem. It does nothing for truth.

Picture [a literature note](https://scribelet.app/blog/literature-notes) in a research slip-box. It summarizes a study cleanly and links to three permanent notes that build on the finding. A year later the study is corrected, or retracted outright. Paper retractions have grown roughly tenfold since 2000, according to [Retraction Watch](https://retractionwatch.com/), and the note has no idea. The link still resolves. The permanent notes downstream still cite it. You find out during peer review, after you've built on a foundation that cracked.

The developer version is faster and just as quiet. A permanent note captures a framework pattern that was correct when you wrote it. Two releases later the pattern is deprecated and throws errors. The note still links neatly into your engineering wiki. The next person who follows it loses a morning to it.

Scribelet's [background verification](https://scribelet.app/learn/ai/ai-verification) is built for exactly this gap. Background agents search the web on a schedule you set, compare what they find against what your notes claim, and surface any discrepancy as a diff: green for new information, red for what's outdated, with a source link on every change.

![Background verification diff on a permanent note, showing an outdated library default highlighted in red and the current default in green with a source link](/blog/zettelkasten-with-ai/verification-diff.svg)

You review it in seconds, accept or dismiss, and the note stays trustworthy. The connecting is automated. The checking is automated. Your judgment stays in the loop where it belongs.

There's a third case that matters most to anyone billing for their thinking. A consultant pulls up a permanent note on a market they analyzed last quarter and reuses it in a new engagement. Two competitors have repriced since, and one shipped a feature that didn't exist when the note was written. Presenting it as current is a professional risk that compounds every time the note gets reused. Verification catches the drift before it reaches a client deck.

Because verification means your notes pass through an AI model, you get a choice about which one. Scribelet's AI works out of the box, and if you want provider control you can [bring your own key](https://scribelet.app/blog/byok-ai) from OpenAI, Anthropic, or Google. Your key is encrypted at rest, and your notes go to the provider you picked rather than one a vendor chose for you. That's the optional sovereignty path, not a setup step.

## A zettelkasten example, start to finish

It helps to watch one note move through the whole loop, because the abstract version hides where the effort used to go.

You read a post about rate limiting and jot a fleeting note: "token bucket vs. leaky bucket, revisit for our API." Later you turn it into a permanent note in your own words, one idea, a few sentences on when each algorithm fits.

On a classic slip-box, this is where the labor starts. You'd assign the note an ID, then scan your other notes to remember that you already wrote something about API gateway design and something else about a client's traffic spikes, then create both links by hand.

In an AI-native version, you write the permanent note and stop. The auto-linker surfaces the gateway note and the traffic-spike note as suggested wikilinks; you accept both in two taps. The knowledge graph now knows this note relates to that client and that project, so a later question about their infrastructure pulls it in without you searching. Weeks on, a background check notices the rate-limiting library you referenced changed its default in a new release and shows you a diff. Same method Luhmann used. None of the filing he had to do.

That's the whole pitch in one note: the principle intact, the busywork gone.

![Flow of a single note from a quick fleeting capture to an atomic permanent note, then AI-suggested links, then a background verification check that keeps it current over time](/blog/zettelkasten-with-ai/note-lifecycle.svg)

## How to start a zettelkasten in 2026

You don't need Luhmann's numbering scheme or a stack of plugins. The method reduces to a short loop, and the tool can carry most of it.

1. Write atomic notes. One idea per note, in your own words. Keep them short enough to reuse.
2. Link as you go, or let the auto-linker suggest connections after you write. Accept the ones that fit.
3. Let the web resurface itself. A daily digest and backlinks panel bring related notes back to you instead of you hunting for them.
4. Verify what matters. Put your source-heavy permanent notes on a background check schedule so decay gets caught before you act on it.

One honest tradeoff worth naming: AI linking suggests, it doesn't decide. It will occasionally propose a connection that doesn't belong, and you'll wave it off. That's the right division of labor. The machine handles the search across your whole slip-box; you keep the judgment about what actually relates. The thinking stays yours, which was always the point of a zettelkasten in the first place.

If you're running an Obsidian zettelkasten today, none of this asks you to abandon the concept. It asks you to stop paying the paper tax that Obsidian, faithful to the original method, still leaves on your desk. Our take on the [best Obsidian alternative](https://scribelet.app/blog/obsidian-alternative) goes deeper on that switch if you're weighing it.

## The slip-box, finally worth the effort

Luhmann built a machine out of paper because paper was what he had. The genius was the principle: small notes, connected by meaning, structure emerging from the network. The busywork of IDs, manual links, and endless review was never the insight. It was the cost of running that principle on cardboard, and it's the reason your version stalled in week three.

A zettelkasten worth keeping is one where the connecting and the checking happen without you becoming their full-time operator. [Start a slip-box that links and verifies itself. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>zettelkasten</category>
            <category>note-taking</category>
            <category>pkm</category>
            <category>ai</category>
        </item>
        <item>
            <title><![CDATA[Obsidian vs Notion: an honest 2026 comparison]]></title>
            <link>https://scribelet.app/blog/notion-vs-obsidian</link>
            <guid isPermaLink="false">https://scribelet.app/blog/notion-vs-obsidian</guid>
            <pubDate>Fri, 26 Jun 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Obsidian vs Notion in 2026, round by round: storage, speed, Obsidian's new native Bases, Notion AI's credit pricing, and migration. Plus the one thing both ignore. Read on.]]></description>
            <content:encoded><![CDATA[
You keep your project tracker in Notion, your actual thinking in Obsidian, and a third pile of half-formed ideas in whatever was open on your phone. Every few months you try to consolidate, lose a weekend to it, and go back to running both.

That split is the honest state of the Notion vs Obsidian debate. Most comparisons hand you a clean rule: Obsidian for private local notes, Notion for databases and teams. The rule is mostly right, and this guide gets to why, dimension by dimension, with a clear winner called on each.

But the rule answers the wrong question. It tells you which tool fits your workflow today. It says nothing about which notes you will still trust a year from now, after the APIs you documented have changed and the sources you cited have moved.

So this is a round-by-round comparison of Obsidian and Notion: who wins each dimension, what each one actually costs, how to move your notes from one to the other, and the single dimension neither of them measures.

_Updated November 2026. Two things shifted this year and both change the math below: Obsidian's Bases is now a built-in core feature, so Obsidian finally has native database-style views, and Notion AI moved from a flat per-seat add-on to credit-metered usage bundled into the paid plans. Both are reflected in the rounds and the pricing table._

## Obsidian vs Notion at a glance

Notion is a cloud database that doubles as a note app, best for teams, structured data, and all-in-one workspaces. Obsidian is a local-first Markdown editor, best for private, fast, deeply linked personal notes. The honest split: Notion for collaboration and databases, Obsidian for ownership and thinking.

| Dimension | Notion | Obsidian | Winner |
|---|---|---|---|
| Where notes live | Cloud database on Notion's servers | Local Markdown files on your device | Obsidian |
| File format | Blocks, exportable to Markdown | Plain Markdown, yours by default | Obsidian |
| Speed and offline | Needs a connection; slows on big databases | Instant, offline-first | Obsidian |
| Databases and structured data | Relations, boards, calendars, filtered views | Native Bases views, no true relations | Notion |
| Linking and graph | Backlinks and database relations | Wikilinks plus an interactive graph | Tie |
| Collaboration | Real-time, built in | Paid sync or third-party services | Notion |
| Built-in AI | Notion AI, bundled but credit-metered | None native; community plugins | Depends |
| Mobile and cross-platform | iOS, Android, web, desktop | Desktop and mobile as separate apps | Notion |
| Plugins and extensibility | ~200 integrations | 2,700+ community plugins | Obsidian |
| Pricing | Free plan; paid tiers per seat | Free for personal use; paid add-ons | Depends |
| Keeping notes accurate over time | None (manual) | None (manual) | Neither |

Notice the last row. Every comparison covers the others. Almost none covers that one, and it is the row that decides whether your notes are an asset or a liability. If you have watched your own notes drift out of date without noticing, our guide to [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why it happens to everyone, not just disorganized people.

## The real difference: a database vs a folder of files

Most feature-by-feature debates miss the design choice underneath everything else, and it is the choice that decides every round below.

Notion's source of truth is a database living on Notion's servers. The interface is the door to your data, and for most practical purposes it is the only door. That is what makes Notion's databases, relations, and shared views possible, and it is also why exporting a large Notion workspace can feel like moving house.

Obsidian's source of truth is a folder of plain Markdown files on your own machine. The [app sits on top of that folder](https://help.obsidian.md/getting-started) and gives you ways to link, search, and visualize the files. A note can be read outside the app, backed up like any other folder, and opened in twenty years by anything that reads text.

Everything downstream follows from this. Notion trades ownership for collaboration and structure. Obsidian trades convenience for control. Neither choice is wrong; they are built for different fears.

![Side-by-side diagram contrasting Notion's cloud database, reached only through its app, with Obsidian's local Markdown folder that the app sits on top of](/blog/notion-vs-obsidian/database-vs-folder.svg)

## Round by round: who wins each dimension

The at-a-glance table calls the winners. Here is the reasoning behind each one, so you can weight the rounds that matter to you and ignore the ones that do not.

### Storage and ownership: Obsidian

Obsidian notes are plain text on your disk. They open without the app, survive the company folding, and back up like any other folder. Notion holds everything in a proprietary cloud database you reach through the interface. For anyone whose fear is lock-in or longevity, this round is not close.

### Speed and offline: Obsidian

Obsidian opens instantly, searches without lag, and works on a plane. Notion needs a connection for most things and gets visibly slower as a workspace grows into thousands of blocks. If you capture fast and often, the difference is felt daily.

### Databases and structured data: Notion

This is Notion's home turf, and in 2026 it finally got a real challenger. Turn a Notion page into a table, a board, a calendar, or a gallery, and filter the same data a dozen ways. Relational databases connect projects to clients to deliverables, and that relational layer is still Notion's alone.

What changed is the other side. Obsidian's Bases is now a built-in core feature, not a community plugin, so a folder of notes can be shown as a filtered table, cards, a kanban board, or a map, all driven by the properties already in your Markdown files. That closes most of the everyday-view gap that used to make this round a blowout. What Bases does not do is relations: it queries and displays your own notes, but it does not wire projects to clients to deliverables the way a Notion relation does. So Notion still wins the round, by a good deal less than it did a year ago.

### Linking and organization: tie

Both do bidirectional links well. Notion links pages and database rows; Obsidian links files and renders an interactive graph. Obsidian's graph is prettier and its wikilinks are faster to write; Notion's relations carry structured meaning a backlink cannot. Which one wins depends on whether you think in connected notes or in structured records.

### Collaboration: Notion

Real-time multi-user editing is built into Notion, not bolted on. A five-person team can run its roadmap, meeting notes, and customer feedback in one workspace, each view filtered to what that person needs, and a non-technical teammate is productive in an afternoon. Obsidian is a solo tool unless you pay for sync and add third-party services, and even then it is not built for concurrent editing.

### Built-in AI: depends

[Notion AI](https://www.notion.com/help/notion-ai-faqs) is a capable writing and summarizing assistant, and in 2026 it is folded into the paid plans rather than sold as a flat per-seat add-on. The catch is metering: the heavier features, agents and AI meeting notes, now draw on Notion credits, and the Free and Plus tiers get little more than a trial, so steady AI use effectively starts at the Business plan. It is also reactive by design: you prompt it, it answers. Obsidian ships no native AI, but its community plugins and external agents let you wire up almost anything, including local models. If you want AI that works out of the box, Notion wins; if you want to choose your own model and route, Obsidian's openness wins. The wider set of [AI options for Obsidian](https://scribelet.app/blog/obsidian-ai) is worth a look before you decide this round.

### Mobile and cross-platform: Notion

Notion runs the same workspace across iOS, Android, web, and desktop, syncing for free. Obsidian has good mobile apps, but syncing them means the paid Obsidian Sync add-on or a DIY setup. If running your notes across a phone, tablet, and laptop is the real requirement, it is worth weighing both against [a note app that works well on every device](https://scribelet.app/blog/cross-platform-note-taking-app) without a sync surcharge.

### Plugins and extensibility: Obsidian

Obsidian's community catalog runs past 2,700 plugins, from kanban boards to spaced repetition, which means the app can become almost anything, including a rough approximation of Notion. If you run Obsidian, it helps to know [which of those plugins are actually worth installing](https://scribelet.app/blog/best-obsidian-plugins) rather than adding all of them. Notion has roughly 200 integrations and a more closed model. Obsidian is one of several apps built on that plain-text, extensible idea; we weigh the wider field in our guide to [markdown note apps compared](https://scribelet.app/blog/markdown-note-taking-apps).

### Learning curve: split

Notion is easier to start. You type a slash, pick from a menu, and have a usable page in minutes. Obsidian is easier to master, because a folder of Markdown files never hides how it works. The common failure mode runs the other way, though: Notion tempts you into engineering an elaborate system, while Obsidian's blank vault gives you no opinion about what to build.

## What each one actually costs

Pricing is where the AI overview and most comparisons go vague. Here are the real shapes, verified in November 2026. Both companies adjust plans, so confirm the exact figure before you commit a team.

| Plan | Notion | Obsidian |
|---|---|---|
| Free tier | Full personal use, generous limits | Full personal use, no limits |
| Individual paid | Plus, about $10 per user per month billed annually | None needed; personal use is free |
| Team or business | Business, about $20 per user per month billed annually | Commercial license, $50 per user per year for work use |
| AI | Bundled into the paid plans but metered by Notion credits; Free and Plus get only a trial | None native; you supply your own via plugins |
| Sync across devices | Included in every plan | Obsidian Sync, about $4 per month billed annually |
| Publishing to the web | Public pages included | Obsidian Publish, about $8 per month per site |

The honest read: for a solo user, Obsidian is free forever and Notion is free until you want AI or history. For a team, Notion's per-seat cost buys collaboration Obsidian cannot match at any price. Neither bill includes the cost that actually bites, which is the time you spend later finding out a note went stale.

## Switching between them: the migration paths

Nobody mentions the exit until you need it, so here is the reality in both directions. Packing is the easy part in any direction, and it is worth being honest about [what you are actually moving](https://scribelet.app/blog/evernote-alternative): a years-old archive is rarely as intact as you remember it.

| Moving | How it goes | What breaks |
|---|---|---|
| Notion to Obsidian | Export the workspace as Markdown and CSV, then open the folder as a vault | Databases flatten into files plus CSVs; relations, rollups, and filtered views do not survive; internal links need cleanup |
| Obsidian to Notion | Import the Markdown files into Notion pages | Wikilinks and the graph do not carry; nested folders become nested pages; plugin-rendered content is lost |
| Either to a fresh start | Both export to plain Markdown, the portable format | Formatting quirks and embeds; the notes themselves travel fine |

The asymmetry is the point. Obsidian exports cleanly because the files were always plain text. Notion exports lose the database structure that made Notion worth using, because that structure lived in the cloud, not in the files. Plan your entry with your exit in mind.

## The questions everyone asks

### Can Notion replace Obsidian?

For structured, collaborative work, yes. For a private, offline, plain-text thinking space, no. Notion can hold your notes, but it holds them in a cloud database you do not own, and it is slower for fast capture. People who leave Obsidian for Notion usually miss the speed and the ownership; people who leave Notion for Obsidian usually miss the databases.

### What are the downsides of Obsidian?

You own the maintenance. There is no native AI, sync across devices is a paid add-on or a DIY project, and the blank-vault problem is real: a tool that can be anything gives you no opinion about what it should be. The graph looks beautiful and tells you nothing about whether the notes inside it are still true. One more, quietly: fewer plain-text tools hold that line than used to, and the outliner closest to Obsidian moved its notes into a database in 2026, which we cover in [the file question behind Obsidian vs Logseq](https://scribelet.app/blog/obsidian-vs-logseq).

### Is Notion overkill for personal use?

For most individuals, yes. A solo user rarely needs relational databases to keep a few hundred notes, and the common failure mode is spending more time engineering the system than using it. You can watch this play out in any Notion vs Obsidian thread: someone builds an elaborate second brain with linked databases, and three weeks later admits they are maintaining the scaffolding more than thinking with it. A methodology is not a maintenance plan. The setup is the easy part. Keeping it trustworthy is the part nobody budgets for.

### Does anyone still use Notion?

Yes, in large numbers, especially teams and startups running everything from one workspace. The "everyone is switching to Obsidian" narrative is loud on Reddit and quiet in company wikis. Both tools are growing; they are just growing with different users. The switch stories you see are mostly solo thinkers, not the five-person teams Notion was built for.

## The question neither answers: will you trust these notes next year?

Here is the dimension every Obsidian vs Notion comparison skips. Both tools are exceptional at getting information in and organizing it once it is there. Neither does anything about what happens to that information afterward.

A developer writes a careful guide to a payment API integration. Eight months later the provider deprecates the OAuth scope the guide depends on. The note still looks authoritative in both Notion and Obsidian. The next teammate to follow it spends a morning chasing 401 errors before realizing the doc went stale. The editor was never the problem. The accuracy was.

This is knowledge decay, and it is a property of information, not a failure of discipline. Technical docs decay in weeks, research citations get retracted, competitor data shifts, and links rot. Your vault does not know. Your workspace does not care. As we have argued before, [every note-taking method skips a maintenance phase](https://scribelet.app/blog/living-notes-method) between organizing a note and trusting it.

![Line chart showing a note's accuracy declining steadily over a year without maintenance, while scheduled background verification keeps it near fully accurate](/blog/notion-vs-obsidian/note-accuracy-decay.svg)

Notion's AI does not close this gap, because reactive AI only works when you already suspect something is wrong and think to ask. Obsidian's plugins do not close it either, because they automate capture and formatting, not verification. The honest answer to "Obsidian or Notion" is that for keeping notes accurate over time, the score is zero to zero.

## A third option: ownership plus maintenance

This is where a different kind of tool enters the comparison, and where we are upfront that we built one.

Scribelet starts from Obsidian's ownership instinct and adds the proactive AI Notion only gestures at. Background agents search the web on a schedule you set, compare what they find against what you wrote, and surface the difference as a diff: green for new information, red for what is outdated, with a source link on every change. You review, accept or dismiss, and the note stays current without a manual audit. That is [how background verification works](https://scribelet.app/learn/ai/ai-verification), and it is the maintenance layer neither Notion nor Obsidian offers.

A consultant reopens last quarter's competitor analysis for a new pitch. Two rivals changed pricing; one shipped a feature that did not exist when the note was written. In Notion or Obsidian, nothing flags the drift. With scheduled verification, the changes are waiting as a diff before the meeting, not discovered during it.

The ownership story holds too. You can [bring your own key](https://scribelet.app/blog/byok-ai) and route AI through OpenAI, Anthropic, or Gemini, with the key encrypted at rest, so your notes go to the provider you trust rather than one a vendor chose for you. BYOK is optional; the AI works out of the box. Notes connect with the same wikilinks Obsidian users already know.

The honest tradeoff: Scribelet is not a Notion-style all-in-one with relational databases and kanban boards, and it is not a bare local vault you mold with plugins. It is for people whose notes need to stay accurate, not just organized.

## Obsidian vs Notion vs Scribelet: which should you choose?

The decision comes down to what you are most afraid of losing. Match your situation to the row.

| Your situation | Best fit | Why |
|---|---|---|
| Small team running projects and docs together | Notion | Real-time collaboration and databases are the whole point |
| Solo thinker who wants speed and offline plain text | Obsidian | Ownership and instant local files, no sync surcharge |
| You want database views but not a cloud workspace | Obsidian | Native Bases gives table and kanban views over local files |
| Developer keeping technical notes that go stale fast | Scribelet | Background verification catches the decayed API doc for you |
| Student or researcher juggling sources | Obsidian | Plain-text vault plus the graph, portable across years |
| Anyone whose real pain is not trusting old notes | Scribelet | The maintenance layer neither incumbent has |
| You want AI you prompt for drafts | Notion | Notion AI is reactive and built in |
| You want AI that checks your notes for you | Scribelet | Scheduled diffs, not prompts |

![Two-by-two map plotting Notion, Obsidian, and Scribelet by data ownership and note maintenance, with Scribelet alone in the you-own-it and AI-maintained quadrant](/blog/notion-vs-obsidian/positioning-map.svg)

If you have already decided one of the incumbents is not it, we sorted the [Notion alternatives by what actually broke](https://scribelet.app/blog/notion-alternative) and did the same for the [best Obsidian alternative](https://scribelet.app/blog/obsidian-alternative), because the right replacement is different for speed, for AI fatigue, and for lock-in. And if you landed here on your way out of a heavier all-in-one, we ranked [eleven OneNote alternatives by the reason you are leaving](https://scribelet.app/blog/onenote-alternative) the same way, and weighed [Obsidian and OneNote head to head](https://scribelet.app/blog/obsidian-vs-onenote) for anyone deciding between those two. If your shortlist is [Notion versus OneNote](https://scribelet.app/blog/notion-vs-onenote) instead, that one calls the structure-versus-canvas split round by round.

> **Want to see the difference for yourself?** Start free, run your first verification, and watch what a diff actually catches. The [Pro plan](https://scribelet.app/pricing) is $8/mo or $79/yr when you want the full set.

## The comparison that measures the wrong year

Run the standard Obsidian vs Notion comparison and you get a fair answer to a narrow question: which tool fits the way you work right now. Notion wins on collaboration and databases. Obsidian wins on ownership and speed. Readers whose other contender is the default app on their iPhone can see [how Obsidian stacks up against Apple Notes](https://scribelet.app/blog/obsidian-vs-apple-notes) on the same terms. Both answers are correct, and both miss the part that actually decides whether a knowledge base survives.

A note is only as valuable as it is true. The editor you pick determines how pleasant it is to write; it does nothing about whether what you wrote is still accurate six months later. That is the real failure mode behind every abandoned second brain, and it is the one dimension this debate keeps leaving out.

If staying accurate is what you care about, [start writing with background verification and see your first diff](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>notion-vs-obsidian</category>
            <category>comparison</category>
            <category>note-taking</category>
            <category>personal-knowledge-management</category>
            <category>obsidian</category>
            <category>notion</category>
        </item>
        <item>
            <title><![CDATA[AI fact-checking for notes that stay accurate]]></title>
            <link>https://scribelet.app/blog/ai-fact-checking-for-notes</link>
            <guid isPermaLink="false">https://scribelet.app/blog/ai-fact-checking-for-notes</guid>
            <pubDate>Sun, 07 Jun 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[AI fact-checking for notes works when it checks exact claims, cites current sources, and shows diffs you control. Learn how to verify notes before reuse.]]></description>
            <content:encoded><![CDATA[
You wrote the note because you needed to trust it later.

Maybe it was an API behavior, a market number, a study summary, or the pricing model of a competitor you track. It was true when you saved it. Six months later, you are searching your notes again, and the note still sounds confident. Part of the reason is bare repetition: [a claim you have reread enough times starts to feel true on familiarity alone](/blog/illusory-truth-effect), no new evidence required. Even if you once caught its source getting something wrong, that discount rarely survives the reuse, which is [the Gell-Mann amnesia effect](/blog/gell-mann-amnesia-effect) running inside your own knowledge base.

That is the problem. **AI fact-checking for notes** is useful only if it treats your note as something durable: a claim you may reuse months after the source changed. A chatbot verdict is not enough. A model answer with no source attached is [a claim asserted without evidence, which you are entitled to hold rather than adopt](/blog/hitchens-razor) until the check supplies the proof. A good verification workflow extracts exact claims, checks current sources, shows evidence, and lets you decide what gets written back.

This article explains which notes deserve verification, where AI fact-checking fails, and what a trustworthy note-verification workflow should show before you let it touch your knowledge base.

> Want to see the product version of this? [Try Scribelet's AI verification](https://scribelet.app/learn/ai/ai-verification) on a note that cites an external source, then review the diff before accepting anything.

## What AI fact-checking for notes should do

AI fact-checking for notes is a workflow where software identifies factual claims inside your notes, checks them against current sources, and shows evidence-backed corrections for you to review. That multi-step shape, identify then check then propose, is itself [a prompt chain](https://scribelet.app/blog/prompt-chaining): each step does one job, and you can see its output before it feeds the next. Unlike a chatbot answer, note verification preserves your original note, cites sources, and lets you accept or reject proposed changes. Rejecting a correction out of hand because it contradicts what you already wrote is [the Semmelweis reflex aimed at your own notes](/blog/semmelweis-reflex), which is exactly why a good workflow shows you the evidence instead of asking you to take a verdict on faith.

The distinction matters because notes are not one-off prompts. They accumulate. They connect to projects, clients, citations, decisions, and future work. Standing instructions accumulate the same way, and finding [the lines that stopped earning their place](https://scribelet.app/blog/system-prompt) takes the same kind of check: test the claim rather than trust that it is still true.

When a note goes stale, the mistake does not stay contained inside that note. It travels into the next decision you make with it, and by then [refuting it later costs an order of magnitude more than checking it now](/blog/brandolinis-law).

A useful note checker should do four jobs.

First, it should separate claims from prose. "Stripe supports this billing flow" is a claim. "This felt like the cleanest path" is judgment.

The first one can be checked. The second one needs context, not a web search.

Second, it should retrieve evidence from the right place. The right source for a React API claim is the React documentation or release notes, not a generic blog post. The right source for a pricing claim is the vendor's current pricing page, not an old comparison article.

Third, it should compare evidence against your wording. The output should not be "true" or "false" in isolation. It should explain what changed, what still holds, and what source supports the correction.

Fourth, it should keep you in control. The safest workflow is not silent rewriting. It is a diff: here is what your note says, here is what the source says now, here is the proposed edit, and here is the evidence.

That is why Scribelet uses the term [AI verification](https://scribelet.app/learn/ai/ai-verification) more than fact-checking. Verification is broader. It covers stale facts, source drift, missing caveats, changed APIs, and claims that are too ambiguous to update automatically.

## Why ordinary AI fact checkers do not solve stale notes

Most AI fact-checking tools were built for a different job: review a draft, scan an article, or check an AI-generated answer before it is published. That is useful. It is not the same as keeping a personal knowledge base accurate over time.

The difference is lifecycle.

A draft has a deadline. You check it, publish it, and move on.

A note keeps coming back. You write it in March, cite it in June, link it from a project plan in September, and ask your AI assistant about it in December. If the original source changed in July, a one-time check from March does not protect you.

Microsoft's guidance on [how to fact-check AI](https://www.microsoft.com/en-us/microsoft-365-life-hacks/everyday-ai/how-to-fact-check-ai) points out the everyday failure modes: AI may cite incorrectly, rely on outdated information, or omit context. Those problems get worse when the content being checked is not a disposable answer, but a note you expect to keep using.

Research points in the same direction. Stanford's Cyber Policy Center summarized a study where 15 large language models were tested on more than 6,000 PolitiFact claims. Models with only built-in knowledge performed poorly.

Reasoning and web search helped inconsistently. The strongest gains came from curated evidence supplied through retrieval-augmented generation, with the best setup reaching a macro F1 score of 0.90 compared with 0.27 without curated context.

The lesson for notes is blunt: model confidence is not verification. The quality of the evidence pool matters more than how fluent the answer sounds.

That is why "ask ChatGPT if this note is still accurate" is a weak maintenance system. It might work for a quick sanity check. It will not tell you which claims in 400 notes have drifted, which source changed, or what wording should be updated.

Source-grounded tools raise the floor here, and it is worth knowing exactly where they stop. Google's NotebookLM answers from material you uploaded rather than from model memory, which is a real improvement over a bare chatbot verdict. It still checks the sources you gave it at the moment you gave them, so a notebook assembled in March does not notice that a vendor rewrote a pricing page in July. That limit is why people start looking for [NotebookLM alternatives](https://scribelet.app/blog/notebooklm-alternatives-personal-notes) once the research phase ends and the notes have to stay usable.

If your real problem is [knowledge decay](https://scribelet.app/blog/knowledge-decay), you need a loop, not a verdict.

## Which notes deserve verification

Not every note should be checked by AI. Some notes age badly. Others do not.

A journal entry from 2024 does not need source verification. It records what you thought, felt, or noticed at the time. Rewriting it because the world changed would be wrong.

A technical note about OAuth scopes is different. If the provider deprecates a scope, the note is no longer a record of your thinking. It is a trap waiting for the next person who follows it.

Use this triage before turning on automated note verification:

| Note type | Verification priority | Best source to check |
|---|---:|---|
| API docs, framework notes, migration guides | High | Official docs, release notes, GitHub repositories |
| Research summaries and citations | High | Original papers, journal pages, retraction notices |
| Client and market intelligence | High | Vendor pages, filings, current reports |
| Architecture decision records | Medium | Current code, internal docs, dependency docs |
| Meeting notes and project plans | Medium | Follow-up decisions, tickets, calendar records |
| Personal reflections and journals | Skip | Not source-checked unless they cite external facts |

A developer note makes the risk easy to see. You documented a webhook integration in January with a note saying the provider retries failed events for 72 hours. In May, the provider changes the retry window to 24 hours and updates the docs.

Your note still looks polished. The next incident response plan built from that note now has the wrong recovery assumption.

That is a verification problem, not an organization problem. Better tags will not catch it. A prettier editor will not catch it. A weekly review helps only if you remember to check that exact claim against the current docs.

For a manual workflow, Scribelet's [30-minute note review system](https://scribelet.app/blog/keep-notes-up-to-date) is a good baseline. For notes that carry source risk, AI can narrow the work to the claims most likely to matter.

One thing to watch when an assistant has already read that note: correcting the answer is not enough. [Fix the source, not just the memory](https://scribelet.app/blog/ai-memory), or the next extraction pass writes the outdated claim straight back.

## How a note-verification workflow should work

A serious AI fact-checking workflow starts with the same discipline traditional fact-checkers use: preserve the exact claim before changing it. The Knight Science Journalism project at MIT describes the editorial process as identifying and marking facts, cross-referencing them against source material, and documenting corrections. Notes need the same discipline, adapted for a system that runs after the note was written.

Here is the sequence that matters.

1. **Extract exact claims.** The system should identify specific sentences that carry evidence burden: dates, numbers, API behavior, quotes, source summaries, policy details, and named-entity claims.
2. **Choose the source path.** It should decide whether to check the open web, a configured connector, a cited URL, or a private source like a repository.
3. **Retrieve current evidence.** It should fetch current material and keep source links attached to the finding.
4. **Compare claim and evidence.** It should detect whether the claim is supported, contradicted, incomplete, or too ambiguous to judge.
5. **Show the diff.** It should propose a minimal edit instead of rewriting the note from scratch.
6. **Ask for review.** The user should accept, dismiss, or ignore. The tool should not assume that current search results understand the context better than the person who owns the note.
7. **Schedule the next check.** A fast-moving API note may need monthly verification. A literature note may need a slower cadence.

Notice what is missing from that list: "generate a better note." That is a different task.

Verification is narrower and more valuable. It does not ask AI to become the author. It asks AI to do the tedious source work, then show receipts.

The output should look something like this:

```text
Original claim:
The API retries failed webhook deliveries for 72 hours.

Current source:
Provider docs now state retries continue for 24 hours after the initial failed delivery.

Suggested diff:
Replace "72 hours" with "24 hours."

Source:
Provider webhook delivery documentation, last updated May 2026.
```

That is the moment where the note owner can make a decision. Maybe the source is right and the note should change. Maybe the note was describing an older API version and needs a caveat instead. Maybe the source page is wrong for your account tier.

The tool should make that judgment easier. It should not pretend the judgment disappeared.

![Workflow diagram showing a note moving from claim extraction to source checks, source-backed diffs, review, and scheduled recheck](/blog/ai-fact-checking-for-notes/verification-loop.svg)

> If your notes reference technical sources, [configure verification sources](https://scribelet.app/learn/ai/connectors) before you rely on generic web search. For developer notes, the [GitHub connector](https://scribelet.app/learn/ai/github-connector) can check claims against the code and docs you actually use.

## Source quality matters more than model confidence

AI fact-checking breaks down when retrieval breaks down. A model can write a clear explanation from weak evidence. That is worse than an obvious failure because it feels finished. It also cannot always tell whether a source means what it appears to say, since [a satirical or AI-generated page can read exactly like a sincere one](/blog/poes-law). And [when much of what you read may be machine-generated](/blog/dead-internet-theory), a source's provenance is often all you have to separate a real account from automated filler.

This is the difference between source-backed verification and AI theater.

For note verification, sources should be ranked by how close they are to the original fact:

| Claim type | Strong source | Weak source |
|---|---|---|
| API behavior | Official docs, release notes, repository code | Tutorial posts, forum guesses |
| Research finding | Original paper, journal correction, retraction database | Blog summary, citation snippet |
| Pricing or packaging | Vendor pricing page, terms page | Old comparison article |
| Legal or policy detail | Government source, official policy document | News recap without links |
| Internal decision | Decision record, ticket, meeting note, code change | Memory, chat summary |

![Source quality ladder showing primary sources above traceable secondary sources, context signals, and weak evidence](/blog/ai-fact-checking-for-notes/source-quality-ladder.svg)

Forums and social posts are not useless. They can show that a problem exists, reveal a workaround, or surface a breaking change before docs catch up. But they are not the final source for claims that carry risk.

The Columbia Journalism Review covered X's AI-written Community Notes and found the same tension at platform scale. AI notes can contribute to fact-checking, but quality depends heavily on implementation. In one case, a draft AI-written note made a false claim about protest footage before human review prevented it from appearing publicly.

That is a useful warning for personal knowledge bases. Human review is not a ceremonial step. It catches the places where retrieval, context, or source interpretation failed.

For high-stakes notes, AI should act as triage. Medical, legal, financial, regulatory, and reputation-sensitive claims still need expert judgment. A verification agent can flag the claim, collect source material, and show where the note may be outdated. It should not become the authority of record.

## Privacy and control are part of the workflow

Fact-checking a note means sending some part of that note into an AI and search workflow. For throwaway prompts, that may not feel like a big decision. For a knowledge base, it is. The same holds when you [ask a model to write your prompts](https://scribelet.app/blog/meta-prompting) from your own notes: whatever you hand it to work from leaves your machine, and where it goes is worth knowing.

Your notes contain client names, project details, private research, half-formed thinking, and relationships that only make sense in context. A tool that verifies them needs to explain where the text goes, which provider processes it, how provider keys are stored, and whether the AI can write back without review.

Ask these questions before trusting an AI note checker:

- Can I choose which notes are verified?
- Can I restrict which sources it checks?
- Does it show a diff before editing?
- Can I reject a suggested change?
- Which AI provider receives the note text?
- Are provider keys encrypted at rest?
- Can I use the feature without giving the vendor my own API key?

That last question matters because Bring Your Own Key (BYOK) is useful, but it should not be a setup tax. Scribelet's AI works out of the box. BYOK is the optional control path for people who want provider choice, cost visibility, or stricter routing through OpenAI, Anthropic, or Gemini. The deeper argument is covered in [BYOK AI explained](https://scribelet.app/blog/byok-ai).

The principle is simple: AI should not quietly become the owner of your notes. It should show its work, preserve your original text, and leave the final write-back decision to you.

That is especially true for teams. A shared desk can contain research from several people. A verification result that changes a team note should be traceable: who accepted it, what source supported it, and what changed in the note.

Without that trail, you have not solved trust. You have moved it from stale notes to invisible automation.

## What this looks like in real work

The easiest way to understand AI note verification is to look at the places where ordinary notes fail.

### Technical notes

A developer saves an internal note about a framework migration. It says a specific configuration flag is required in v4, links to the docs, and includes a code snippet. Two releases later, v5 removes the flag and changes the default behavior.

Search still finds the note. The snippet still looks plausible. The only visible problem is that it no longer matches reality.

A verification workflow should detect the version-sensitive claim, check the current release notes, and propose a focused edit: keep the v4 note for historical context, but add a v5 caveat and link to the migration guide. That is exactly the kind of [outdated documentation](https://scribelet.app/blog/outdated-documentation) problem that wastes engineering hours because the note looks trustworthy.

### Research notes

A researcher summarizes a paper and records the key claim in a literature note. A year later, the paper receives a correction. The correction does not invalidate the entire note, but it narrows the conclusion.

An article checker would not help unless the researcher happened to resubmit the note for review. A note-verification system can periodically re-check cited sources, flag corrections or retractions, and ask whether the wording should change.

The right output is not "this note is wrong." It is more specific: "The cited paper now includes a correction affecting the sample-size claim. The conclusion may still hold, but this sentence should be qualified."

### Client and market notes

A consultant keeps a competitive research note with pricing, plan limits, and feature positioning. The note gets reused across two proposals because it was thorough the first time. The competitor changes packaging in April.

The stale note does not announce itself. It sits in the knowledge base until the consultant quotes the old plan in front of a client.

Verification cannot replace judgment about the market. It can do the dull check: compare saved pricing claims against the current pricing page, flag mismatches, and show the new wording before the note enters another proposal.

That is the real value of AI fact-checking for notes. It does not make you smarter by writing new thoughts for you. It protects the thoughts you already did the work to capture.

## Can AI fact-check notes automatically?

AI can automatically check some note claims, but it should not automatically rewrite your knowledge base. The safer pattern is automatic detection and human-approved correction. Let the system find source drift, gather evidence, and propose a diff. Keep the final decision with the note owner.

This distinction protects you from the two obvious failure modes. Fully manual review does not scale past a small set of notes. Fully automatic rewriting can erase context the AI did not understand.

The middle path is where AI helps most: it narrows the review surface.

## Is AI fact-checking reliable enough for research notes?

AI fact-checking is reliable enough for research-note triage when it uses strong sources and shows uncertainty. It is not reliable enough to be the final authority on high-stakes claims.

The University of Kansas open textbook chapter on research notes makes the same underlying point from a journalism angle: detailed notes let writers and fact-checkers retrace how a claim was found and supported. AI can speed up that source review, but it cannot replace the need for a traceable research process.

For research notes, use verification to catch changed citations, corrections, source mismatches, and unsupported summaries. Use your own expertise to decide what the change means.

## Your notes need receipts, not vibes

Notes become risky when they stay persuasive after their sources drift. The sentence still reads well. The link still exists.

The conclusion still fits the project you are working on. None of that proves the claim is current.

AI fact-checking for notes is worth using when it respects that tension. It should check exact claims, retrieve better sources than a generic chatbot answer, show diffs, and keep you in control of the final edit.

That is the difference between AI that writes more material into your knowledge base and AI that helps you keep trusting what is already there.

[Try Scribelet verification](https://scribelet.app/learn/ai/ai-verification) on one source-heavy note. Pick something old enough to make you uncomfortable. If the note still holds, you get confidence. If it does not, you get a diff before the stale claim gets reused.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>ai-verification</category>
            <category>fact-checking</category>
            <category>note-taking</category>
            <category>knowledge-decay</category>
            <category>knowledge-management</category>
            <category>byok</category>
        </item>
        <item>
            <title><![CDATA[NotebookLM alternatives for personal notes]]></title>
            <link>https://scribelet.app/blog/notebooklm-alternatives-personal-notes</link>
            <guid isPermaLink="false">https://scribelet.app/blog/notebooklm-alternatives-personal-notes</guid>
            <pubDate>Mon, 25 May 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Compare NotebookLM alternatives for editable notes, source chat, audio, privacy, and AI maintenance. See when Scribelet fits, and when Google still wins.]]></description>
            <content:encoded><![CDATA[
NotebookLM is easy to like until you try to make it your daily notebook.

It can summarize a dense PDF, turn a stack of sources into a study guide, and generate audio overviews that feel better than most AI summaries. But if you are comparing NotebookLM alternatives because you want editable personal notes, cross-note memory, wikilinks, mobile capture, or control over which AI provider reads your knowledge base, you are not looking for another research assistant. You are looking for a notebook with AI inside it.

That distinction matters. NotebookLM is source-first. A personal note-taking system is note-first. Source-first tools help you understand uploaded material. Note-first tools help you keep your own knowledge usable after the first summary.

The useful comparison is by job: research, audio learning, private source chat, and living personal notes. From there, the choice gets cleaner. Some workflows still belong in NotebookLM. Others need a note-taking system that keeps changing as your knowledge changes.

If what you want is AI chat over notes you keep writing, linking, tagging, and revising, start with [Scribelet's AI chat guide](https://scribelet.app/learn/ai/ai-chat). It is the core difference between asking questions about uploaded sources and asking questions inside a notebook that keeps changing.

## The real question: source library or living notes?

NotebookLM is a source-grounded research tool. You add sources, ask questions, generate summaries, create study material, and listen to audio overviews. Google's own [source guide](https://support.google.com/notebooklm/answer/16215270?hl=en) frames the workflow around source material, not a long-running notebook where notes themselves are the main object.

That makes NotebookLM excellent for temporary research containers:

- A semester's reading packet
- A folder of client PDFs
- A batch of interview transcripts
- A long report you need to understand fast
- A set of YouTube videos or web pages you want summarized

A personal note-taking app has a different center of gravity. The note is not an output from source material. It is the thing you keep using. You write into it, edit it, link it to other notes, tag it, search it later, and return to it months after the original source has changed.

That distinction is where a lot of NotebookLM frustration comes from. A user uploads 20 PDFs, gets a useful answer, and thinks: "I want this for all my notes." Then they discover that the product is better at analyzing a bounded set of sources than maintaining an evolving knowledge base.

Google has added note features to NotebookLM, including ways to save responses and create notes. But [Google's note help page](https://support.google.com/notebooklm/answer/16262519?hl=en) still describes notes as a layer inside a notebook built from sources, and it notes that mobile app support for creating or editing notes is not available at the time of writing. That does not make NotebookLM weak. It makes it a different tool.

Here is the practical test: if you delete the sources, does the system still make sense?

For NotebookLM, probably not. For a note-taking app, absolutely. Your notes are the system of record.

![Diagram comparing a source-first research notebook with a note-first knowledge base](/blog/notebooklm-alternatives-personal-notes/source-first-vs-note-first.svg)

## Best NotebookLM alternatives by job

The wrong way to choose a NotebookLM alternative is to ask, "Which tool is closest to NotebookLM?" That pushes you toward feature matching instead of workflow matching.

Ask what you are trying to preserve from NotebookLM and what you are trying to escape.

| What you need | Better-fit category | Why |
|---|---|---|
| Fast summaries of uploaded PDFs and web pages | Source-grounded research assistants | They are optimized around documents, citations, and synthesis. |
| AI audio from source material | Audio learning tools | They care more about listening flow, voice quality, and mobile playback. |
| Private or self-hosted source chat | Local-first AI knowledge tools | They keep files closer to your machine or your own infrastructure. |
| Editable personal notes with AI chat | AI note-taking apps | The notes remain editable, searchable, linked, and useful after the first summary. |
| A team workspace with AI summaries | All-in-one workspaces | They combine docs, projects, permissions, and shared knowledge. |

Those categories are a better starting point than feature matching.

One thing to keep in mind: NotebookLM alternatives are not interchangeable. A tool that is better at academic paper search may be worse at daily note capture. A tool with beautiful audio may have no concept of backlinks. A self-hosted tool may protect your data well but add enough setup work that you never use it.

The best alternative is the one whose failure mode you can live with.

## When NotebookLM is still the right tool

NotebookLM deserves its popularity. If your workflow starts with a defined set of sources, it is hard to beat.

Say you have six PDFs for a literature review, two long YouTube lectures, and a few web pages. You want a briefing, a list of themes, and questions to ask before a meeting. NotebookLM is built for that. You are not trying to maintain a permanent notebook. You are trying to understand a source set quickly.

The audio feature is another real strength. Google's [Audio Overviews announcement](https://blog.google/innovation-and-ai/products/notebooklm-audio-overviews/) made NotebookLM feel different from ordinary summarizers because it turned source material into something you could listen to while walking, commuting, or doing chores. That is not a minor interface trick. For many people, listening is the only way they get through dense material.

NotebookLM is also a good fit when you want a clean separation between projects. Each notebook can hold a bounded set of material. That works well for a class, a research sprint, a report, or a single client engagement.

Use NotebookLM when the job looks like this:

- "Help me understand these sources."
- "Summarize this report and explain the key claims."
- "Turn this source set into an audio briefing."
- "Find where these documents agree or disagree."
- "Prepare me for a discussion about this material."

The boundary is simple. NotebookLM works best when the sources define the work. A personal note-taking system works best when your own evolving notes define the work.

## Where NotebookLM starts to feel wrong for note-taking

NotebookLM starts to creak when you use it as a long-term personal knowledge management system. Not because it is badly designed, but because it is designed around a different lifecycle.

### Your notes are not the center

In a living note system, you start with your own thinking. Sources support it. You write a note about a project, connect it to a meeting note, tag it with `#client-research`, and link it to a decision log. A month later, you update it with what changed.

NotebookLM reverses that. You start with sources. The AI helps you extract, summarize, and reason over them. Notes exist, but they are not the same as a full writing environment with backlinks, templates, tags, note history, and a knowledge graph.

That difference becomes obvious once the source material stops being the main thing.

A consultant uploads a market report, a pricing page, and interview notes before a strategy call. NotebookLM generates a useful brief. Two months later, the competitor changes pricing and the consultant has added four new client notes elsewhere. The original notebook still knows the old source set. The live knowledge now lives across multiple places.

The summary was useful. The system did not become the source of truth.

### Cross-note memory is different from source chat

There is a meaningful difference between chatting with a source set and chatting with your whole knowledge base.

Source chat answers from the material you uploaded. Cross-note memory answers from the evolving context you have built over time: people, projects, terms, decisions, preferences, and prior conversations. That is why [AI memory](https://scribelet.app/learn/ai/ai-memory) in a note-taking app has to behave differently from a research notebook.

If you ask, "What did we decide about the billing migration?" the answer should pull from meeting notes, architecture decision records, daily notes, and prior chat episodes. It should know that "Paddle migration," "RevenueCat cleanup," and "billing refactor" may refer to the same project context. That is not a PDF summary problem. It is a persistent memory problem.

### Mobile capture matters more than mobile reading

NotebookLM's mobile apps are useful for reading, listening, and asking questions. But note-taking is capture-heavy. The important moment is often when you are walking between meetings, leaving a client call, or thinking through a bug on your phone.

If the mobile workflow is mainly "consume what I already prepared," it will not replace a notes app. A notes app needs fast capture, editing, offline tolerance, search, tags, links, and a path back to the desktop workflow. That capture-to-desktop loop only holds up in a genuine [note app for iOS and Android](https://scribelet.app/blog/cross-platform-note-taking-app) and web, not a desktop tool with a companion viewer bolted on.

Voice is part of this. A raw transcript is not enough. A strong mobile note app should turn a voice memo into a structured note with a title, headings, action items, and tags. Otherwise you have traded typing for cleanup.

### There is no note maintenance loop

NotebookLM can help you analyze sources. It does not solve the problem that [notes go stale](https://scribelet.app/blog/knowledge-decay).

That matters when notes contain claims that can drift: API behavior, pricing pages, citations, market data, policy details, competitor messaging, and internal decisions. Search and summary help you find and understand information. They do not tell you whether the information you wrote three months ago is still true.

This is the missing layer in most NotebookLM alternatives, too. They help you ask better questions. Fewer help you maintain better answers.

![Diagram showing how one-time summaries age silently while maintained notes loop through search, verification, diffs, and review](/blog/notebooklm-alternatives-personal-notes/maintenance-loop.svg)

## What to look for in a NotebookLM alternative for personal notes

If your real need is "NotebookLM for my notes," do not start with a generic feature checklist. Start with the lifecycle you need your knowledge to survive.

### Editable notes as the system of record

The alternative should let you write real notes instead of save AI outputs. That means a proper editor, version history, note links, tags, search, and durable organization.

You should be able to create a note from scratch, revise it next week, link it to related notes, and trust that it still belongs in the same system a year later. Saved summaries are useful. They are not a notebook.

### AI chat that searches your notes

AI chat should be grounded in your own notes and cite what it used. This is where a note-taking app can beat NotebookLM for personal knowledge. The AI should search across notes, fetch the relevant ones, compare them, and answer with enough traceability that you can check the source.

In Scribelet, AI chat searches your notes with semantic retrieval and source citations. It is built for questions like "What did I decide about this project?" or "Which notes mention this client risk?" instead of "Summarize these five uploaded PDFs."

### Links, tags, and knowledge graph behavior

NotebookLM can help you reason over a source set. A note-taking system should help you build a connected web of thought.

That means `[[wikilinks]]`, backlinks, inline `#tags`, and AI-assisted connection discovery. If you care about personal knowledge management, [wikilinks and backlinks](https://scribelet.app/learn/notes/wikilinks-backlinks) are not decorative. They are how old notes keep finding their way back into active work.

The AI layer should respect those connections. If two notes are linked, that relationship should help retrieval. If several notes mention the same project under slightly different wording, the system should learn that pattern.

### Provider choice and BYOK

If an app is going to read your notes, you should care where those notes go.

Bring Your Own Key (BYOK) means you connect your own OpenAI, Anthropic, or Gemini key instead of using only the vendor's bundled AI path. It gives you provider choice, cost control, and clearer data routing. For personal notes, that matters more than it does for throwaway prompts, because your notes contain a long-running record of your work.

Scribelet supports BYOK across its AI features. If you want the deeper privacy and cost argument, read [BYOK AI explained](https://scribelet.app/blog/byok-ai).

### Verification beats another summary

The most useful AI note-taking feature is not always another summary. Sometimes it is a warning that a note is wrong.

For technical notes, that might mean an API endpoint changed. For research notes, it might mean a citation was updated or challenged. For client notes, it might mean a competitor pricing page no longer matches what you wrote.

Scribelet's [AI verification](https://scribelet.app/learn/ai/ai-verification) is built around that loop. Background agents check notes against sources, compare findings to what you wrote, and show diffs when something changed. You review the diff instead of re-auditing the note from scratch.

That is the line between AI that helps you write more notes and AI that helps you keep trusting the notes you already have.

> Want the note-first version of this workflow? Try Scribelet with a free desk, write a few notes, then ask AI chat what it can find across them. The difference shows up once your notes start connecting.

## The shortlist: which alternative fits your workflow?

There is no single best NotebookLM alternative. There are better fits for specific workflows.

### If you want NotebookLM as an actual notebook: Scribelet

Scribelet is the closest fit if your complaint is, "I want NotebookLM-style AI, but inside notes I can keep editing."

It gives you a real note-taking surface: rich markdown editing, wikilinks, backlinks, inline tags, semantic search, daily notes, voice-to-structured-note, and cross-platform access on iOS, Android, and web. The AI layer sits inside that notebook instead of beside it. You can chat with your notes, verify claims, build memory, and let background agents surface stale information.

This is not a replacement for NotebookLM's audio overviews. If your primary workflow is listening to generated podcasts from uploaded sources, NotebookLM or a dedicated audio tool will fit better. Scribelet is for people whose notes are the durable knowledge base.

### If you want local-first control: Obsidian plus AI plugins

Obsidian is the strongest choice when file ownership matters above everything else. Your notes live as local markdown files. The plugin ecosystem is deep. The community has built workflows for almost every serious personal knowledge management method.

The tradeoff is assembly. AI depends on plugins, local models, API keys, and configuration choices. That can be exactly what a technical user wants. It can also become the thing that keeps the system from being used every day.

Choose Obsidian if you want maximum control and are willing to maintain your own stack.

### If you want an all-in-one workspace: Notion

Notion is not a NotebookLM clone. It is a workspace with databases, docs, projects, permissions, and AI features layered across them. If your real need is a shared operating system for a team, Notion may be the practical choice.

The downside is that note-taking can become heavier than it needs to be. Databases, relations, views, permissions, and templates are useful until they make a simple note feel like a configuration task. Notion also does not give you BYOK for AI, so provider choice and data routing stay with Notion.

Choose Notion if collaboration and workspace structure matter more than note-native AI maintenance.

### If you want academic research workflows: Elicit, Unriddle, or Paperguide

Academic research tools beat general note apps when the job is literature discovery, paper analysis, citation workflows, and evidence extraction. They are built around papers and claims, not daily notes.

This is the right category for a graduate student preparing a literature review or a researcher triaging dozens of PDFs. It is less compelling if you are trying to keep meeting notes, project decisions, and voice memos in one personal knowledge base.

Choose a research assistant when sources are the work.

### If you want audio-first learning: NotebookLM, ElevenLabs Reader, or dedicated audio tools

If audio is the reason you love NotebookLM, do not force a note-taking app to become a podcast generator. Pick a tool designed around listening.

NotebookLM's Audio Overviews are still the reference point for conversational source summaries. ElevenLabs Reader and other audio-first tools may fit better when voice quality, long-form playback, and mobile listening matter more than note organization.

The only caution: audio summaries can feel productive while leaving little durable knowledge behind. If you listen, capture the decisions, ideas, and follow-up questions somewhere you will search later.

## How Scribelet compares to NotebookLM

The cleanest comparison is not feature by feature. It is lifecycle by lifecycle.

| Question | NotebookLM | Scribelet |
|---|---|---|
| What is the main object? | Sources inside a notebook | Editable notes inside a desk |
| What is AI best at? | Summarizing and explaining uploaded material | Chatting with, connecting, and verifying your notes |
| Does it support audio overviews? | Yes | No dedicated podcast generator |
| Does it support wikilinks and backlinks? | No native PKM-style linking | Yes |
| Can you use your own AI provider key? | No | Yes, through BYOK |
| Does it check whether notes are stale? | No dedicated maintenance loop | Yes, through AI verification |
| Best use case | Researching a bounded source set | Maintaining a living knowledge base |

That is the decision.

Use NotebookLM when you have sources to understand. Use Scribelet when you have notes to keep using.

The overlap is real. Both products help you ask questions and synthesize information. But the center is different. NotebookLM is what you open when you need to understand a pile of material. Scribelet is where that understanding becomes part of your ongoing knowledge base.

## The right alternative depends on what you want to trust

NotebookLM made source-grounded AI feel normal. That is a big shift. It taught people that AI answers are more useful when they can point back to the material they came from.

The next question is what happens after the summary.

If the work ends when you understand the sources, NotebookLM is still a strong choice. If the work continues for months, through meetings, decisions, notes, edits, links, and updates, you need a system built for living knowledge.

If you compare only AI features, you miss the real decision: what you want to trust later. A source notebook, an audio briefing, a local folder, a team workspace, and a personal knowledge base all age differently.

If your answer is the last one, [start with Scribelet](https://scribelet.app). Create a desk, write a few notes, connect them with wikilinks, and ask AI chat what it can find. Then turn on verification for anything that has to stay true.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>notebooklm</category>
            <category>ai-notes</category>
            <category>note-taking</category>
            <category>personal-knowledge-management</category>
            <category>alternatives</category>
            <category>byok</category>
        </item>
        <item>
            <title><![CDATA[A better work log starts before Friday]]></title>
            <link>https://scribelet.app/blog/ai-work-log</link>
            <guid isPermaLink="false">https://scribelet.app/blog/ai-work-log</guid>
            <pubDate>Mon, 11 May 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A work log should remember outcomes, decisions, and follow-ups before Friday. See how AI work memory turns daily notes into status updates and review evidence.]]></description>
            <content:encoded><![CDATA[
Friday, 4:42 p.m. The weekly update is due, your calendar says the week was full, and your work log has three bullet points that explain almost nothing.

That is the failure point. A work log is supposed to help you remember what happened, but most people only open it when the memory work is already hard.

The meetings are over. The follow-ups are scattered across Slack, email, and half-written notes. The decision that mattered on Tuesday is now buried under the ten things that happened on Thursday.

A better pattern is possible: a work log that captures outcomes, decisions, action items, and review evidence while the work is still close. The point is not to make reporting heavier. It is to make Friday easier because the important context was already captured during the week.

If you want to see the output this produces, start with [Scribelet weekly insights](https://scribelet.app/learn/ai/weekly-insights). They are the closest product surface to the Friday update problem: notes go in during the week, patterns and action items come back out.

## What is a work log?

A work log is a running record of work activity, outcomes, blockers, decisions, and follow-ups. A useful work log doesn't only list what you did. It preserves enough context to explain why the work mattered, what changed, and what needs attention next.

That definition matters because people use "work log" to mean two different jobs. One group wants a time tracker: hours, dates, clients, billable work. Another group wants a narrative memory of the week: shipped work, decisions, blockers, action items, and status updates.

Scribelet belongs in the second category. It is not trying to become a timesheet. It is for the knowledge worker who needs to answer questions like:

- What changed this week?
- Which decisions should we not lose?
- What follow-ups did I promise?
- What should my manager, client, or team know?
- What evidence will matter during review season?

A work log only earns its keep when it helps with real outputs. It should make the weekly update faster, keep decisions from disappearing, turn loose follow-ups into visible next steps, and preserve evidence you can use when someone asks what you worked on.

## Why manual work logs fail by Friday

The standard work-log advice sounds reasonable: write down what you did every day, organize it in a template, review it once a week, and turn it into a report. That works for a short stretch. Then real work takes over.

The problem is not laziness. The problem is timing.

Manual work logs ask memory to act like infrastructure. By Friday afternoon, your brain is trying to rebuild an event stream from leftovers: calendar titles, chat fragments, ticket comments, and whatever you remembered to write down. The most visible work wins. The quiet work disappears.

That is why career advice around brag documents has stuck around for years. Julia Evans' guide to [brag documents](https://jvns.ca/blog/brag-documents/) is still the canonical reference because it names a real failure mode: your manager will not remember every useful thing you did, and neither will you. The fix is evidence, captured before the evidence fades.

A [r/LifeProTips discussion about updating a private brag document every Friday](https://www.reddit.com/r/LifeProTips/comments/1t2pq3o/lpt_keep_a_private_brag_document_and_update_it/) made the same point from the adoption side. People liked the idea, but the resistance was obvious: another weekly document becomes another chore. The pain is strong enough to discuss. The habit is fragile enough to fail.

There is a second failure hidden in most templates. They separate the output from the source.

A weekly status report might say "resolved billing retry issue." Useful, but thin. The real context lives elsewhere: the customer complaint, the incident note, the decision to change retry timing, the follow-up to update docs, and the metric that showed failures dropped the next day. If those pieces never make it into the work log, the report is technically correct and still not very useful.

A product manager might finish a week with 11 meetings, two stakeholder decisions, one delayed launch, and a list of follow-ups across three tools. If they wait until Friday to write the update, the report becomes a memory exercise. If rough notes were captured each day, the Friday job becomes editing. That difference is the whole point.

## A work log template is only half the system

Templates are useful. There is a reason people reach for a work log template or a weekly status report template before they change the underlying workflow.

The reason is simple: a blank page is unpleasant. A template gives the update a shape.

[Asana's work log template](https://asana.com/templates/work-log) frames the job around tasks, custom fields, and work visibility. Atlassian's [end-of-week status report template](https://www.atlassian.com/software/confluence/templates/end-of-week-status-report) focuses on progress, results, help needed, and project alignment. Those are sensible structures.

But a structure is not a memory. It tells you where to put the information. It doesn't create the information, preserve its source, or remind you what happened when Friday arrives.

| Need | Work log template | Time tracker | AI work memory |
|------|-------------------|--------------|----------------|
| Gives the update a repeatable shape | Yes | Sometimes | Yes |
| Captures hours | No | Yes | Optional |
| Preserves decisions and rationale | Only when typed manually | Rarely | Yes, from notes |
| Extracts action items | No | No | Yes |
| Generates weekly status updates | No | Sometimes as activity reports | Yes, from captured context |
| Preserves review evidence | Only with discipline | Weak | Strong |
| Links back to source notes | No | Rarely | Yes |

This is where most work-log apps blur into time tracking. They know a two-hour block existed. They may know the project name. They usually do not know the decision that came out of the meeting, the customer risk that changed priority, or the follow-up you promised to send by Wednesday.

For some work, hours are the product. For knowledge work, hours are only a shadow. The useful record is the trail of decisions, outcomes, blockers, and evidence.

That is why "AI work log" is a sharper phrase than "automatic timesheet." The goal is not to infer every minute of your day. The goal is to keep enough work memory that the professional artifacts become easier to produce.

## What an AI work log should capture

An AI work log should start from rough capture, not polished reporting. The daily notes, meeting notes, voice memos, and project observations are the source material. The output can be clean later.

Scribelet already has the pieces for that workflow. [Creating and editing notes](https://scribelet.app/learn/notes/creating-editing-notes) gives you the daily capture surface. Voice memos can become structured notes with headings, action items, and suggested tags. [Note templates](https://scribelet.app/learn/notes/note-templates) give recurring work a repeatable shape without turning every note into a form.

The capture model should cover five kinds of information.

**Outcomes** are the finished work, shipped changes, client deliverables, decisions accepted, incidents resolved, or drafts completed. They answer "what moved?"

**Decisions** preserve the call and the rationale. Keeping [a dedicated decision log](/blog/decision-log) matters because the decision itself is rarely the hard part. The hard part is remembering why the team chose that path after the constraints have changed.

**Action items** need an owner, context, and next step. People build action item trackers because loose promises decay fast. A good work log keeps the promise attached to the meeting, decision, or project note that created it.

**Blockers and risks** keep the update honest. A weekly report that only lists wins is less useful than one that names the dependency, the missed input, or the decision still waiting on someone else.

**Evidence** turns work into career memory. This is the brag-document angle, but broader. A useful work log can later answer: what did I improve, who did it affect, and what proof do I have?

Here is a concrete version. A software engineer spends Tuesday pairing on a flaky billing test, Wednesday reviewing a risky migration plan, and Thursday fixing a production alert that did not become a full incident. None of that may show up as a large shipped feature. Captured properly, it becomes review evidence: reliability work, cross-team support, incident prevention, and judgment under pressure.

The best work logs do not treat that as miscellaneous activity. They preserve it.

## How Scribelet turns daily notes into work memory

Scribelet's advantage is that it doesn't need the work log to start as a work log.

You can write a daily note, record a voice memo after a meeting, tag a project with `#billing`, link a decision to `[[Q2 roadmap]]`, or keep a client desk separate from your personal desk. The work memory forms from the notes you were already taking.

[AI memory](https://scribelet.app/learn/ai/ai-memory) then extracts the durable context: people, projects, terminology, preferences, and relationships. That matters for work logs because the same project appears under different names across a week.

A ticket code, a customer name, a roadmap label, and a meeting title may all point to one body of work. Memory helps connect them.

[Desks](https://scribelet.app/learn/organization/desks) keep those contexts separate. A consultant can keep each client in a separate desk. A manager can keep team notes separate from personal review notes. A founder can split investor updates, product work, and hiring notes without mixing the memory.

Then weekly insights and AI chat turn captured context into outputs:

- A weekly status update for a manager or client
- A follow-up list grouped by project
- A decision log with source notes attached
- A review-evidence list for a brag document
- A risk summary for the next team meeting

The connection to source notes is the part templates usually miss. If an AI-generated weekly update says "billing retry failures dropped after retry timing changed," you should be able to open the note, see the decision context, and inspect the evidence. Without that trace, the update is polished text. With it, the update is a usable work record.

There is also a trust reason to care. Work notes are sensitive. They contain client details, internal projects, people issues, compensation context, and unfinished thinking. Scribelet's default AI works without setup, but Bring Your Own Key (BYOK) is available when you want provider choice and stricter data routing. The [BYOK AI guide](https://scribelet.app/blog/byok-ai) explains the model-control side in more detail.

Ready to test the workflow in a small way? Create one work desk, add this week's daily notes, and let [weekly insights](https://scribelet.app/learn/ai/weekly-insights) show what it can extract before you build a bigger system.

## A simple work-log workflow to try this week

Do not start with a massive template. Start with capture.

On Monday, create a daily note and write the projects you expect to touch. Keep it rough. A useful daily work log entry can be three fragments: what changed, what got stuck, what needs follow-up.

After meetings, add one short note while context is fresh. Capture the decision, the owner of the next step, and the reason the decision went that way. A 45-second note after the meeting beats a polished reconstruction three days later. That habit of logging a line the moment you switch tasks has a name, [interstitial journaling](https://scribelet.app/blog/interstitial-journaling), and it pays off most when something reads the day's log back for you.

On Friday, ask for the output you need. A manager update and a client update are not the same artifact. A performance-review evidence list is different again. The source memory can be shared; the output should match the audience.

Once a month, review the evidence, not every note. Look for shipped work, decisions influenced, incidents prevented, customer outcomes, and repeated themes. That is where the work log becomes more than administration.

A manager using this pattern might notice that the same dependency blocked two projects in one month. A consultant might see that client follow-ups cluster around unclear ownership after workshops. An engineer might find that most of their highest-value work was unplanned reliability work. The artifact at the end is useful because the memory underneath is specific.

This is also where Scribelet connects to the broader [AI second brain](https://scribelet.app/blog/ai-second-brain-setup) idea. A second brain usually focuses on knowledge retrieval. An AI work log focuses on work accountability: what happened, what changed, what was decided, and what should happen next.

## The best work log keeps evidence close to the work

A work log fails when it becomes a second job. The point is not to maintain a beautiful spreadsheet, keep a perfect template, or write miniature performance reviews every afternoon. The point is to keep evidence close enough to the work that you can use it later.

That is the real shift from a manual work log to AI work memory. Capture can stay small. The system can extract action items, connect decisions, surface themes, and draft the Friday update when you need it. You still review the output. You still decide what to send. But you are editing from memory, not inventing from absence.

Try it with one week of work. Capture the rough notes as they happen, then use Scribelet to turn them into a status update, follow-up list, and review-evidence trail. If the Friday update gets easier, the system is doing its job.

[Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and give your work a memory before the week disappears.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>work-log</category>
            <category>ai</category>
            <category>productivity</category>
            <category>note-taking</category>
            <category>weekly-insights</category>
            <category>knowledge-management</category>
            <category>ai-memory</category>
        </item>
        <item>
            <title><![CDATA[AI second brain: how to build one that stays accurate]]></title>
            <link>https://scribelet.app/blog/ai-second-brain-setup</link>
            <guid isPermaLink="false">https://scribelet.app/blog/ai-second-brain-setup</guid>
            <pubDate>Sat, 02 May 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[An AI second brain is only as good as the day you last checked it. Compare the four ways to build one, then add the maintenance step every guide skips.]]></description>
            <content:encoded><![CDATA[
Search interest in the phrase "AI second brain" has more than tripled in the past year, and the guides have multiplied to match. Build one with Claude Code. Build one with a no-code workflow builder. Build one in a weekend with a vector database and an afternoon of patience. Nearly all of them assume you are building it for work, and quietly skip [a second brain for your personal life](/blog/second-brain-for-personal-life), where the same method applies to your home, health, and kitchen.

Almost all of them stop in the same place. They cover how information gets in and how you ask questions of it. Very few say anything about month seven, when the API you documented has shipped a new auth flow, the pricing you saved is out of date, and the model answering your questions is confidently citing a note that stopped being true in March.

This guide covers both halves. What an AI second brain actually is, the four ways people build one and what each costs you, and then the maintenance layer that decides whether you still trust the thing a year from now.

## What is an AI second brain?

An AI second brain is a personal knowledge system where AI does three jobs the system used to require you to do by hand: retrieve the right note by meaning rather than by keyword, connect notes you would never have linked yourself, and keep what you filed accurate as the world it describes changes.

The "second brain" half of the term comes from Tiago Forte's 2022 book, which popularised the idea of an external store for everything you learn. The "AI" half is what changed in the last 18 months, and it changed the bottleneck. Capture was never the hard part. Trusting what you captured, and reaching it at the moment it matters, always was.

A working definition that respects a skeptical reader: an AI second brain is a notes system where every note can be checked, retrieved, and referenced by an AI without you doing the integration work by hand. It does not write your notes for you. It keeps what you wrote useful.

That last distinction matters because two different artifacts get called the same thing right now. [The LLM wiki pattern](https://scribelet.app/blog/llm-wiki) has a model compile your curated sources into a wiki it authors and you read. A second brain is the notes you wrote yourself, in your own words. Both are worth building, and both need someone checking whether what is on the page is still true. We pulled that fork apart in more detail when Andrej Karpathy floated the idea, and there are genuinely [two directions for a self-maintaining knowledge base](https://scribelet.app/blog/karpathy-llm-wiki-reaction) depending on which artifact you care about.

## The four ways to build an AI second brain

Every setup guide you will find is arguing for one of four architectures. They differ less in what they can do on day one than in who is responsible for keeping them working on day two hundred.

| Build path | What it is | Who keeps it accurate | Where it breaks |
|---|---|---|---|
| **Markdown plus a coding agent** | Local files in Obsidian or a plain folder, indexed and edited by Claude Code or Cursor | You, by remembering to run the prompts | The month you get busy and stop running them |
| **No-code workflow builder** | n8n, Zapier or MindStudio wiring capture into a vector store, with a chat layer on top | You, by repairing the workflow | Any API in the chain changes shape, silently |
| **Managed second-brain app** | A hosted product that ingests your sources and answers questions about them | The vendor, and only for retrieval | You need the same knowledge anywhere else |
| **Notes app with background agents** | Notes with scheduled verification, semantic linking, and an endpoint other AI tools can call | The system, on a schedule you set | The agents check the wrong things, or you never read what they surface |

The first three are the ones the tutorials cover, and they all work. The honest caveat is that the first two hand you a maintenance job and the third hands you a boundary you cannot cross. Whichever you choose, the question to ask before you invest a weekend is not "can it answer questions about my notes" but "what happens to this in six months if I stop paying attention to it".

If you are starting from an existing vault rather than a blank slate, the practical constraints are different again, and we went through them separately in the guide to [running AI over an Obsidian vault](https://scribelet.app/blog/obsidian-ai).

## Three ways a second brain stops working

Most guides treat second brain failure as a discipline problem. You did not review weekly. You did not tag consistently. You did not follow the method rigorously enough.

That diagnosis is wrong, and it is why the standard fix (try harder) does not hold. There are three structural failure modes. They feel different from the inside and they lead to the same place: a folder of notes you have quietly stopped opening.

![Three failure modes of an AI second brain: decay, the retrieval graveyard, and the integration gap with your AI tools](/blog/ai-second-brain-setup/second-brain-failure-modes.svg)

### Decay

You wrote a Stripe integration guide last quarter. Stripe shipped a new auth flow. Your guide now teaches a pattern that returns 401s, and you will not find out until a teammate follows it.

This is [knowledge decay](https://scribelet.app/blog/knowledge-decay), and it reaches every note that references something external: an API, a paper, a competitor's pricing, a regulation. Information has a half-life. Notes accumulate inaccuracy by sitting still while the world moves.

The standard advice is a quarterly review. At 50 notes that works. At 500 it fails arithmetically. Verifying a single note properly, which means checking sources, reading changelogs, and comparing what you wrote against what is current, takes 15 to 30 minutes. Multiply that by your top notes and you will quietly stop doing it.

### The graveyard

A user on r/PKMS [named this one precisely](https://www.reddit.com/r/PKMS/comments/1rqv62k/i_spent_years_trying_to_build_a_second_brain_with/): "The actual problem isn't capturing. Capturing is easy. The problem is retrieval."

You captured for years. You have thousands of notes. You can never find the one you need at the moment you need it, because search returns either every note that mentioned the keyword or nothing at all, since you used different words six months ago.

A 237-upvote post in r/ObsidianMD titled ["I Deleted My Second Brain"](https://www.reddit.com/r/ObsidianMD/comments/1lmh226/i_deleted_my_second_brain/) is the emotional version of this failure. Two years of building. Unusable. Deleted.

A [digital garden](https://scribelet.app/blog/digital-garden) is the same project with an audience attached, and it stalls on the same schedule for the same reason. Publishing does not create the upkeep; it only makes the gap visible to other people.

### The integration gap

This one is newer, and it is growing. You have a second brain in Obsidian. You also pay for Claude, use NotebookLM occasionally, and run Cursor for coding. Each tool has its own idea of "your context." None of them know about the others.

A user [described it on r/ObsidianMD](https://www.reddit.com/r/ObsidianMD/comments/1ri2z8q/im_trying_to_build_an_ai_second_brain_and_im/): "I want a second brain that actually knows my history, past decisions, failed experiments, half-baked ideas, the WHY behind how I think. My setup: Obsidian + Claude Pro + NotebookLM. Solid individually but completely siloed."

The AI you are paying for has amnesia. The notes you wrote cannot reach it. You re-explain your projects every time you open a chat.

A system that solves one of these three still fails in the other two. A system that solves all three is a different kind of object, and that is the thing worth building.

## The step CODE stops before

Most second brain guides start with [Tiago Forte's CODE framework](https://fortelabs.com/blog/basboverview/), and it is worth using. It is clean, and the vocabulary already exists in everything else you will read.

CODE stands for Capture, Organize, Distill, Express. Capture what resonates as you read or work. Organize by actionability rather than topic. Distill down to what is worth keeping. Express it as writing, decisions, or product.

CODE is good. It is also open at one end. It describes everything up to the moment you make something with a note, and says nothing about what happens to that note in the six months afterwards.

![The four stages of the CODE method shown left to right, with a fifth stage, Maintain, closing the loop back to Capture](/blog/ai-second-brain-setup/code-plus-maintain.svg)

The missing fifth step is Maintain: keeping notes accurate as the world changes, resurfacing dormant notes when they become relevant again, and archiving what is no longer true. Skip it and decay catches up with you on a schedule you do not control. Close the loop and the knowledge base appreciates instead of depreciating.

This is the gap we wrote about at length in the [living notes method](https://scribelet.app/blog/living-notes-method). The short version: every PKM methodology designed before AI agents existed treats notes as finished artifacts. They are not. They behave much more like dependencies in a software project, and dependencies need updating. It is also the step missing from the field as a whole, which is the argument we made about [what personal knowledge management leaves out](https://scribelet.app/blog/personal-knowledge-management).

## A maintenance layer you can actually run

"Maintain your notes" is useless as advice. Here is the specific version, split by what a machine should do and what only you can.

| Task | Cadence | Who runs it | What it catches |
|---|---|---|---|
| Verify notes that cite external sources | Weekly | Automated | The API, price, statistic or rule that changed since you wrote it |
| Triage what verification flagged | Weekly, 10 minutes | You | Real changes, separated from noise |
| Link new notes to older related ones | Continuous | Automated | Connections you would never have made by hand |
| Archive projects that have shipped | Monthly | You | Finished work still sitting in the active pile |
| Prune what you no longer believe | Quarterly | You | Notes you would be embarrassed to cite today |

The split is the whole point. The two automated rows are the ones that fail when they are left to a human, because they are unbounded and boring. The three manual rows are the ones that fail when they are left to a machine, because they need judgement about your own work.

Getting that division right is what makes the difference between a system you maintain and a system that maintains itself.

## PARA in 2026, with AI doing the sorting

PARA is the filing system that pairs with CODE. Four buckets: Projects, Areas, Resources, Archive. Projects are short-term efforts with an outcome. Areas are ongoing responsibilities. Resources are topics you might use later. Archive is everything inactive.

PARA still works. What changes is who does the sorting. In the original, you decide where each note goes as you process your inbox. With AI in the loop, the system can propose the bucket, suggest tags, surface related notes you forgot you wrote, and flag a "Project" note that belongs in "Archive" because the project shipped two months ago. You stay the decider. The AI does the legwork. We walked through that mapping in detail in [the PARA method with AI](https://scribelet.app/blog/para-method-with-ai).

In Scribelet, each major bucket lives in a [desk](https://scribelet.app/learn/organization/desks). Personal projects in one, client work in another, ongoing areas in a third. Tags inside each desk handle finer filing. AI memory is scoped per desk, so your team's terminology in the work desk does not leak into your personal desk.

That separation matters more than it sounds like it should. It is the difference between a second brain that is one giant context window and one that is a structured memory you can reason about. If you want the mechanics underneath that distinction, [the four types of AI memory](https://scribelet.app/blog/ai-memory) covers what each one holds and what each one gets wrong.

## Setting up your AI second brain

Five steps. Each takes between two and ten minutes.

**1. Create one desk, not a system.** Pick the single use case where you most often need notes you can trust: technical documentation, client research, course notes. Start there. Modelling your whole life on day one is the most common way this stalls.

**2. Set up capture from wherever you already think.** Web, mobile, and voice. Voice is the highest-leverage capture method most people never turn on. You record a thought, it gets transcribed, and AI structures the result into a note with a title, headings, and suggested tags. Accuracy improves as the desk's memory learns your vocabulary.

**3. Turn on the background agents.** This is the Maintain step, and it is the one to do early rather than "once the system settles." Verification runs on your schedule and surfaces a diff when a note drifts from current sources. The auto-linker finds semantic connections you did not make. The stale checker flags untouched notes on topics you are actively working in. The daily digest gives you a morning brief across recent notes.

**4. Connect it to the AI tools you already use.** This closes the integration gap. The [MCP server](https://scribelet.app/learn/ai/mcp-server) exposes your notes as tools any Model Context Protocol client can call, including Claude Code and Cursor. You ask a question, the model searches your notes by meaning, and answers with citations. Your second brain becomes the context layer for the AI you were already paying for.

**5. Optionally, bring your own key.** Scribelet's AI works out of the box; chat, tag suggestions, and on-demand verification are on the free plan with daily limits. If you would rather route AI through your own provider, [bring your own key](https://scribelet.app/learn/ai/byok) for OpenAI, Anthropic, or Google. Your key is encrypted at rest with AES-256-GCM, your prompts go to the provider you picked, and you control the spend. Skip this if you do not need it.

> One Reddit user got tired of waiting for a product like this and [built a DIY version](https://github.com/arnaldo-delisio/mindstone) from Obsidian, Supabase, vector embeddings, and a homebrewed MCP server. The post is still circulating on r/PKMS. When the audience is building it themselves, that tells you what the gap looks like from the user side.

## The cadence that survives a skipped week

Standard PKM advice tells you to run a 30-minute weekly review. It is solid advice, and most weekly reviews collapse around week three anyway. Life gets busy, you skip a Sunday, the inbox piles up, and restarting feels worse than starting over.

The fix is not more discipline. It is a system that holds its shape during the weeks you skip.

When the background agents are running, most of the maintenance happens whether you are at your desk or not. Verification catches the API change the day it ships. The auto-linker connects the new note to the old one without waiting for your review. Stale flags accumulate quietly until you have a few minutes to triage them.

What is left for you weekly is small: scan the digest, accept or dismiss the diffs, capture anything you missed. Twenty minutes if you do it on time. You come back from a skipped week to a slightly larger inbox rather than to a graveyard.

## When this is not the right fit

An AI second brain is not the right answer for every kind of note-taking, and pretending otherwise is the marketing posture that earned this category its skepticism.

If your notes are pure journaling, daily reflection without external references, there is nothing to verify. No facts point outward, so the maintenance layer has no work to do.

If you are using notes for therapy, processing, or genuinely private writing, you may not want AI in the loop at all. That is a legitimate choice, and notes can be excluded from AI processing entirely.

If you have fewer than 50 notes, you do not have a maintenance problem yet. You have a capture problem. The setup above is fine to start, but most of the value compounds after a few hundred notes, so do not optimise for a scale you have not reached.

And if you enjoy configuring systems more than writing in them, no tool fixes that. The system is a means, not an end.

## Your next 30 minutes

1. Pick the use case where staleness has actually cost you something: drifting technical docs, client research, notes from a course you took last year.
2. Create one desk and bring in five existing notes that fit it.
3. Run a verification pass on those five and read the diffs. Most people find at least one inaccuracy in their top five notes. That is the maintenance gap, made concrete on your own material.
4. Turn on the daily digest. The first one arrives the next morning.
5. Connect the MCP server to whichever AI tool you already have open all day.

Half an hour of work, and you have a system you can grow into rather than one you will rebuild next year.

A second brain is not a filing system. It is something that thinks with you, and that only works if what is inside it stays true and the AI you use can actually reach it.

[Set up your first desk](https://scribelet.app/learn/getting-started/quick-start) and see what an AI second brain looks like when the maintenance is built in.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>second-brain</category>
            <category>ai</category>
            <category>pkm</category>
            <category>note-taking</category>
            <category>methodology</category>
            <category>knowledge-management</category>
            <category>byok</category>
        </item>
        <item>
            <title><![CDATA[Architecture decision record examples: 10 real ADRs + template]]></title>
            <link>https://scribelet.app/blog/architecture-decision-record-examples</link>
            <guid isPermaLink="false">https://scribelet.app/blog/architecture-decision-record-examples</guid>
            <pubDate>Wed, 29 Apr 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Copy a working ADR template, compare the Nygard, MADR, and Y-statement formats, study 10 architecture decision record examples from real repositories, and learn the maintenance patterns that keep ADRs accurate.]]></description>
            <content:encoded><![CDATA[
You're new on a team and you find a folder called `doc/adr/`. Inside: 47 numbered Markdown files, the oldest from 2019, the newest from 2022. The eighth one explains, in confident prose, why the team picked PostgreSQL over MongoDB. The current code, you find out the next morning, runs on DynamoDB.

Nobody superseded the ADR. Nobody deleted it. It just sits there, looking authoritative, contradicting the codebase silently.

This is the state of most architecture decision record directories in production. Tutorials show clean Nygard-style templates and one polished example. Real repositories show supersession links nobody updated, ADRs orphaned by authors who left two years ago, and entries marked "Accepted" that the team quietly stopped following. The same rot lands on every artifact a repository carries, down to [the issue template](https://scribelet.app/blog/github-issue-template) that still lists a platform the project dropped support for two releases back.

This article gives you an architecture decision record template you can copy today, two fully worked ADR examples including the superseded pair almost nobody publishes, and 10 real decision records from open-source projects worth studying. Then it names the patterns that separate the alive from the rotted. The format is the easy part. The maintenance discipline is what makes [a running decision log](/blog/decision-log) worth reading.

## What is an architecture decision record?

An architecture decision record (ADR) is a short Markdown document, usually one page, that captures a single architectural decision: the context that forced the choice (often [the org structure itself, per Conway's law](https://scribelet.app/blog/conways-law)), the options considered, the choice made, and the consequences. ADRs [live in the source repository alongside the code](https://scribelet.app/blog/docs-as-code), are numbered sequentially, and are never edited after acceptance. To change a decision, you write a new ADR that supersedes the old one.

Michael Nygard popularized the format in 2011. The concept of decision logs predates him; the lightweight Markdown form is his contribution. Today the term covers a family of formats: MADR, Y-statement, Tyree-Akerman, arc42, and the loose conventions most teams build for themselves.

An ADR is deliberately narrower than a [software design document](https://scribelet.app/blog/software-design-document). A design doc proposes an entire system before it exists and stops being true at merge; an ADR records one choice and stays valid long after the system around it has been rewritten. That difference in scope is why the "alternatives considered" section of a retiring design doc belongs in an ADR rather than the wiki. It is also why a recorded decision is the cheapest guard against [a rejected feature quietly creeping back](https://scribelet.app/blog/feature-creep): the reasoning survives the person who made the call.

![Architecture decision record lifecycle diagram showing transitions from Proposed to Accepted or Rejected, and from Accepted to Superseded with bidirectional cross-links to the new ADR](/blog/architecture-decision-record-examples/adr-lifecycle.svg)

## Architecture decision record template

Most ADR templates you'll find stop at Context, Decision, and Consequences. Those three fields record what you decided. They record nothing about when the decision stops being true, which is the failure this whole article is about.

The template below adds four maintenance fields to the standard Nygard structure. Copy it as `doc/adr/NNNN-short-title.md`.

```markdown
# ADR-014: Use Stripe Billing for subscription invoicing

**Status:** Accepted
**Date:** 2026-03-11
**Owner:** D. Lee
**Last verified:** 2026-07-02 by D. Lee, method: re-read Stripe pricing page and re-ran billing integration tests
**External dependencies:** Stripe Billing API v2, Stripe pricing tier (0.5% on recurring), EU SCA regulations
**Drift triggers:** Stripe deprecates the v2 webhook signature, Stripe raises the recurring fee above 0.8%, our MRR exceeds $2M (renegotiation threshold), we need invoicing in a country Stripe does not serve

## Context

We bill roughly 4,000 monthly subscriptions across 14 currencies. Our
current hand-rolled invoicing runs on a cron job that reconciles against
Postgres, and it has produced three billing incidents in two quarters.
We need dunning, proration, tax handling, and SCA compliance, none of
which we want to own.

## Decision

We will use Stripe Billing for all recurring subscription invoicing.
Our system remains the source of truth for entitlement; Stripe is the
source of truth for money.

## Alternatives considered

- **Chargebee:** Better multi-gateway support, but adds a second vendor
  on top of Stripe, which we already use for payments.
- **Keep building in-house:** Rejected. Tax and SCA compliance alone is
  a standing headcount cost we cannot justify at our size.

## Consequences

- **Positive:** Dunning, proration, and SCA stop being our problem.
- **Positive:** One vendor for payments and billing, one reconciliation path.
- **Negative:** 0.5% of recurring revenue leaves as vendor fee.
- **Negative:** Entitlement logic now spans two systems and must stay in sync.
- **Negative:** Migrating off Stripe later means migrating billing history.
```

Two fields do most of the work. `Last verified` is deliberately separate from `Date`: every tool already shows you when a file was last edited, and last edited tells you nothing about whether anyone checked that the content is still true. `Drift triggers` are written while you still remember which parts of the world the decision leans on. Reconstructing them a year later is guesswork, which is exactly the situation [Chesterton's fence](/blog/chestertons-fence) describes: someone finds the decision, can't tell if the reasoning still holds, and has to choose between trusting it blind and tearing it out blind.

### Copy-paste ADR templates: MADR, minimal Nygard, and Y-statement

The template above is the one to adopt if you want maintenance built in. If you only need a standard starting point to drop into `doc/adr/`, here are the three formats teams reach for most, shortest first. Copy any of them and add the two maintenance lines afterward.

Minimal Nygard is the smallest record that still captures the "why":

```markdown
# ADR-NNNN: <short title of the decision>

**Status:** Proposed | Accepted | Superseded by ADR-XXXX
**Date:** YYYY-MM-DD

## Context
<the forces and constraints that make this decision necessary>

## Decision
<the choice, in one or two sentences, and why it wins>

## Consequences
<what gets easier, what gets harder, what you now have to live with>
```

MADR (Markdown Any Decision Records) adds the alternatives and the drivers to the page, so the record shows the options you weighed, not only the one you picked:

```markdown
# <short title of the problem and the chosen solution>

**Status:** proposed | accepted | rejected | superseded
**Date:** YYYY-MM-DD when the decision was last updated

## Context and problem statement
<what is the motivation, what is the disagreement>

## Decision drivers
- <driver 1: a constraint or a non-functional requirement>
- <driver 2: cost, team skill, tech-stack fit>

## Considered options
- <option 1>
- <option 2>

## Decision outcome
Chosen: "<option 1>", because <the justification and the trade-offs you accepted>.

### Consequences
- Good, because <positive impact>
- Bad, because <negative impact>
```

The Y-statement compresses the whole record into one sentence, for a decision small enough to live in a pull request or a chat thread:

```
In the context of <use case>, facing <concern>, we decided <option>,
to achieve <quality>, accepting <downside>.
```

Whichever you copy, paste the `Last verified` and `Drift triggers` lines from the maintenance template above underneath it. The format decides how you write the decision down; those two fields are the only part of any ADR template that tells you when to stop trusting the decision.

## What a superseded architecture decision record looks like

The single most common defect in real ADR directories is a decision that was reversed without anyone writing it down. The old record still reads "Accepted." Here is the other half of the pair, the record that retires the one above.

```markdown
# ADR-027: Move subscription invoicing to Paddle (merchant of record)

**Status:** Accepted
**Supersedes:** ADR-014 (Use Stripe Billing for subscription invoicing)
**Date:** 2026-06-24
**Owner:** D. Lee
**Last verified:** 2026-06-24 by D. Lee, method: signed contract, ran parallel billing for one cycle
**External dependencies:** Paddle merchant-of-record agreement, EU and UK VAT registration thresholds
**Drift triggers:** Paddle's fee exceeds 5%, we incorporate an entity in the EU (which removes the MOR advantage), Paddle drops support for a currency we sell in

## Context

ADR-014 chose Stripe Billing and was correct for the constraints of the
time. One of its named drift triggers fired: expanding into the EU put
us over the VAT registration threshold in four countries. Stripe Billing
leaves us as the merchant of record, so that filing burden is ours.

## Decision

We will move recurring invoicing to Paddle and operate under its
merchant-of-record model. Stripe remains in place for one-off payments.

## Consequences

- **Positive:** Paddle files VAT as merchant of record. Four registrations avoided.
- **Negative:** Paddle's effective rate is roughly 5%, against Stripe's 0.5% plus our filing cost.
- **Negative:** Less control over the checkout surface and the dunning schedule.
```

Notice what the pair gives a reader that a single record cannot. ADR-014 was not wrong; a condition it named in advance came true. The new engineer reading both learns the current state and the reasoning that moved it, in about ninety seconds. Then update ADR-014's header to `**Status:** Superseded by ADR-027` so the link points both ways. Most teams update one side and forget the other, which is how a reversed decision keeps looking authoritative.

## ADR formats: Nygard, MADR, and Y-statement compared

The template above is Nygard's structure, extended. It is the most common ADR format, but it is not the only one, and the right format depends on how much structure your team will actually keep current. Four formats cover almost every architecture decision record you will meet in the wild.

| Format | What it adds | Best for |
|---|---|---|
| **Nygard** | Title, Status, Context, Decision, Consequences. The base. | The default. Teams that want the least structure that still records the "why". |
| **MADR** (Markdown Any Decision Records) | Considered Options with per-option pros and cons, plus Decision Drivers and a Decision Outcome. | Teams that want the alternatives weighed on the page, not just named. |
| **Y-statement** | One sentence: "In the context of X, facing Y, we decided Z, to achieve W, accepting V". | Recording a decision inline in a pull request or a chat thread when a full file is overkill. |
| **Tyree-Akerman** | Assumptions, Constraints, Positions, Argument, Implications, Related decisions. | Regulated or high-stakes systems where the full argument has to be auditable. |

Pick the lightest format your team will keep current. A Nygard record somebody updates beats a Tyree-Akerman record nobody re-reads. Whichever you choose, the one addition worth making is the maintenance block from the template above: the format decides how you write the decision down, but nothing in any of these standard formats tells you when the decision stops being true.

For a decision small enough to live in a single sentence, the Y-statement is the whole record:

```
In the context of subscription invoicing, facing EU VAT registration
thresholds, we decided to move to Paddle as merchant of record, to avoid
filing VAT in four countries, accepting a fee near 5% against Stripe's 0.5%.
```

That is the same ADR-027 decision from the superseded pair above, compressed to one line. Use the long form when the alternatives need room to breathe; use the Y-statement when the decision is real but the argument is short. Both are architecture decision records; they differ only in how much of the reasoning survives in writing.

## 10 architecture decision record examples worth studying

Every link below was live in April 2026. By the time you read this, some directories may have moved or stopped being updated. That is the point of the article. ADRs decay along with everything else.

### 1. MADR project (the format documenting itself)

The [Markdown Any Decision Records (MADR) project](https://github.com/adr/madr) documents its own format using its own format. Each ADR in the repository follows the template the project recommends. It's the cleanest example of an ADR format eating its own dog food, and a good place to start if you want to see what "good" looks like before customizing.

Worth copying: the dated decision filename pattern (`YYYYMMDD-decision-title.md`) and the explicit "Considered Options" section that lists alternatives with concrete pros and cons.

### 2. Cosmos SDK

The [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) keeps its ADRs under `docs/architecture/`. Sixty-plus numbered records cover everything from gas accounting to module structure. The supersession discipline here is unusually strict: when an ADR is replaced, the old file gets a `Status: Superseded by ADR-NNN` header at the top, and the new ADR cross-references back. Reading the directory in chronological order is a tour of how the architecture evolved over five years.

Worth copying: bidirectional supersession links. Most projects only update one side.

### 3. Spotify Backstage

[Backstage](https://github.com/backstage/backstage), Spotify's developer portal platform, publishes its architecture decisions inside its docs tree. The notable pattern is linking each ADR to the pull request that implemented it. You can read the decision, then click through to the diff that put it into the codebase. This collapses the gap between "we decided X" and "X is actually how the system works now," which is one of the main ways ADRs go stale.

### 4. EdgeX Foundry

[EdgeX Foundry](https://github.com/edgexfoundry/edgex-docs), an open-source IoT platform under the Linux Foundation, publishes its ADRs in `edgex-docs`. The template borrows from arc42 and includes a dedicated "Risks and Technical Debt" section that most ADR formats leave out. Useful precedent for any team operating in a regulated or mission-critical context.

### 5. adr-tools (Nat Pryce)

Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools) is a command-line utility for managing ADRs in git. The tool's own ADRs live in `doc/adr/` in the same repository. The directory is small (under 10 records), but the early entries explain why the tool exists and the CLI conventions it picked. You can read the entire decision history in 20 minutes; there is no faster way to internalize the format.

### 6. Kubernetes Enhancement Proposals (KEPs)

Strictly speaking, [KEPs](https://github.com/kubernetes/enhancements) aren't ADRs. They're heavier process documents with explicit lifecycle states (provisional, implementable, implemented, deferred, rejected, withdrawn, replaced). But the lifecycle model is exactly what teams whose ADRs go stale need to copy. Every KEP has an owner, a sponsor SIG, and a graduation criteria checklist. Drift is hard without somebody actively neglecting an assigned record.

### 7. Apache Kafka Improvement Proposals (KIPs)

Kafka's [KIPs](https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals) predate the modern ADR movement and are heavier still. Over a thousand KIPs have been filed across a decade. Several hundred have been formally superseded. For any team that worries supersession discipline cannot scale, the Kafka KIP index is the rebuttal.

### 8. React RFCs

The [React RFCs repository](https://github.com/reactjs/rfcs) sits between an ADR and a design document. The RFCs are public, debated in the open through GitHub discussions, and remain useful long after a decision is made because the discussion thread captures dissent and alternatives the final decision did not adopt. ADRs are usually written in private; React's are written in public, which makes them an unusually rich teaching example.

Capturing dissent is also the test for the document that comes before the decision. A plan earns its review by [making claims a reviewer can disagree with](https://scribelet.app/blog/technical-spec), and the alternatives it rejects are exactly what the ADR inherits once the argument is settled.

### 9. Joelparkerhenderson template gallery

Joel Parker Henderson's [architecture-decision-record repository](https://github.com/joelparkerhenderson/architecture-decision-record) is the most-starred ADR resource on GitHub (15.7k stars at last count) and the place most teams find their first template. It's a gallery of formats rather than a maintained ADR log: useful as a comparison tool, less useful as a study in maintenance discipline.

### 10. arc42

[arc42](https://arc42.org) is a documentation methodology that integrates ADRs as one component of a broader architecture documentation structure. Worth studying if you want decision records that link cleanly to other architecture artifacts (quality scenarios, system context, building blocks) rather than living in isolation. The cost is more upfront structure; the benefit is that an ADR is never an orphan document.

## Three patterns that separate living architecture decision records from dead ones

After reading enough ADR directories, the pattern of decay becomes predictable. Three signals consistently separate the directories teams still trust from the ones they have learned to ignore.

![Side-by-side comparison of a decayed ADR with no owner, no supersession link, and no drift triggers, alongside the same record rebuilt with the maintenance fields a healthy decision log uses](/blog/architecture-decision-record-examples/decayed-vs-alive-adr.svg)

### Explicit ownership on every record

The healthiest ADR directories name a person, not "the team." When the inevitable question comes up two years later ("Why did we pick gRPC?"), an unowned ADR forces the new team into archaeology. An ADR with `Owner: D. Lee` next to its status field gives them a starting point. Cosmos SDK does this. Backstage does this. The directories that don't tend to drift.

### Supersession links that point both ways

The Nygard convention is to mark an old ADR `Superseded by ADR-NNN` and add a `Supersedes ADR-MMM` reference on the new one. Most teams update one side and forget the other. Reading old ADRs without forward references is one of the fastest ways to act on a decision the team has already reversed. The Cosmos SDK convention of always updating both files is small, mechanical, and one of the clearest signals of a maintained directory.

### Named drift triggers

A decision based on external constraints (vendor pricing, framework version, regulatory requirement) decays the moment those constraints change. The strongest ADRs name the trigger explicitly: "Reconsider this decision if Stripe deprecates the v2 webhook signature, AWS publishes a managed alternative, or transaction volume exceeds 10M per month." Without a named trigger, an ADR has no condition under which to expire. With one, anyone reviewing it knows what to look for. The technique transfers directly to operational docs, where [a runbook that tells you when it's wrong](https://scribelet.app/blog/runbook) beats one that gets skimmed every quarter.

## How architecture decision records go stale

Three failure modes show up across every directory of more than 30 ADRs.

The first is orphaned ownership. An author leaves the company. Nobody is assigned the records they wrote. The decisions remain "Accepted" forever even after the codebase moves on. This is the most common form of decay and the most preventable: assign new owners during offboarding the way you reassign open pull requests.

The second is missing supersession. A team makes a new decision in a Slack thread, ships it, and never writes the corresponding ADR. The old ADR is silently wrong. Six months later, a new engineer reads it and wastes an afternoon implementing the deprecated approach. The fix is procedural rather than technical: making "did this need a new ADR?" a checklist item in code review. It is one of the few checklist items that earns its place, because no machine can answer it; [what to delete from your pull request template](https://scribelet.app/blog/pull-request-template) covers the ones that don't.

The third, hardest to catch, is hidden external dependency drift. The ADR was written when AWS Lambda's cold-start penalty was a multi-second concern. AWS has since published Provisioned Concurrency and runtime improvements that bring typical cold starts well under a second. The ADR, which used cold-start penalty as a major reason to avoid Lambda, is now built on outdated cost-benefit assumptions. The decision may still be right, but the rationale has rotted. This is the kind of drift that hand audits rarely catch. It's the engineering-specific case of the broader [knowledge decay](https://scribelet.app/blog/knowledge-decay) problem and the central pattern in [outdated documentation](https://scribelet.app/blog/outdated-documentation) of every kind.

## Maintenance patterns worth copying

Five patterns appear across the well-maintained examples above. Each takes minutes to add and pays back over years.

1. A `Last verified:` date in every ADR header, separate from the original `Date:` field. Tells future readers when the rationale was last sanity-checked, not just when the decision was made. It is the same distinction that decides whether [internal documentation stays trustworthy](https://scribelet.app/blog/internal-documentation): every tool shows you last edited, and last edited says nothing about accuracy.
2. An `Owner:` field with a single name. "The team" is not an owner; nobody on a team will feel personally responsible for a record assigned to all of them.
3. An `External dependencies:` block listing every vendor, framework version, or regulatory document the decision depends on. Makes drift triggers explicit instead of implied.
4. A scheduled review cadence. Quarterly for ADRs that touch external APIs; annually for ADRs about internal architecture. Add it to the same calendar as your dependency updates.
5. Supersession-only edits. Once an ADR is accepted, the only acceptable change is a new ADR that supersedes it (with both files cross-linking). Silent edits hide history; they don't preserve it.

## Tools for managing architecture decision records

You do not need tooling to keep ADRs. A `doc/adr/` folder and a numbering convention is enough, and several of the examples above run exactly that way. But three small tools remove the friction that makes teams stop writing records at all.

- **adr-tools** (Nat Pryce's CLI, linked in example 5 above): `adr new "Use Paddle for invoicing"` creates the next-numbered file from a template and `adr link` wires up a supersession. Shell-based, no runtime, works anywhere git does.
- **[Log4brains](https://github.com/thomvaill/log4brains)**: turns a `doc/adr/` directory into a searchable static site with a timeline view, so the decision log is browsable outside the repository. Useful once a directory passes 30 records and reading raw files gets slow.
- **MADR tooling** (adr-manager and the MADR CLI): scaffolds and edits records in the MADR format, for teams that adopt its heavier structure and want the fields filled in consistently.

Every one of these solves creation, numbering, and linking. None of them solves maintenance, which is the failure this article keeps returning to: a tool can generate a record and cross-link a supersession, but only a person, or an agent watching the repository, notices that a two-year-old decision has quietly stopped matching the code.

## AI agents as fitness functions for architecture decision records

Joel Parker Henderson's repository has a section on "fitness functions for decisions as code": automated checks that verify a decision is still being followed in the codebase. The original idea is structural; you write a unit test that asserts an architectural rule (`ArchUnit` for Java, `dependency-cruiser` for JavaScript, similar tools for other stacks).

The pattern extends naturally to maintenance. An ADR's external assumptions (a vendor pricing tier, a framework version, a regulatory line) can be background-checked. Scribelet's [verification feature](https://scribelet.app/learn/ai/ai-verification) does this for Markdown notes generally: background agents periodically search the web, compare findings to what you wrote, and surface a diff when they drift apart. Applied to an ADR, an agent can flag when current AWS Lambda documentation contradicts the cold-start numbers cited in your three-year-old serverless decision. The same shift shows up one step earlier, in the move to [writing a spec your agent builds from](https://scribelet.app/blog/spec-driven-development) rather than prompting and correcting after the fact.

The harder case is ADRs that describe your own system rather than external dependencies. Web search cannot see whether your code still matches the decision; only the repository can. Scribelet's [GitHub connector](https://scribelet.app/learn/ai/github-connector) plugs that gap by letting verification search a connected repository through GitHub's Code Search API. The PostgreSQL ADR from this article's opening is exactly the case it was built for: the moment somebody pushes DynamoDB code that contradicts the record, the agent has both halves in front of it.

The agent doesn't make the decision. It surfaces the drift. A human still owns the call to supersede the ADR or update the rationale. If you use Scribelet for this on a [Pro plan](https://scribelet.app/pricing), you can route the verification through your own AI provider via [BYOK (Bring Your Own Key)](https://scribelet.app/learn/ai/byok): your data goes to OpenAI, Anthropic, or Gemini directly, with your key encrypted at rest.

## Frequently asked questions

### What's the difference between an ADR and an RFC?

An RFC (Request for Comments) is a proposal under discussion; an ADR is a decision after discussion has closed. RFCs are debated, edited, and may be withdrawn. ADRs are accepted or rejected, then frozen. Some projects (React, Rust) use RFCs because they want public deliberation as part of the artifact. Most internal teams use ADRs because they want a clear closed record.

### How long should an architecture decision record be?

One page, ideally. Martin Fowler's recommendation is to follow the inverted-pyramid style of news writing: the decision and rationale go first, supporting detail goes later. If a decision needs more than a page to explain, link to a separate design document and keep the ADR itself summary-form.

### Who should write the ADR?

Whoever is closest to the decision: the engineer who proposed it or the architect who made the call. Not a designated documentation owner separated from the work. ADRs written by people removed from the decision read as procedure and tend to omit the rationale that makes the record useful later.

### Should accepted ADRs be edited or superseded?

Superseded. Once accepted, an ADR is part of the historical record. Editing it loses the trail of what the team actually believed at the time. Supersession preserves both the original decision and the reason it changed.

### Where should architecture decision records live?

In the source repository, alongside the code they describe. The conventional location is `doc/adr/` or `docs/architecture/`. ADRs that span multiple repositories (cross-team or cross-product decisions) live in a shared docs repo or wiki. Everyone who looks at the affected code should be one click away from the relevant ADRs.

### What is the standard ADR format?

There is no single standard, but Michael Nygard's format (Title, Status, Context, Decision, Consequences) is the de facto default and the base for most others. MADR extends it with explicit options and decision drivers; the Y-statement compresses a decision to one sentence; Tyree-Akerman adds a full auditable argument. Pick the lightest one your team will keep current, then add a maintenance block so the record carries an expiry condition. The same one-line record settles the trivial rules too, the naming convention or the indent width that [reignites the same argument every few months](/blog/sayres-law) once the reason behind it is forgotten.

### What tools help manage ADRs?

Most teams need nothing beyond a `doc/adr/` folder and a numbering convention. adr-tools (a shell CLI) automates creation and supersession links; Log4brains renders a directory into a browsable static site; MADR's tooling scaffolds records in that format. All three handle creation and numbering. None handles the harder problem of noticing when an accepted decision no longer matches the code.

## Conclusion

The format is the easy part. Anyone can copy a Nygard template and write three good ADRs in an afternoon. The directories that still serve their team five years later have something the template alone does not provide: an owner on every record, supersession links that point both ways, named drift triggers, and a review cadence somebody actually keeps.

The decision is half the work. Watching it for drift is the other half.

An ADR is the format for architectural decisions specifically. For the everyday calls a team makes outside the codebase, the same discipline runs through a general [decision-making framework and a written decision record](/blog/decision-making-framework): pick the method that fits the decision, then keep the reasoning where it can be re-checked.

[Start writing with background verification. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>architecture-decision-records</category>
            <category>adr-template</category>
            <category>technical-documentation</category>
            <category>software-architecture</category>
            <category>engineering</category>
            <category>documentation</category>
            <category>knowledge-decay</category>
        </item>
        <item>
            <title><![CDATA[Outdated documentation: causes, costs, and a fix plan]]></title>
            <link>https://scribelet.app/blog/outdated-documentation</link>
            <guid isPermaLink="false">https://scribelet.app/blog/outdated-documentation</guid>
            <pubDate>Thu, 16 Apr 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Why engineering docs go stale, what docs-as-code still misses, and a practical 30-day plan for finding and fixing outdated documentation.]]></description>
            <content:encoded><![CDATA[
You wrote that integration guide eight months ago. The auth flow you documented uses an OAuth scope that was deprecated last quarter. You don't know yet, and neither does the new engineer who's about to follow it.

This is the part of engineering nobody plans for. We have rituals for shipping code, postmortems for outages, retrospectives for sprints, even [planning meetings where we pad the estimate](/blog/hofstadters-law) and still run late. We have nothing for the slow rot of documentation that started accurate and quietly stopped being so.

Most teams have stopped trying. The PR checkbox that says "docs updated" gets ticked because nobody wants to block the merge. The quarterly review never happens because there's never a quarter without a fire. The wiki accumulates pages that are half wrong in ways nobody knows about. A doc that misleads you is [ordinary neglect, not a trap anyone set](/blog/hanlons-razor).

This article covers where outdated documentation actually comes from, what current tooling catches and misses, and a thirty-day plan for getting rot under control. The interesting part is what's newly possible since 2024: an AI agent that reads your doc, identifies the external claims you made, and tells you when they no longer hold. The newest document in this category is the one you write for the AI itself: a [spec that drives your coding agent](https://scribelet.app/blog/spec-driven-development) drifts from the code the same way any doc does, only faster.

## The half-life of a developer doc

alex_c on Hacker News named this problem [in 2011](https://news.ycombinator.com/item?id=3158990): "Documentation rot is one of the most annoying things when trying to learn a new technology." Fifteen years later, it's worse. There are more frameworks shipping breaking changes more often, more API surfaces to track, and more layers of obsolete information that complicate even searching for the right answer.

Different docs decay at different speeds. Reference documentation (API signatures, schema definitions, integration guides) decays fastest. A dependency ships v6, your guide still teaches v5 patterns, and the gap between what your doc says and [what the code does](/blog/self-documenting-code) grows every Tuesday release.

Architecture documentation decays more slowly but more catastrophically. The reasoning gets lost; the decisions remain in effect; nobody remembers why. It happens to decisions of every kind, not just architectural ones: [the framework that produced a choice](/blog/decision-making-framework) is worthless a year on if the reasoning behind it was never written down. And [the second-order consequences you thought through](/blog/second-order-thinking) at the time are the first part of that reasoning to vanish, because they were always a prediction rather than a fact.

The cost is rarely measured by debugging hours. It's measured by interruption. One engineer on r/softwaredevelopment [puts it bluntly](https://www.reddit.com/r/softwaredevelopment/comments/1k65vup/how_much_does_outdated_documentation_hurt_your/): "Our team spends 2+ hours weekly per engineer answering PMs, non-tech stakeholders, and managers about how systems work." That's the real expense. Outdated docs pull experienced engineers out of flow to re-explain what the docs were supposed to answer.

The phenomenon also has a measurement problem. A 2023 paper, ["Detecting Outdated Software Documentation"](https://arxiv.org/abs/2307.04291), proposes automated approaches because manual detection doesn't scale at the rate documentation drifts. None of the major note and wiki tools have implemented those approaches. This is documentation-flavored [knowledge decay](https://scribelet.app/blog/knowledge-decay), and it has the same root cause: information has a half-life, and our tools don't account for it.

## Why "documentation as code" wasn't enough

The "docs near code" pattern (storing markdown alongside the source it describes, reviewing it in PRs, versioning it in git) was supposed to solve this. It didn't. Most teams that adopted [the docs as code workflow](https://scribelet.app/blog/docs-as-code) now have well-organized markdown files that are still wrong. The same trap catches personal notes, which is why we sorted the [markdown note-taking apps that still let notes go stale](https://scribelet.app/blog/markdown-note-taking-apps) from the ones that do something about it.

The mechanics worked. The accountability didn't. A typical setup adds a PR checkbox: "documentation updated as part of this change." On r/ExperiencedDevs, one engineer [described what every team that's tried this knows](https://www.reddit.com/r/ExperiencedDevs/comments/1nebg0u/how_do_you_guys_keep_documentation_up_to_date_on/): "My team has a checkbox when we do PR's where the reviewer checks to see if documentation has been updated as part of the PR. That hasn't worked super well, though."

The reasons are obvious in retrospect. The reviewer doesn't always have the domain context to know whether the docs needed updating. The checkbox gets ticked under sprint pressure because nobody wants to block the merge over docs.

And the largest source of rot isn't even from the team's own changes. It's from upstream. A dependency you didn't touch shipped a breaking change last week, and the doc that referenced its API is now stale through no PR of yours.

Docs-as-code makes documentation maintainable in principle. It doesn't make documentation accurate in practice. It moves the problem from "where does the doc live" to "who is going to actually read this against current reality." That second question is where most systems quietly fail.

## Three patterns of doc rot

Stale documentation tends to fall into three patterns. Each has a different failure mode and a different fix.

### Drift: the source of truth moved

The doc was right when you wrote it. Then the underlying system changed quietly, and the doc didn't.

A common form: an OAuth scope you used got renamed. Your code still works because someone migrated it during an unrelated PR. The doc still references the old scope. The next engineer follows your guide, hits a 403, and spends an afternoon retracing the logic before realizing the doc is wrong.

The drift is small per change, but it compounds. After six months, the doc and the code are describing different products.

Some documents drift on a schedule you can predict. A design doc is written before the system exists, gets changed by its own review, and describes something nobody built by the time the branch merges, which is why it needs [a template with an expiry date built into it](https://scribelet.app/blog/software-design-document) rather than a calendar reminder.

The same trick works one step earlier, on the plan itself. [A technical spec template you can copy](https://scribelet.app/blog/technical-spec) carries a last-true-on date separate from last-edited, so the document reports its own drift instead of hiding it behind a typo fix.

Drift is the most automatable pattern. It's also the one current tooling catches the worst, because most tools check whether docs got *touched*, not whether they're still *true*.

### Abandonment: nobody owns it anymore

The original author left fourteen months ago. Three teammates have edited the doc since, each fixing one section. Nobody has read the whole doc end-to-end in eighteen months. Half of it is accurate-but-stale, half is wrong, and the doc looks authoritative because of its length and its place in the wiki sidebar.

Abandonment is a culture problem more than a tooling problem. The fix is naming an owner per doc, not per team. "The platform team owns the auth docs" sounds responsible but produces no maintenance. "Aisha owns the OAuth integration guide, with a review-by date in the header" produces maintenance.

That fix comes with an expiry date of its own. Aisha changes teams, the header still says Aisha, and the review-by date passes without anyone noticing, which is the trap we pulled apart in [nobody owns the second draft](https://scribelet.app/blog/internal-documentation).

### Context loss: the why is gone

An [architecture decision record](https://martinfowler.com/articles/scaling-architecture-conversationally.html) from 2023 explains a queue choice. The constraint that drove the decision (a vendor SLA that no longer applies) has lapsed. The decision is technically still in effect because nothing rescinded it, but the reasoning has decayed into folklore. New engineers inherit the choice without inheriting the conditions that made it right.

Context loss is the most insidious because the doc still reads as accurate. The fact didn't change; the world around it did. Detecting context loss requires a model of *why* the doc says what it says, not just *what* it says.

That's where automated detection has historically given up. It's also, increasingly, where AI-driven semantic verification can step in.

## What current tooling misses about outdated documentation

Most engineering teams use some combination of the following tools for documentation hygiene. Each catches a slice of rot. Together, they miss most of it.

| Tool | What it catches | What it misses |
|---|---|---|
| Link checkers (htmltest, lychee) | Dead URLs and broken anchors | Anything substantive (the link works; the page it points to has changed) |
| Screenshot diff tools (Chromatic, Percy) | UI changes that affect screenshots | Behavioral and API changes that don't affect the UI |
| "Docs touched" CI checks | Code changes that don't update docs | Doc rot from upstream changes you didn't touch |
| Doc-as-code review processes | New docs that ship inconsistent with code | Ongoing drift in docs that nobody is editing |

Notice the gap. Every tool above checks whether documentation matches *something we already know is true*: the link resolves, the screenshot matches, the PR included a doc edit, the new doc reads like the surrounding code. None of them check whether the doc's claims are still true *against the world*. None of them notice that an external dependency you reference shipped a breaking change yesterday.

This is the gap the AI-agent layer fills.

## The AI-agent layer: docs that audit themselves

The new option, available since roughly 2024, is automated semantic verification. An AI agent reads your doc, identifies its external claims (an API signature, a recommended library version, a regulatory citation), searches the current web for each, compares findings to the doc, and surfaces a diff. You see what your doc says next to what the source now says, with the source link for verification. You accept the change, dismiss it, or queue it for further review.

Web search closes most of the gap, but not all of it. The doc's claim is sometimes "what our payments service does when this event arrives," and the source of truth for that isn't on the web at all. It's in your repository. The most useful recent extension to this pattern is letting the AI agent search your own code in addition to the web, the same context a [coding agent](https://scribelet.app/blog/agentic-coding) leans on every time it edits your project.

This is what Scribelet's background verification does for technical notes. You set the schedule per note, or let the system prioritize by content age and external-reference density. Background agents run on the cadence you chose.

When they find drift, you see a diff: green for new information, red for what's outdated, with a source link for every change. No vague "this might be stale" warning. A specific "this Stripe webhook event was renamed in API version 2025-08-27, here's the new name and the migration note." Or, if you've connected a [GitHub repository](https://scribelet.app/learn/ai/github-connector), a snippet of your own code showing the function whose behavior diverged from what the doc still says.

> Honest tradeoff: this works best on docs that reference external claims. API references, library guides, regulatory citations, framework documentation. It's less useful for purely internal procedural docs (how your team does code review, your on-call rotation policy) where there's no external "ground truth" to verify against. For those, the older tactics still apply: ownership, schedules, and review reminders.

Sovereignty matters when AI is reading your docs. Bring your own API key (OpenAI, Anthropic, or Gemini) and your data goes to the provider you trust, not the one we chose for you. Keys are encrypted at rest with AES-256-GCM.

We've covered the [BYOK approach](https://scribelet.app/blog/byok-ai) elsewhere. The short version: your model, your costs, your data boundaries.

## A 30-day plan to fix outdated documentation in your repo

If you've read this far, you probably have specific docs in mind that worry you. Here's a four-week plan to get rot under control without committing to a multi-quarter overhaul.

### Week 1: inventory and prioritize

Pick your ten most-trafficked docs. Use page-view analytics if you have them. If you don't, ask the engineering channel: "Which doc do you find yourself referencing most?" The answers come fast.

For each doc, note three things: who wrote it, when it was last edited, and how many external references it contains (APIs, library versions, vendor configurations). High external-reference density and stale last-edit dates are your highest-rot candidates.

### Week 2: establish ownership

Each of the ten docs gets one named owner. Not a team, not a role, a person. Add the owner's name and a "next review by" date directly to the doc header.

If the doc is in markdown, the header is one frontmatter block. If it's in a wiki, it's the first section.

This sounds bureaucratic. It isn't. Without it, "everyone is responsible" turns into "nobody noticed." Naming an owner removes the diffusion-of-responsibility excuse.

### Week 3: instrument detection

Choose your detection layer based on team size and tolerance for setup work.

Lightweight is a calendar reminder per owner per doc. Free, works for ten docs, breaks at fifty.

Middle is a GitHub Action that comments on PRs touching code referenced in `/docs/*.md`. Better than nothing, catches drift from your own commits, misses upstream-driven drift.

Automated is AI verification on a schedule. Reads the entire doc, identifies external claims, diffs them against current sources, and queues findings for human review. Best signal-to-noise at scale, recommended for teams with more than a dozen high-rot docs. This is what a [Scribelet Pro](https://scribelet.app/pricing) plan provides.

### Week 4: close the loop

Run your first review cycle. For each finding the detection layer surfaced, decide: accept the change, dismiss as not applicable, or escalate to the owner for deeper review. Track which docs produced the most findings; those are the ones that need shorter review intervals.

By the end of week four, you have an inventory, owners, a detection signal, and one cycle of evidence about how fast each doc actually rots. That's enough to set sustainable cadences for everything else.

## Frequently asked questions

### Why does documentation get outdated?

Three reasons combine. Reference docs go stale when external systems they describe ship breaking changes (a dependency, an API, a vendor configuration). Architecture docs go stale when the constraints that drove a decision lapse without anyone updating the doc. And process controls (PR checkboxes, [a team's "definition of done"](/blog/definition-of-done)) reliably get skipped under sprint pressure, so even teams that try to maintain docs accumulate drift.

### How often should documentation be reviewed?

It depends on the doc type. Reference documentation (APIs, schemas, integration guides) needs review every 30 days because external surfaces change quarterly at minimum. Architecture documentation can go 90 days unless the underlying system is in active redesign. Internal procedure docs (on-call rotations, code review process) can go annually unless the procedure itself changes, with one exception: anything that names a system. [A pull request template](https://scribelet.app/blog/pull-request-template) that still asks for a Jira ticket number expires the day the team moves to Linear, and [a GitHub issue template](https://scribelet.app/blog/github-issue-template) that auto-assigns a label the team renamed quietly stops triaging anything. Runbooks are the exception to all of this: [runbooks go stale](https://scribelet.app/blog/runbook) on the deploy clock rather than the calendar, so the right trigger is a rename or a moved endpoint, not a date.

### What's the best tool for detecting outdated documentation?

A combination: link checkers for dead URLs, AI verification for external-claim drift, and a named owner per doc for everything tooling can't catch. Tools don't fix culture; they make culture observable. The minimum viable setup is one detection mechanism plus one owner per doc. Add layers as you find specific gaps.

### Should I delete outdated documentation or update it?

If the doc is actively used and the underlying system still exists, update it. If nobody has referenced it in over a year and the system has substantially changed, delete it. Outdated docs are worse than no docs because they erode trust in the rest of your documentation. A wiki where half the pages might be wrong is a wiki nobody uses. A stale runbook is the sharpest case: it looks like it spread the knowledge around when in fact it left [the task's bus factor](/blog/bus-factor) at one, because only the original author knows the page is now wrong.

### Can AI keep documentation up to date automatically?

AI can detect drift and surface diffs against current sources. It cannot decide what to keep or how to phrase the replacement; that's a judgment call your team owns. The right pattern is AI surfaces the question, a human answers it, and the answer ships in the same PR cycle as any other code change.

## Notes that stay alive

Documentation rots whether you're watching or not. The choice is whether you watch.

The tactics in this article (ownership, schedules, tooling, AI verification) work in combination, not in isolation. None of them are silver bullets. All of them are better than the status quo of "we'll review it when there's time." Start with the lightest one you can sustain. Add layers as the gaps reveal themselves.

Try [Scribelet's documentation verification](https://scribelet.app) on your team's most-trafficked doc. See what it catches in five minutes. If nothing turns up, your doc is in better shape than most. If something does, you've already paid for the experiment.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>outdated-documentation</category>
            <category>technical-documentation</category>
            <category>knowledge-decay</category>
            <category>docs-as-code</category>
            <category>ai-verification</category>
            <category>devops</category>
            <category>engineering</category>
        </item>
        <item>
            <title><![CDATA[Two directions for a self-maintaining knowledge base]]></title>
            <link>https://scribelet.app/blog/karpathy-llm-wiki-reaction</link>
            <guid isPermaLink="false">https://scribelet.app/blog/karpathy-llm-wiki-reaction</guid>
            <pubDate>Sat, 11 Apr 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A response to Karpathy's LLM-maintained wiki gist. His pattern points an LLM at compiled external sources. There's another axis worth naming.]]></description>
            <content:encoded><![CDATA[
[Karpathy's gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) on LLM-maintained wikis names something the PKM world has been circling for years: the tedious part of a knowledge base isn't the reading, it's the bookkeeping. His pattern solves it by pointing the LLM at compiled external sources. There's another direction worth naming.

## Two directions, not one

Karpathy's pattern is compiled external knowledge. You curate raw sources (papers, articles, PDFs, transcripts), and the LLM authors and maintains the synthesis on top of them. Entity pages, concept pages, a log.md, a CLAUDE.md that encodes the schema. The LLM is the writer; you're the librarian pointing it at what to read.

There's an inverse shape. You write your own notes (half-formed thoughts, meeting fragments, architecture sketches, what you actually decided on Tuesday), and the LLM maintains *that*. It never authors the first draft. It cross-references, flags contradictions, catches drift, and keeps the graph connected. You're the writer; it's the librarian for the thing you wrote.

Take each pattern to the limit. Karpathy's wiki, scaled to infinity, converges toward a personalized copy of the internet, an ever-more-complete synthesis of what you've read. The inverse, scaled to infinity, converges toward a persistent copy of your own mind, what you've actually thought, kept alive. Genuinely different artifacts. Genuinely different architectures.

## The maintenance loop is the same; the source of truth is not

Both shapes need the same pipeline: ingestion, cross-referencing, contradiction detection, stale flags, synthesis, scheduled health checks. What changes is the authoring layer.

In Karpathy's pattern the LLM authors, so the maintenance loop can be aggressive. If a new source contradicts an entity page, rewrite the page. Better synthesis wins. The prior version had no sentimental value. Nobody wrote it from the inside.

In the inverse pattern the human authors, so the maintenance loop has to be careful. When you care about what *you* think, not what the best available reading of the sources says, the LLM must not overwrite your voice. It maintains *around* you. It surfaces the contradiction; you decide whether you changed your mind or misremembered something. It finds the older note that connects; you decide whether the link belongs. The diff is the interface, not the rewrite.

This is why the tools end up shaped differently even when they share the same loop. If the LLM is the author, you ship a renderer. If the human is the author, you ship an editor with a maintenance layer underneath it.

## Only one of these is a second brain

The PKM crowd will tell you that "second brain" and "personal knowledge management" aren't about having a fast retrieval system for stuff you've read. They're about the act of writing your own words, in your own voice, while the ideas are still metabolizing. Tiago Forte's CODE framework (Capture, Organize, Distill, Express) treats the last two steps as where the value actually lives. Sönke Ahrens's *How to Take Smart Notes* rests on the same claim: writing is thinking. Skip the writing and you skipped the thinking.

By that standard, only the second shape is PKM. Karpathy's pattern builds a personalized research index, and probably the best version of that artifact anyone has proposed. But the LLM is doing the distillation and the expression. Taken seriously as a methodology, "second brain" describes the tool where *you* do the distilling and the expressing, and something else keeps your output from rotting.

This is worth naming because a lot of the reaction to the gist is calling it "Karpathy's second brain." It isn't, in the sense the PKM tradition uses the term. It's a better thing for a different job: queryable external knowledge, not accumulated personal thinking.

## What that looks like as a product

We've been building the inverse shape for about a year. A few concrete pieces, in case the mapping is useful:

Background verification searches the web on a schedule and shows a diff when something you wrote has drifted from reality, the "lint pass for stale claims" applied to user-authored notes instead of ingested sources. Notes go stale the same way compiled sources do; [knowledge decay](https://scribelet.app/blog/knowledge-decay) is the underlying problem, and this is the parallel to the periodic health checks Karpathy describes.

The auto-linker finds the note you wrote six months ago that connects to the one you wrote today, across pages the LLM didn't author. Contradiction detection flags when a new note disagrees with an older one and asks you which version survives, not which the model prefers. Memory extraction pulls the entities you've been thinking about out of your notes and chats and draws the edges between them, building the same kind of graph Karpathy's wiki grows, but seeded from your thinking rather than your sources. Episodic memory is the log.md idea applied to conversations: timestamped summaries you can recall by "when did we talk about X." Procedural memory is the CLAUDE.md idea applied at runtime: rules you write once (`category='procedural'`) and the AI respects on every future turn, injected unconditionally into the system prompt.

None of this is a clone of the gist. No parity claim. Karpathy is describing a pattern a skilled user implements in Claude Code against their own sources, which is a different scope than a product that has to behave reasonably for everyone. Same problem, same shape of loop, different source of truth.

## Which one should you build?

Honest answer: depends on what you're trying to remember. If you're synthesizing a field (catching up on a new research area, compiling what's known about a topic), Karpathy's pattern is probably the right shape, and the gist is a good spec to build against. Budget for the part the spec leaves out, though: [everyone compiles, nobody recompiles](https://scribelet.app/blog/llm-wiki), and the compiled artifact starts drifting from its sources the day after you build it. If you're accumulating your own thinking (decisions, rationales, half-formed ideas, the things you'd forget by Friday), the inverse is probably right, because the authoring layer is the thing you care about and you don't want a model rewriting it.

Most people will want both. Different tools, different jobs. The tools that try to do both usually do neither well, because the aggressive maintenance loop the compiled pattern needs is exactly the loop that eats your voice in the authored pattern.

## Closing

Both shapes are maintenance loops wrapped around different sources of truth. Karpathy's is pointed outward at the world; this other one is pointed inward at your own notes. Most people doing serious knowledge work will end up with something of each: something Karpathy-shaped for the fields they're researching, something else for the thinking they're accumulating.

If you're curious what the inverse pattern looks like as a real product, we've been building it at [Scribelet](https://scribelet.app).
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>llm</category>
            <category>pkm</category>
            <category>knowledge-management</category>
        </item>
        <item>
            <title><![CDATA[BYOK AI: 7 questions to ask before you paste your API key]]></title>
            <link>https://scribelet.app/blog/byok-ai</link>
            <guid isPermaLink="false">https://scribelet.app/blog/byok-ai</guid>
            <pubDate>Sun, 05 Apr 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[BYOK AI means using your own OpenAI, Claude, or Gemini key. What it costs, how apps actually store your key, and the 7 questions to ask before trusting one.]]></description>
            <content:encoded><![CDATA[
In late 2025, Cursor quietly killed its Bring Your Own Key option. Developers who had been running their own API keys for months were funneled onto paid subscriptions. The backlash on forums and social media was immediate, but Cursor held firm. The feature wasn't coming back.

The Cursor incident is worth remembering not because it was unusual, but because it exposed something most users hadn't considered: BYOK is only as reliable as the company offering it. If the business model shifts, your key access can vanish overnight.

Bring your own key AI has moved from a niche developer preference into a mainstream consideration for anyone using AI-powered tools. This article covers what BYOK actually means in the context of AI apps, how the economics of BYOK vs. subscription AI compare, what to look for in a trustworthy implementation, and why BYOK AI privacy matters more for note-taking than for most other categories. By the end, you'll know which questions to ask before handing your API key to any app.

## What is BYOK AI?

BYOK (Bring Your Own Key) in AI means connecting your own API key from providers like OpenAI, Anthropic (Claude), or Google Gemini to a third-party application. Instead of the app bundling AI behind a per-seat subscription, you generate a key with the provider, paste it into the app's settings, and pay based on actual token usage. The app routes your requests through your key. You control the cost, the model, and the data path.

Here's what that looks like in practice.

The term originally comes from enterprise encryption, where BYOK referred to companies managing their own cryptographic keys in cloud services. [IBM's explainer on BYOK](https://www.ibm.com/think/topics/byok) still focuses on that encryption-key context. But since 2024, the meaning has shifted. When most people search for BYOK AI today, they mean API key portability for language models, not HSM key management for cloud storage.

The mechanics are straightforward. You create an account with an AI provider. You generate an API key in their dashboard. You paste that key into the app that wants to use it. When the app needs AI, it sends your request to the provider using your key, and the provider bills your account directly based on how many tokens you consumed.

This is a fundamentally different model from what Notion, Mem, or most AI-powered productivity tools offer. Those tools pay the AI provider on your behalf, wrap the cost into a monthly subscription, and choose which model you get to use. You never see the API key, the per-request cost, or the data routing path.

## Why BYOK is taking over AI tools

Three forces are converging to make BYOK AI the expected default rather than a power-user perk.

The first is subscription fatigue. AI subscription costs add up fast. If you're a knowledge worker in 2026, you might be paying $20/month for ChatGPT Plus, $10/month for an AI writing tool, and $19/month for an AI coding assistant. That's nearly $600/year for tools that all call the same underlying APIs. When Marcus, a freelance developer in Berlin, added up his AI subscriptions last January, the total was $67/month. He switched every tool that supported BYOK to his own OpenAI key. His combined API spend dropped to $11/month for roughly the same usage. The savings aren't theoretical.

The second force is enterprise validation. In December 2025, [JetBrains shipped BYOK support across all its IDEs](https://blog.jetbrains.com/ai/2025/12/bring-your-own-key-byok-is-now-live-in-jetbrains-ides/). A month later, [GitHub expanded Copilot's BYOK to support AWS Bedrock, Google AI Studio, and additional OpenAI-compatible providers](https://github.blog/changelog/2026-01-15-github-copilot-bring-your-own-key-byok-enhancements/). When tools used by millions of professional developers adopt BYOK, it stops being a fringe preference and becomes infrastructure.

The third force is the Cursor backlash. Cursor's BYOK removal proved that "supported" doesn't mean "permanent." The developer community's reaction wasn't just about losing a feature. It was about trust. When you build workflows around a BYOK integration, revoking it feels like a bait-and-switch. The incident surfaced a vendor lock-in risk that didn't exist before: *will this company keep supporting BYOK, or will they pull it once they have enough users?*

Directory sites like BYOKList.com now catalog over 100 BYOK AI apps across categories, from coding assistants to design tools to note-taking apps. The ecosystem has reached the point where bring your own API key support is a competitive differentiator in product listings, right alongside pricing and platform availability.

## The real cost: BYOK vs. AI subscriptions

The cost argument for BYOK is compelling, but it depends on how you use AI. Here's how the math works for a typical knowledge worker.

A ChatGPT Plus subscription costs $20/month for access to GPT-4o, with usage caps. The same model through the API costs roughly $2.50 per million input tokens and $10 per million output tokens. For someone who sends 50 prompts a day averaging 500 tokens each (input and output combined), that's about 750,000 tokens per month. At API rates, that's roughly $3-5/month. The subscription costs four to six times more.

The gap widens for teams. A 10-person team paying $20/seat/month for ChatGPT Team spends $2,400/year. The same team sharing a single API key with usage-based billing might spend $400-600/year total, depending on volume.

But BYOK AI isn't free money. There are real tradeoffs.

You manage your own billing. There's no flat monthly charge. Your bill fluctuates with usage, and a runaway integration or an accidental loop can spike costs fast. Provider dashboards let you set spending caps, but you need to actually configure them.

You handle key rotation and security. If a key leaks, you need to revoke it and generate a new one. Subscription services handle this silently.

Some features require vendor infrastructure. Cursor's stated reason for dropping BYOK was that their custom model routing and caching layer couldn't work with arbitrary keys. Whether you find that argument convincing, the underlying constraint is real: some optimizations depend on controlling the full pipeline.

And for light users, the setup friction isn't worth it. If you use AI once a week, the $20/month subscription is simpler than managing API keys, monitoring dashboards, and understanding token pricing. BYOK rewards consistent, moderate-to-heavy use.

| | Subscription AI | BYOK AI |
|---|---|---|
| Monthly cost (typical user) | $20/mo flat | $3-8/mo usage-based |
| Billing model | Per-seat, predictable | Per-token, variable |
| Model choice | Vendor decides | You decide |
| Data routing | Through vendor's infrastructure | Through your chosen provider |
| Setup effort | Create account, pay | Create account, generate key, configure app |
| Key security | Vendor manages | You manage (unless the app encrypts it) |
| Risk of removal | N/A | Vendor can drop BYOK support |

> Scribelet includes BYOK on every plan, including the free one. You add your own OpenAI, Anthropic, or Gemini key, and AI costs are between you and your provider. Pro is [$8/month or $79/year](https://scribelet.app/pricing) when you want higher system-model limits and the always-on background agents.

## BYOK and data control: where your notes actually go

Cost savings get the headlines, but data control is the stronger argument for BYOK, especially in tools that store sensitive information.

When you use a tool with bundled AI, your data follows a path you don't fully control. Your note content goes from the app's servers to whichever AI provider the company negotiated a deal with. You might not know which provider that is. You almost certainly don't know which model version is processing your text. And the app's privacy policy, not the AI provider's, governs what happens to your data in transit.

With BYOK, the data path is explicit. Your content goes from the app to the provider you chose, using the key you generated, under the terms you agreed to with that provider. You can read OpenAI's data usage policy, Anthropic's, or Google's, and know exactly which one applies. That transparency matters for compliance (GDPR data processing agreements, SOC 2 audit trails) and for peace of mind.

The route matters just as much when the AI is bolted on rather than built in. If you assemble your own stack out of plugins and coding agents, [each route sends a different share of your notes to the model](https://scribelet.app/blog/obsidian-ai), and "runs locally" ends up describing where the plugin sits rather than where your text goes.

But transparency about the *route* isn't enough if the app itself handles your key carelessly. This is where most BYOK articles stop, and where the real differences between implementations begin.

Priya, a healthcare consultant in Toronto, evaluated four BYOK-compatible note apps last fall. Two stored API keys in plaintext in a browser cookie. One encrypted the key but used a single encryption key for all users. Only one encrypted each key with a per-workspace key, wrapped by a managed key service, so that even a database breach wouldn't expose usable credentials. The security difference was invisible from the marketing page. She only found it by asking.

The question isn't just "does this app support BYOK?" It's "what does this app do with my key after I paste it in?"

The same scrutiny belongs on your notes, not only your key. It's worth understanding [what a secure note-taking app actually protects against](https://scribelet.app/blog/secure-note-taking-app) before you trust one, because strong encryption and useful AI pull against each other in ways the marketing rarely admits.

### Seven questions to ask any BYOK app

Before trusting an app with your API key, ask these:

1. Where is my API key stored? Server-side encrypted, server-side plaintext, or local-only?
2. What encryption standard protects it? AES-256-GCM is the current gold standard. Anything less should raise questions.
3. Does the app use a single encryption key for all users, or per-workspace keys?
4. Does my data pass through the app's servers on the way to the AI provider, or is it routed directly?
5. Can I revoke access instantly by deleting my key from the app?
6. What happens to cached data if I remove my key or delete my account?
7. Has this vendor ever revoked BYOK support?

That last question didn't used to matter. After Cursor, it does.

## Why BYOK matters more for notes than for chat

Most BYOK AI discussion focuses on coding assistants and chat interfaces. But the case for BYOK is actually stronger in note-taking and knowledge management, for reasons that don't apply to ephemeral AI conversations.

Notes accumulate. A chat with Claude will not be easy to find later on. But your notes persist for months or years, and the information in them [silently goes stale](https://scribelet.app/blog/knowledge-decay). They contain project plans, client research, technical documentation, personal reflections. The sensitivity of that data compounds over time. A year of notes is a more complete picture of your professional life than any single conversation.

Notes get maintained by AI. In tools with background AI features, your notes aren't just stored. They're read, analyzed, compared against web sources, cross-referenced with other notes, and used to build context for future conversations. That's a deeper level of data processing than a one-off chat prompt. If you don't control which AI provider processes that data, you're trusting a vendor's choice with your entire knowledge base. The same question applies to the standing instructions wrapped around every one of those requests, because [what belongs in a system prompt](https://scribelet.app/blog/system-prompt) is somebody's decision, and in most tools it is not yours.

Notes are shared. Team desks, shared workspaces, collaborative wikis. When AI processes shared notes, every team member's data is affected by the BYOK decision. One team's API key choice determines the data path for everyone in the workspace.

This is why the BYOK AI note-taking landscape splits so cleanly.

Obsidian keeps everything local. No cloud AI, no BYOK question. But you also don't get AI verification, auto-linking, or chat that understands your notes. You trade AI capability for total isolation.

Notion bundles its AI. You get powerful features, but Notion chooses the provider and the model. There's no way to route your data through your own key. For teams in regulated industries, that's a blocker.

Mem, Reflect, and most other AI-native note apps fall somewhere in between, with varying levels of model choice but no full BYOK where you control the key, the billing, and the provider for every AI feature.

[Scribelet](https://scribelet.app) takes a different position. BYOK spans every AI feature: chat, verification, voice transcription structuring, background tasks, memory extraction. You add your OpenAI, Anthropic, or Gemini key in desk settings, and every AI request routes through it. All keys get encryption at rest with AES-256-GCM using per-desk Data Encryption Keys, wrapped by a Key Encryption Key through AWS KMS. Even if someone breached the database, the keys would be ciphertext without the KMS layer. This isn't a feature checkbox. It's an architecture decision about where trust lives.

| Feature | Scribelet | Notion | Obsidian | Mem | Reflect |
|---|---|---|---|---|---|
| BYOK support | Full (OpenAI, Anthropic, Gemini) | None | No native AI | None | Partial (OpenAI key only) |
| Key encryption | AES-256-GCM, per-desk keys | N/A | N/A | Unknown | Unknown |
| AI verification | Background agents, scheduled | None | None | None | None |
| AI memory | Per-desk, auto-extracted | None | None | Limited | None |
| Data routing | Direct to your provider | Through Notion's infrastructure | N/A | Through Mem's infrastructure | Through Reflect's infrastructure |

## How to set up BYOK in five minutes

If you've never used an API key before, the process is simpler than it sounds.

**Get your API key.** Go to your provider's dashboard: [platform.openai.com](https://platform.openai.com) for OpenAI, [console.anthropic.com](https://console.anthropic.com) for Anthropic (Claude), or [aistudio.google.com](https://aistudio.google.com) for Gemini. Create an account if you don't have one. Navigate to API keys. Generate a new key. Copy it.

**Add it to your tool.** In Scribelet, open desk settings and paste your key under AI Provider. Choose your preferred model. That's it. AI features are live, powered by your key, billed to your provider account.

**Set a spending cap.** Every major provider lets you configure monthly spending limits. OpenAI's is under Settings > Billing > Usage limits. Set a hard cap at whatever you're comfortable with. $10/month is generous for most individual users. This prevents surprise bills from runaway usage.

Two tips for ongoing management. First, rotate your keys periodically. Every 90 days is a reasonable cadence. Delete the old key, generate a new one, update the app. Second, check your provider's usage dashboard weekly for the first month. You'll quickly develop an intuition for your normal consumption pattern, which makes anomalies obvious.

The entire setup takes less time than filling out a typical SaaS signup form. The difference is that when you're done, you know exactly where your data goes and exactly what it costs.

> Ready to try BYOK with your notes? [Start with Scribelet's free plan](https://scribelet.app/pricing) and add your own key in desk settings.

## BYOK is a floor, not a ceiling

The Cursor episode taught a useful lesson: BYOK AI as a feature can be revoked. BYOK AI as a value cannot.

The distinction matters. A company that adds BYOK because competitors have it will drop it when the economics change. A company that builds BYOK into its security architecture, its encryption model, and its data flow from day one has made a structural commitment. The question to ask isn't "do you support BYOK?" It's "what would have to change for you to remove it?"

For note-taking apps specifically, BYOK AI is one piece of a broader data sovereignty question. Where are your notes encrypted? With what key? Who can read them? When AI processes your notes, which provider handles the data? Can you see what the AI changed? These questions form a stack, and BYOK is the first layer: you choose the AI provider, you control the billing, you own the data path. But it's the floor, not the ceiling.

Your notes [decay over time](https://scribelet.app/blog/knowledge-decay) as the information in them goes stale. AI can help fight that decay, verifying facts, discovering connections, flagging what's outdated. But only if you trust the AI's data path enough to let it touch your notes in the first place. BYOK is what makes that trust possible.

[Try Scribelet free](https://scribelet.app) and add your own OpenAI, Anthropic, or Gemini key. See what BYOK-powered note maintenance looks like when the AI works for you, not the other way around.
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>byok</category>
            <category>ai</category>
            <category>privacy</category>
            <category>note-taking</category>
            <category>api-keys</category>
            <category>knowledge-management</category>
            <category>encryption</category>
        </item>
        <item>
            <title><![CDATA[How to keep notes up to date: a 30-minute weekly system]]></title>
            <link>https://scribelet.app/blog/keep-notes-up-to-date</link>
            <guid isPermaLink="false">https://scribelet.app/blog/keep-notes-up-to-date</guid>
            <pubDate>Mon, 30 Mar 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Most PKM advice covers capture, not maintenance. A 30-minute weekly system to keep your notes up to date without auditing everything. Start free.]]></description>
            <content:encoded><![CDATA[
You built a solid note system. Tagged everything, linked ideas together, even committed to a weekly review. Six months later, you stopped trusting it. Not because the organization fell apart, but because you opened a note you'd been relying on and discovered the core fact in it had been wrong for weeks.

This is the moment most people either declare "PKM bankruptcy" and start from scratch, or quietly stop using their notes for anything that matters. On the Zettelkasten Forum, [a user described this cycle bluntly](https://forum.zettelkasten.de/discussion/3034/every-attempt-at-pkm-has-landed-me-in-the-same-place-a-huge-mess): "Every attempt at PKM has landed me in the same place -- a huge mess." They'd tried for decades, from pen-and-paper to Obsidian to Notion. The system always looked fine on the outside. The information inside kept decaying.

The problem isn't organization. Nobody teaches you how to keep notes up to date after you write them. Every methodology covers capture and filing. None of them cover note maintenance.

This article gives you a practical note review system: a weekly audit you can run in 30 minutes, a triage framework for your existing notes, and a way to scale when manual review breaks down.

## Not all notes decay at the same rate

Before you can maintain your notes, you need to know which ones actually need it.

A note about your personal leadership philosophy from 2024 is probably fine. A note about Stripe's API authentication flow from 2024 is almost certainly wrong. The decay rate depends on what your note references, not how old it is.

Technical documentation decays fastest. Framework APIs ship breaking changes quarterly. The Express.js v4 middleware pattern you documented? Anti-pattern in v5. Your Tailwind CSS guide references utility classes that were renamed. Weeks to months, and these notes are stale.

Client and market research sits in the middle. Competitor pricing changes. Market sizing data gets updated. A competitive analysis from last quarter has probably drifted in at least one material way. These notes decay over one to three months.

Academic citations decay more slowly, but the consequences are worse. [Retraction Watch](https://retractionwatch.com/) reports that paper retractions have grown roughly tenfold since 2000. A cited study could be undermined months after you built analysis on it.

Personal reflections and journal entries rarely decay at all. The insight about managing your energy during deep work sessions is as true now as when you wrote it.

The mistake most review systems make is treating all notes equally. A quarterly review catches the stale journal entry that doesn't matter and misses the API reference that went wrong eight weeks ago. [Knowledge decay](https://scribelet.app/blog/knowledge-decay) happens on different timelines, and your maintenance system needs to account for that.

## The kind of note review nobody talks about

PKM advice covers two types of note review extensively. The third type -- the one that actually determines whether your notes are trustworthy -- gets almost no attention.

Retention review is what most advice focuses on. Spaced repetition, the forgetting curve, active recall, the standard answers to [why you forget what you read](https://scribelet.app/blog/how-to-remember-what-you-read). Do you remember what you wrote? This matters for students. It matters less for professionals whose notes serve as reference material, not memorization aids.

Organization review is what Tiago Forte's [CODE framework](https://fortelabs.com/blog/basboverview/) and GTD weekly reviews cover. Is this note filed in the right project? Should it move from Resources to Archives? Has the priority shifted? This keeps your system navigable.

**Accuracy review** is the gap. Is what you wrote still true? Has the API changed? Was the citation retracted? Did the competitor update their pricing?

Nobody's weekly review template includes a step for this. GTD reviews process inboxes and check project statuses. PARA reviews move items between categories. Neither asks whether the information inside those items is still correct. Digital gardens go furthest by promising notes that get revised as understanding grows, and still leave the checking to you, because [adding is not tending](https://scribelet.app/blog/digital-garden).

That third type of review determines whether your knowledge base is an asset or a trap. The [living notes methodology](https://scribelet.app/blog/living-notes-method) was designed around this gap -- adding a maintenance phase between organize and trust. What follows is the practical implementation: the specific routines and checks that make maintenance a habit instead of a concept.

## The 30-minute weekly note audit

Four steps, 30 minutes, repeatable every week:

1. Triage your inbox (5 min)
2. Check active notes for accuracy (10 min)
3. Surface one dormant note (5 min)
4. Review flagged changes (10 min)

Here's each step in detail.

### Triage your inbox (5 minutes)

Process anything you captured during the week that hasn't been properly filed. Voice memos, browser tab dumps, meeting notes you jotted on your phone. If you keep [a running log of timestamped notes through the day](https://scribelet.app/blog/interstitial-journaling), that stream lands here too, waiting to be triaged into something durable. For each item: tag it, link it to a related note, or delete it. If you can't decide in 15 seconds, tag it "inbox" and move on.

The goal isn't perfection. It's preventing the inbox from growing into a backlog that feels too large to process. That growing backlog is how most note systems begin their decline.

### Check your active notes (10 minutes)

Pull up the notes you actually referenced this week. Not your full archive -- just the ones you opened, shared, or relied on for a decision.

Read each one with a single question: if I used this note to make a decision right now, would the decision be correct? You're not reorganizing. You're checking whether the key facts hold.

When Marcus, a backend engineer at a fintech startup, started doing this step in January, he found his team's API integration guide referenced an authentication flow that Plaid had deprecated two months earlier. A new hire had already spent a morning debugging 401 errors before realizing the guide was wrong. Ten minutes of weekly accuracy review would have caught the change before it cost someone a morning.

A shared team wiki fails in exactly this shape, only louder, because four people act on the wrong page before anyone edits it. That is the whole argument for [why internal documentation goes stale](https://scribelet.app/blog/internal-documentation) faster than the teams relying on it expect.

For each note, look for three things. Do the external references still resolve? Have the key facts changed since you wrote them? Is anything missing that you've learned since?

### Surface one dormant note (5 minutes)

Pick one note you haven't opened in 90 or more days that relates to something you're actively working on. Search for a keyword from a current project and sort by oldest.

Read it with fresh eyes. You'll find one of three outcomes: it's accurate and worth keeping, it's outdated and needs an update, or it's irrelevant and should be archived.

You're not trying to review your whole archive. One note per week. That's the habit that keeps dormant knowledge from rotting unnoticed.

### Review flagged changes (10 minutes)

If you're using automated verification, this is where you review what the agents found. Scribelet surfaces changes as inline diffs -- green for new information, red for what's outdated, with source links for each finding. Review, accept or dismiss, move on.

If you're doing this manually, spend the 10 minutes spot-checking one note's external sources. Google the key claims. Click the links. See if anything has shifted. It's slower, but it builds the instinct for noticing when something feels off.

## How to audit your notes when you have hundreds

The weekly audit keeps things from getting worse. But what about the backlog?

Don't try to audit everything in one sitting. That's how you end up spending a Saturday afternoon staring at your archive, getting overwhelmed, and closing the app. Start small.

### The five-note test

Pick five notes you've actually used in the past month. Not the prettiest ones, not the oldest ones. Just the five you've relied on. Check each one against its sources. Are the APIs working the way you described? Do the links resolve? Has the cited data been updated?

Time it.

Elena, a UX researcher at a health-tech company, ran this test on her competitor analysis notes. Two of the five companies she'd profiled had changed their pricing pages. One had launched an AI feature she hadn't documented.

Her "current" competitive landscape was three months behind reality. She'd been referencing it in client presentations.

Most people find at least one meaningful inaccuracy and spend 20 to 40 minutes checking five notes. That number tells you everything about the maintenance gap in your system.

### Triage, don't reorganize

Once you start finding issues, resist the urge to redesign your whole system. Score each note into one of four buckets.

Current and accurate? No action needed. Partially outdated but structurally sound -- a broken link, a version number that's changed -- those are five-minute patches. Fix them while you're looking at them. Notes where the core facts have shifted need a rewrite; flag these and add them to your weekly audit rotation. Notes no longer relevant to active work get archived to clear your working set.

Start with your 20 most-referenced notes. Once those are triaged, extend to the next 20. Spread it across weeks, not days.

## How often should you review your notes

The answer depends entirely on what they reference.

| Note type | Review cadence | What you're checking |
|---|---|---|
| Technical docs, API references | Every 2-4 weeks | Breaking changes, deprecations, version updates |
| Research notes, citations | Monthly | Retractions, updated data, superseding studies |
| Client and market intelligence | Monthly | Pricing shifts, new features, refreshed reports |
| Project notes | While project is active | Decisions still valid, action items complete |
| Personal reflections, journals | Skip | These don't reference external facts |

If you work in a fast-moving stack -- React, the Python ML ecosystem, anything with a rapid release cycle -- lean toward biweekly for technical notes. For research, the stakes per note are high but the change rate is slower, so monthly works.

Project notes are a special case. Once the engagement wraps, archive them or flag for a one-time accuracy check before reuse. No recurring schedule needed. The exception is anything you will need to account for later, which is the argument for keeping a [work log that remembers outcomes](https://scribelet.app/blog/ai-work-log) rather than a pile of project notes you archive and never reopen.

## When the manual approach stops scaling

The weekly audit works well when you have 50 active notes. Past that threshold, the arithmetic gets uncomfortable.

Manual verification of a single note -- checking sources, reading changelogs, comparing what you wrote against what's current -- takes 15 to 30 minutes when done thoroughly. At 100 notes on a quarterly rotation, you're looking at 25 notes per month, or six to 12 hours of verification work. Per month. For something that isn't your job.

Nobody sustains this. The people who try eventually conclude that PKM "doesn't work." But what actually broke wasn't the system -- it was the assumption that **a human should be doing the maintenance by hand**.

Automated verification changes the equation. Background agents can check hundreds of notes per week against current web sources and surface only the diffs that need your attention. Instead of six hours hunting for problems, you spend 10 minutes reviewing what an agent already identified.

Scribelet runs this as a [Pro](https://scribelet.app/pricing) feature: scheduled background verification with inline diffs, source citations, and one-tap accept or dismiss. You set the cadence per note or let the system prioritize by content age and type. Your notes go to the AI provider you choose through BYOK -- OpenAI, Anthropic, or Gemini -- with keys encrypted at rest.

The weekly audit doesn't disappear when you add automation. Steps one through three stay manual. Step four shifts from "manually Google one note's claims" to "review what the agents found across your entire knowledge base."

## Start this week

Run the five-note test. Pick your five most-used notes, check them against their sources, and time how long it takes. Within 20 minutes, you'll know whether maintenance is a real gap in your workflow or a theoretical one.

If the gap is real, categorize your 20 most important notes by decay rate. Technical references go in the biweekly bucket. Research and client notes go monthly. Journal entries get skipped. That's your second brain maintenance schedule, built in 15 minutes.

Block 30 minutes next Friday. Run the four-step audit. See what turns up.

If the manual process works at your scale, keep doing it. If you're spending more time verifying than the information is worth, that's the signal to automate. [Start with background verification. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>note-taking</category>
            <category>pkm</category>
            <category>maintenance</category>
            <category>productivity</category>
            <category>knowledge-management</category>
            <category>living-notes</category>
        </item>
        <item>
            <title><![CDATA[The living notes method for notes that stay useful]]></title>
            <link>https://scribelet.app/blog/living-notes-method</link>
            <guid isPermaLink="false">https://scribelet.app/blog/living-notes-method</guid>
            <pubDate>Wed, 25 Mar 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Zettelkasten, PARA, and Second Brain help you capture notes. The living notes method adds maintenance so your knowledge stays accurate over time.]]></description>
            <content:encoded><![CDATA[
You've tried at least one serious note-taking system. Maybe you went deep on Zettelkasten, crafting atomic notes and linking them with intention. Maybe you adopted PARA and sorted your knowledge into Projects, Areas, Resources, and Archives. Maybe you read "Building a Second Brain" and spent a weekend setting up a system that would change how you think.

It worked, for a while.

Six months later, you stopped trusting it. The framework notes referenced deprecated APIs. The research brief cited numbers that had shifted. The competitive analysis used a competitor's old pricing page. You'd built a solid system, but the information inside was decaying while the system itself looked fine.

The question of how to keep notes useful long term is the right one to ask. But every major note-taking methodology skips the one phase that determines whether your notes stay valuable or quietly become liabilities.

That phase is maintenance.

## What Zettelkasten, PARA, and Building a Second Brain share

Niklas Luhmann's Zettelkasten method, developed in the 1960s, solved an important problem: connecting ideas across disciplines. You write atomic notes, link them deliberately, and let the network surface insights you'd never reach through linear filing. Sonke Ahrens' "How to Take Smart Notes" popularized the method, and Zettelkasten has become the backbone of serious personal knowledge management (PKM) practice.

But Luhmann was a sociologist working with index cards. His notes referenced concepts and theories that evolved over decades, not APIs that ship breaking changes quarterly.

Zettelkasten has nothing to say about what happens when a linked note becomes inaccurate. The link still works. The note still looks authoritative. The information inside is wrong.

Digital gardening came closest to naming the gap, borrowing a metaphor from the one hobby where upkeep is the entire activity. Then it shipped publishing tools and left the weeding as a manual chore, which is how you end up with a garden where [everyone plants, nobody weeds](https://scribelet.app/blog/digital-garden).

Tiago Forte's [PARA method](https://www.buildingasecondbrain.com/para) solved a different problem: where to put things. Projects, Areas, Resources, Archives. It's an elegant categorization framework that tells you where a note belongs based on how actionable it is.

What PARA doesn't track is whether the note you filed under "Resources" two years ago still contains accurate information. It organizes by location. It doesn't monitor for freshness, which is why [PARA has no maintenance step](https://scribelet.app/blog/para-method-with-ai) to catch a Resource that quietly went stale.

Forte's broader framework, Building a Second Brain, covers the full creative lifecycle through CODE: Capture, Organize, Distill, Express. It's a clean model for moving ideas from your head into a system and back out as creative output.

But look at what's missing. There's no step between "express" and "done" where you check whether the captured information is still true. Once you've expressed an idea, CODE is finished. Your second brain starts aging the moment you move on.

All three share the same blind spot:

**Capture → Organize → Retrieve**

That lifecycle works when knowledge is stable. It breaks when the world changes faster than you review your notes.

Every one of these methods was designed before AI agents existed as a practical technology. Zettelkasten predates the internet. PARA predates large language models. Even Building a Second Brain, published in 2022, treats AI as a nice-to-have writing assistant, not a maintenance engine for the knowledge it helps you capture.

## The phase nobody talks about

Enterprise knowledge management figured this out years ago. Tools like Bloomfire, Guru, and Shelf track content freshness for customer-facing teams. They assign review dates, flag stale articles, and alert maintainers when documentation drifts from reality. Companies invest billions annually in knowledge management, and a significant chunk of that spending goes toward keeping information current, not creating it.

Personal knowledge management has no equivalent.

Claire Carroll described this gap in 2021, calling it ["fighting the entropy of knowledge bases"](https://clrcrl.com/2021/11/30/fighting-the-entropy-of-knowledge). She proposed classifying documents as transient versus reference so teams could focus maintenance where it matters. Good thinking, but scoped to company wikis. Personal notes weren't part of the conversation.

Mem.ai later coined "note rot" for the accumulated knowledge debt in personal notes. They built a cleanup tool around the concept. But refactoring notes after they've rotted is triage, not prevention. The question isn't how to clean up stale notes after the fact. It's how to catch staleness before it costs you.

The clearest evidence that this gap is real comes from the people who've lived it. The blog posts write themselves: "I spent six months building a second brain and then deleted it."

These stories follow the same arc. The system was well-organized. The notes were carefully tagged. But trust eroded because the information decayed while the system looked fine from the outside.

The problem isn't discipline. Maintenance has never been treated as a legitimate phase in the note-taking lifecycle. You wouldn't write software and never update the dependencies. But that is [the step every PKM system skips](https://scribelet.app/blog/personal-knowledge-management). You capture and organize and then never revisit, and the method blames you when the notes stop being useful.

The gap outlives the methods. The newest pattern in personal knowledge management points an LLM at your sources and has it write the wiki for you, which automates the organizing beautifully and still ships [without a maintenance step](https://scribelet.app/blog/llm-wiki). Automating the phases a method already had does not add the phase it never had.

> The concept of [knowledge decay](https://scribelet.app/blog/knowledge-decay) explains why information has a measurable half-life and why your tools should account for it. This article builds on that foundation with a methodology designed to fill the maintenance gap.

## Living notes: a note-taking method for the AI era

Living notes starts from different assumptions than traditional PKM.

Most PKM thinking treats notes as permanent artifacts. Andy Matuschak's [evergreen notes](https://notes.andymatuschak.org/Evergreen_notes) concept frames them as timeless units of knowledge, meant to be refined and reused indefinitely. That works for philosophical insights and personal reflections, where nothing references external sources that change.

It breaks for API documentation, market research, and citation-heavy analysis. Living notes treats knowledge as perishable. The question isn't whether your notes will go stale. It's when, and whether your system will catch it.

This has a downstream consequence for how you allocate effort. If you spend two hours writing a research brief, that brief's value depreciates every month it goes unreviewed. Maintenance isn't optional extra work that happens when you get around to it. It's the activity that determines whether the original two hours remain an asset or become a trap.

The current conversation about AI and notes misses this entirely. AI writes drafts. AI summarizes meetings. AI transcribes audio. These are all capture-phase tools: faster ways to get information into the system. Living notes assigns AI a different job. It monitors, verifies, connects, and flags. Not generating your notes, but keeping them alive after you write them.

The lifecycle changes:

**Capture → Organize → Maintain → Trust**

![Diagram comparing the traditional PKM lifecycle (Capture, Organize, Retrieve) with the Living Notes lifecycle that adds Maintain before Trust](/blog/living-notes-method/lifecycle-comparison.svg)

The maintain phase has four functions:

- **Verification** checks whether the facts in a note still hold against current sources
- **Connection discovery** finds relationships between notes you haven't explicitly linked
- **Staleness detection** identifies notes that need attention based on age, topic relevance, and recent activity
- **Context building** extracts facts, terminology, and relationships from your notes so AI improves over time

None of these require you to do the work manually. That's the point. A methodology built around maintenance only becomes practical when the maintenance itself is automated.

![The four functions of the maintenance phase: Verification checks facts against sources, Connection Discovery finds relationships between notes, Staleness Detection identifies notes needing attention, and Context Building extracts facts so AI improves over time](/blog/living-notes-method/maintenance-functions.svg)

## What the maintenance phase looks like day to day

Here's what changes when maintenance is baked into the system.

On a Tuesday morning, you open your notes and find a diff waiting. Background agents ran overnight and found that the Express.js middleware pattern you documented last quarter was deprecated in v5.2. The diff shows the old pattern in red, the current pattern in green, with a link to the Express migration guide.

You review it in 30 seconds, accept the update, and your note is current. Doing the same work yourself would have meant reading release notes you didn't know existed, for a framework update you didn't know had shipped.

That same morning, a daily digest arrives. It surfaces a connection you'd missed: you wrote about a client's rebranding initiative in one note and their Q1 revenue data in another, but never linked them.

The digest flags both notes, explains the relationship, and suggests a wikilink. You tap to accept. Your knowledge graph now reflects a connection your filing system wouldn't have surfaced for months.

In the background, a stale checker noticed something. Your competitive analysis of a SaaS company hasn't been updated in 90 days. Normally that wouldn't trigger anything. But you wrote three new notes mentioning that same competitor last week.

The stale checker flags the analysis for review. Not because it's old (everything gets old), but because it's old *and* you're actively working in the same space. That's the difference between a calendar reminder and intelligent maintenance.

Later, on your commute, you record a voice memo about an idea for a product feature. The memo gets transcribed and structured by AI into a note with a title, two headings, four action items, and three suggested tags. AI memory already covers your active projects and common terminology, so the transcription handles your jargon accurately. The note is organized before you reach your front door.

> Background verification, daily digests, auto-linking, stale detection, and voice-to-structured-note are all part of Scribelet's [Pro plan](https://scribelet.app/pricing). They're the tools that make the living notes maintenance phase practical at real-world scale.

Over weeks and months, the maintenance layer compounds. Your knowledge base gets more connected, more accurate, and more contextually aware. AI builds a per-desk knowledge graph mapping your people, projects, and terminology.

Conversations carry context through episodic memory, which preserves what you discussed and when. The more you use the system, the better the maintenance becomes.

This is the opposite of the traditional PKM trajectory. In most systems, notes get less trustworthy the longer they sit untouched. With living notes, the system actively fights that decay. Trust compounds instead of eroding.

## Why maintenance needs AI (and why the AI should be yours)

You can practice the principles of living notes without AI. Review your important notes quarterly. Check sources manually. Look for connections yourself.

It doesn't scale. Manual verification of a single note, checking cited sources, comparing against current information, reading changelogs, takes 15 to 30 minutes. Multiply that by your top 50 notes and you're looking at a full workday every quarter doing nothing but checking whether what you already wrote is still true.

AI agents make the maintenance phase practical at real-world scale. They run verification checks on hundreds of notes per week and surface connections across a corpus too large for working memory.

![Line chart comparing maintenance effort as a knowledge base grows. Manual review climbs steeply and becomes impractical past 200 notes at roughly 20 minutes per note. AI-assisted maintenance stays nearly flat at about 30 seconds of review per surfaced diff.](/blog/living-notes-method/maintenance-scaling.svg)

They also detect staleness patterns that need multiple signals at once: this note is old, the topic is active in your recent notes, and a key source has changed since you last checked.

But automated maintenance means your notes flow through an AI model. What you wrote, what the agent found, what changed. Scribelet uses fully private AI models, running in our own infrastructure, and will not use your data to train anything. But if you want to control the data flow more closely, that's where BYOK (Bring Your Own Key) matters.

If you decide to go that route, you can choose the provider: OpenAI, Anthropic, or Google Gemini. Your API key, encrypted at rest with AES-256-GCM. Your data goes to the provider you selected, not one a vendor chose for you.

## Where living notes changes the math

Knowledge decays at different rates depending on what you write about, and the maintenance phase matters most where decay runs fastest.

Technical documentation is the obvious case. You wrote a guide to integrating a payment API. Three months later, the API ships v3 with a new authentication flow. Your guide now teaches a pattern that returns 401 errors.

A teammate follows your guide during onboarding, spends an hour debugging, and discovers the documentation is wrong. With a living notes approach, background verification catches the API change when it ships and gives you a 30-second diff review instead of your teammate's hour of confusion.

Research work decays on a different timeline. A study you cited in a literature review gets retracted for methodological concerns. That risk starts the moment you [read a paper and file it away](https://scribelet.app/blog/how-to-read-a-research-paper) without a way to re-check it. You don't find out until peer review, months later, after you've built analysis on a compromised foundation.

[Retraction Watch](https://retractionwatch.com/) reports that paper retractions have grown roughly tenfold since 2000. A living notes verification layer monitors cited sources and flags changes, including retractions, before they propagate through your work.

Client-facing research has the highest stakes per note. You pull up last quarter's competitive analysis for a new engagement. Two competitors changed their pricing since you wrote it. One launched a feature that didn't exist three months ago.

You present the analysis with minor updates, confident it's mostly right. "Mostly right" is a professional risk that compounds with every reuse. The maintenance phase catches the drift before you walk into the meeting.

Same methodology, different cadences. The way to keep notes useful long term isn't a single review schedule. It's adapting verification frequency to how fast your specific content decays.

![Horizontal bar chart showing knowledge decay rates: technical docs decay in weeks to months, client research in 1-3 months, academic citations in months to a year, while personal reflections rarely decay. A dotted line marks the typical quarterly review cadence, showing fast-decaying content goes stale before most people check it.](/blog/living-notes-method/decay-rates.svg)

## How to keep your notes useful long term

You don't need to rebuild your system. Start with a five-note audit.

Pick five notes you've referenced in the past month. Not the oldest ones, not the most carefully organized. The ones you've actually used.

Now check them against their sources. Are the APIs still working the way you described? Do the links resolve? Has the data been updated since you cited it?

Time how long this takes.

If you're like most knowledge workers, you'll find at least one meaningful inaccuracy and spend 20 to 40 minutes verifying five notes. Multiply that across a knowledge base of hundreds of notes, and the maintenance gap becomes viscerally clear.

Once you've seen the gap, prioritize. Not all notes need the same maintenance cadence. Technical notes with external API references decay fast and need frequent checks. Personal journal entries may never go stale.

Focus maintenance effort where accuracy matters and where facts change.

The final step is automation. You can set calendar reminders and manually audit your top notes quarterly. That's better than nothing. But at the scale where a knowledge base becomes genuinely valuable, hundreds of notes accumulated over years, you need a tool that treats maintenance as a system function rather than a human chore.

[Scribelet](https://scribelet.app) is built for this. Background verification runs on a schedule you set, surfaces diffs when your notes drift from current sources, and shows you exactly what changed with links to the updated information. Start free, run your first verification, and see your first diff. That five-minute experience will tell you more about living notes than any article can.

## Notes that stay alive

The note-taking conversation has been stuck on the wrong phase. Capture tools keep improving. Organization frameworks keep getting refined. Search keeps getting smarter. None of it matters if the information you're organizing and retrieving is no longer true.

If you want to keep notes useful long term, the answer isn't better organization. It's adding the maintenance phase that every other methodology skips, and letting AI agents handle the work. Living notes addresses the actual reason people abandon their knowledge systems. Not bad organization, but eroded trust.

Every note you've written is either appreciating or decaying. The only question is whether your system knows the difference.

[Start writing with background verification. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>note-taking</category>
            <category>pkm</category>
            <category>methodology</category>
            <category>ai</category>
            <category>knowledge-management</category>
            <category>living-notes</category>
        </item>
        <item>
            <title><![CDATA[Knowledge decay: why your notes are silently going stale]]></title>
            <link>https://scribelet.app/blog/knowledge-decay</link>
            <guid isPermaLink="false">https://scribelet.app/blog/knowledge-decay</guid>
            <pubDate>Mon, 16 Mar 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Your notes start decaying the moment you save them. APIs change, facts shift, sources update. Learn what knowledge decay is and how to fight it.]]></description>
            <content:encoded><![CDATA[
You probably have a note somewhere about that API you integrated last year. Maybe it covers the authentication flow, rate limits, the endpoints you used. You wrote it carefully. It was accurate at the time.

But APIs change. Rate limits get updated. Auth flows get deprecated. That note has been quietly becoming a liability instead of an asset, and you'd never know until you tried to use it and hit a wall.

This is knowledge decay. It's the gradual loss of accuracy in your stored information as the world around it changes. And it's happening to your notes right now.

Most note-taking tools treat this as a you problem. You should review your notes more often. You should be more organized. You should tag things better. But the problem isn't your habits. It's that information has a half-life, and your tools don't account for it.

This article explains what knowledge decay is, why it affects personal notes more than most people realize, and what you can do about it. Including letting AI handle the maintenance for you.

## What is knowledge decay?

Knowledge decay is the gradual loss of accuracy in stored information as the world around it changes. A fact that was true when you wrote it down becomes partially true, misleading, or outright wrong as its underlying source updates, because [a note is a map and the territory it describes keeps moving](/blog/the-map-is-not-the-territory). The same happens to decisions: [a choice made with a sound decision-making framework](/blog/decision-making-framework) still rests on assumptions that quietly expire, and the record of it reads exactly as confident as the day you wrote it. The [second- and third-order effects you predicted when you decided](/blog/second-order-thinking) are the same kind of expiring assumption: a bet on how the world would react, quietly going stale until someone checks it against what actually happened. The reasoning behind a metric decays the same way, and [once nobody remembers why a high-stakes number was chosen it hardens into a target no one can defend](/blog/campbells-law). The same forgetting buries [which groups a number was pooled over before its trend quietly reversed](/blog/simpsons-paradox).

The term comes from organizational knowledge management, where companies lose institutional knowledge through employee turnover, outdated processes, and unmaintained documentation. But knowledge decay isn't just an enterprise problem. It affects [personal knowledge management](https://scribelet.app/blog/personal-knowledge-management) just as deeply. It's a physics-of-information problem that touches every note you've ever written.

Samuel Arbesman, a complexity scientist, explored this concept in his book "The Half-Life of Facts." As [Farnam Street's overview of his research](https://fs.blog/the-half-life-of-facts/) explains, knowledge across every domain has a measurable rate of decay. Medical knowledge has a half-life of roughly 45 years and shrinking. The half-life of an engineering best practice is shorter. The half-life of an API reference? Months.

### The half-life of different types of information

Not all notes decay at the same rate. The type of information determines how quickly it goes stale.

**Technical documentation** decays fastest. Framework APIs change quarterly. Libraries ship breaking changes. A [React guide](https://react.dev/blog) written in early 2025 might reference patterns that were deprecated by early 2026. Express.js v4 middleware patterns are anti-patterns in v5. The Python package you documented might have been forked, renamed, or abandoned.

**Research citations** decay at a medium rate. Papers get retracted, updated, or superseded. According to [Retraction Watch](https://retractionwatch.com/), the rate of paper retractions has grown roughly tenfold since 2000. That literature review you built is accumulating risk with every month it sits untouched.

**Industry knowledge** shifts more slowly but still shifts. Market size figures go stale. Competitive landscapes change. Regulatory requirements update. The client research brief you wrote six months ago probably contains at least one number that no longer holds.

Even foundational concepts aren't immune, though they decay slowest. Paradigms shift. Design patterns fall out of favor. The "right" way to structure a React application in 2024 isn't the same as in 2026.

The more specific and external-facing your notes are, the faster they decay, and [the more often you reread a stale line, the more settled it feels](/blog/illusory-truth-effect) even as it drifts away from the truth.

The same clock runs on the configuration files nobody thinks of as writing. A system prompt is a document a machine reads on every request, tuned to a model that gets replaced twice a year, which is why [a system prompt is an artifact, not a setting](https://scribelet.app/blog/system-prompt). The same clock runs on [the examples you paste into a prompt](https://scribelet.app/blog/few-shot-prompting) to steer it: they freeze a format the world keeps moving away from, and the output stays fluent while it drifts. It even runs on [the prompt a model writes for you](https://scribelet.app/blog/meta-prompting) when you ask it to: a generated prompt captures the day you asked and keeps steering there long after. And it runs on [a chain of prompts you save and reuse](https://scribelet.app/blog/prompt-chaining), which bakes in the task, the format, and the model it was tuned for, then keeps running after any of them changes.

![Line chart showing how technical documentation, research citations, industry knowledge, and foundational concepts lose accuracy at different rates over time](/blog/knowledge-decay/decay-curve.svg)

## What knowledge decay looks like in your notes

Knowledge decay is invisible until it isn't. You don't get a notification when an API you documented ships a breaking change. Nobody emails you when a paper you cited gets retracted. Nobody flags the [estimate whose assumptions quietly stopped being true](/blog/hofstadters-law). The note just sits there, looking authoritative, waiting to mislead. Some notes were never solid to begin with: you saved a conclusion you felt you understood and [never captured the mechanism you could not actually explain](/blog/illusion-of-explanatory-depth), so each reread only deepens a confidence the note cannot support.

Here's what it looks like in practice.

Say you're a developer who's written technical guides, architecture decision records, integration notes. Six months pass. The framework ships a major version. Three of the APIs you documented now have different signatures. The auth library you recommended switched to a new token format. Your onboarding doc for new engineers is now teaching patterns your codebase has moved away from. Someone follows your guide, hits errors they don't understand, and spends two hours debugging before realizing the guide is wrong. That is [Brandolini's law running inside your own notes](/blog/brandolinis-law): the wrong line was cheap to write and expensive to catch. The same rot reaches the reasoning inside the code itself: [good names tell you what a function does, never why it does it that way](/blog/self-documenting-code), and the why is the first thing to go.

Research notes rot differently. You build a literature review across dozens of notes, citing a study that supports a key finding, and [the paper you cited can change under you](https://scribelet.app/blog/how-to-read-a-research-paper) after you file it. A year later, that study gets retracted due to methodological concerns. Your literature review still cites it. Your analysis still builds on it. You don't find out until a peer reviewer flags it, and by then you've built three months of work on a foundation that cracked.

Consultants and knowledge workers face a subtler version. You assemble research for a client engagement: market sizing, competitive analysis, regulatory landscape. The engagement wraps. Three months later, a similar engagement starts. You pull up the old research because it was thorough. But the market has shifted, a competitor pivoted, and a regulation changed. You present the old data with minor updates, confident it's mostly right. "Mostly right" is a dangerous baseline when your credibility is on the line.

Every one of these is an ordinary consequence of stale notes, of information with a shelf life stored in tools that don't track expiration.

Encryption changes none of this. A note sealed behind zero-knowledge encryption goes stale on exactly the same schedule as a plaintext one, because [security protects the bytes, not the accuracy](https://scribelet.app/blog/secure-note-taking-app). A locked note you can no longer trust is still a liability, just a private one.

Decay compounds quietly enough that most people only meet it in bulk, years later, when they export everything to move to another app and finally see the whole pile at once. That is its own kind of reckoning, and it is why [migrating off Evernote](https://scribelet.app/blog/evernote-alternative) after a decade tends to be less about the destination app than about how much of the archive was still true. Most of that pile is the ninety percent [Sturgeon's law predicts](https://scribelet.app/blog/sturgeons-law); the trouble is that the ten percent worth keeping is buried in it, and decay is steadily thinning even that.

## Why your note-taking app doesn't help

Every major note-taking tool is built around the same lifecycle: capture, organize, search, retrieve. They help you create notes. They help you find notes. They do nothing to address knowledge decay or tell you whether the notes you find are still accurate.

Look at the tools:

**Notion** is excellent at databases, project management, and team wikis. Its AI helps you write and summarize. But once you write a note, Notion treats it as finished. If the information in that note becomes outdated, Notion doesn't know and doesn't care.

**Obsidian** gives you complete control over your files. Local-first, plugin-rich, deeply configurable. But the maintenance burden falls entirely on you. Obsidian's philosophy is "file over app," which is admirable for data ownership. It's less helpful when you need to know which of your 500 notes contains a deprecated API reference. Nor does bolting AI on top close the gap: [all four ways to add AI to a vault](https://scribelet.app/blog/obsidian-ai) read your notes on demand, and not one of them revisits a note you are not currently looking at.

**Apple Notes** captures thoughts with zero friction. It's on every Apple device, syncs seamlessly, and stays out of your way. But it's also the tool equivalent of a filing cabinet. It stores what you put in and never looks at it again.

**Even AI-native tools** like Mem and Reflect focus their intelligence on search, organization, and writing assistance. The AI helps you find related notes and generate new content. It doesn't check whether the notes it found are still true. So a surfaced note gets the same trust as a fresh one, and [trusting a source you already caught being wrong](/blog/gell-mann-amnesia-effect) is exactly how a stale note keeps its authority.

**Source-grounded research tools** like Google's NotebookLM ground every answer in material you upload, which genuinely helps when you're working through a dense reading pile. But the notebook is built around those sources, so a summary generated in March is still a March summary in November. The distinction is [source library vs living notes](https://scribelet.app/blog/notebooklm-alternatives-personal-notes), and it decides whether the tool is still useful after the first read.

**Digital gardens** are the honorable exception, because they promise upkeep out loud: notes that get revised and deepened as your understanding grows. The tooling underneath still only publishes them, so the promise depends entirely on you remembering to return. That's [why digital gardens stall at seedling](https://scribelet.app/blog/digital-garden).

**LLM wikis**, the newest arrival, automate the synthesis itself: you curate the sources and a model compiles them into an interlinked markdown wiki. It's a genuine improvement on re-reading a folder of PDFs forever. It also inherits this exact problem, because [a compiled wiki freezes on the day you build it](https://scribelet.app/blog/llm-wiki) and nothing in the pattern watches the sources for changes afterward.

The note-taking industry has a blind spot. Every tool in the market helps you move from blank page to organized knowledge base. None of them help you move from organized knowledge base to *trustworthy* knowledge base.

The lifecycle should be: capture, organize, **maintain**, trust. That third step is where every current tool stops and where the real problem begins.

![Diagram comparing the current note-taking lifecycle (Capture, Organize, Search, Write) to the complete lifecycle that adds a Maintain step before Trust](/blog/knowledge-decay/maintenance-gap.svg)

> If you're interested in a tool that fills this gap, [Scribelet](https://scribelet.app) is built around the idea that your notes should stay accurate after you write them, not just well-organized.

## How to fight knowledge decay

There's no way to stop information from changing. But if you've wondered how to keep notes up to date without manually auditing everything, there are three approaches, each with different tradeoffs.

### Manual audits: thorough but unscalable

Set a calendar reminder. Once a quarter, open your most important notes and check them against current sources. Verify the APIs still work the way you described. Check that the citations haven't been updated. Confirm the market data is still current.

This works if you have 20 notes. It breaks down at 200. And at 2,000, it's not a maintenance strategy. It's a fantasy.

The manual approach also requires you to know what changed. If you're reviewing a technical note, you need to know that the framework shipped a new version. If you're reviewing a research note, you need to know that a citation was retracted. You're doing the verification work that should be automated.

### Date-based review: better targeting, still passive

A more structured version: tag every note with a review date. Use a system (a tag, a property, a reminder) to surface notes that are due for review based on how quickly their content type decays. Technical notes every three months. Research notes every six. General knowledge annually.

This improves targeting. You're reviewing notes when they're most likely to have decayed, not on an arbitrary schedule. But you're still doing the work manually. And the system tells you *when* to check, not *what* changed.

If you want the version of this that runs on a schedule rather than on your willpower, we set out [a maintenance layer you can actually run](https://scribelet.app/blog/ai-second-brain-setup), split by what a machine should handle and what still needs your judgement.

![Comparison of three note maintenance approaches: manual audits, date-based review, and AI-powered verification with their scalability, change detection, and cost tradeoffs](/blog/knowledge-decay/approaches-comparison.svg)

### AI-powered verification: the maintenance layer

The third approach is to let an AI agent do the checking.

Background agents search the web on a schedule you configure. They compare what they find against what you wrote. When something doesn't match, they surface the discrepancy as an inline diff: green highlights for new information, red for what's outdated. Each change includes a source link so you can verify the finding yourself.

You review, accept or dismiss, and move on. The note stays current. You didn't have to remember to check it, know what changed, or do the research yourself.

This is what Scribelet's background verification does. You set the schedule per note (or let the system prioritize based on content age and type). Agents run in the background. When they find something, you see a clear, traceable diff. Not a vague "this might be outdated" warning, but a specific "this API endpoint was deprecated in v5.2; here's the replacement, here's the migration guide."

The key difference from the first two approaches: **note maintenance is no longer your job.** The tool handles it.

The same decay reaches anything an AI has stored about you, which is why it is worth knowing [what belongs in an AI's memory and what expires](https://scribelet.app/blog/ai-memory) before you let one accumulate facts unchecked. It also shows up live inside a single long session, where a model's answers get worse as its [working context fills with clutter](https://scribelet.app/blog/context-rot).

And because Scribelet is privacy-first, the default AI runs in a fully isolated environment where your data is never used for training. If you want even more control, BYOK (Bring Your Own Key) lets you route through OpenAI, Anthropic, or Google directly. Your API key, encrypted at rest. Your provider, your choice.

> **Ready to stop maintaining your notes manually?** [Try Scribelet](https://scribelet.app) and see how AI-powered note maintenance works.

## A new category: notes that maintain themselves

The note-taking conversation has been stuck for years. Every product announcement is about the same things: better organization, prettier editors, smarter search, AI writing assistance. These matter. But they all address the same phase of the lifecycle: getting information *in*.

Nobody talks about knowledge decay or what happens after. The closest the conversation gets is the recurring idea of [self-maintaining knowledge bases](https://scribelet.app/blog/karpathy-llm-wiki-reaction), which splits into two very different bets depending on whether the AI curates external sources or maintains what you already wrote.

The industry lifecycle looks like this:

**Capture → Organize → Search → Write**

What's missing:

**Capture → Organize → Maintain → Trust**

That "maintain" step is where knowledge decay either gets caught or doesn't. It's where a note stays an asset or becomes a liability. It's the difference between a knowledge base you can rely on and one you have to second-guess.

We built Scribelet around this missing step. Not because organization and search don't matter (they do, and Scribelet handles both). But because we kept finding outdated information in our own engineering docs and realized no tool we used cared about that problem.

Background verification is one piece of this maintenance layer. But the concept is broader:

- **Daily digests** surface themes, action items, and connections across your recent notes, so patterns don't slip through the cracks
- **Auto-linker** discovers semantic relationships between notes you didn't explicitly connect, building your knowledge graph without manual effort
- **Stale checker** flags stale notes you haven't touched in 60 or more days that relate to topics you're actively working on

All of this comes from designing a note-taking tool around the premise that notes need ongoing care, not just a good filing system.

## Your notes deserve maintenance, not just organization

Knowledge decay is real, measurable, and already happening in your notes. The API guide you wrote last quarter has probably drifted from reality. The research you compiled for a project is accumulating risk every month it goes unreviewed. The technical documentation your team relies on is one framework update away from being actively misleading, which is [the maintenance layer a team wiki is missing](https://scribelet.app/blog/internal-documentation).

That's not a failure of discipline. It's a property of information. Facts change. Sources update. Best practices evolve. The only question is whether your tools help you keep up or leave you to figure it out alone.

Information has a half-life, and right now every note-taking app ignores that. They help you create and organize. None of them help you maintain and verify. But maintenance can be automated: AI-powered verification catches what manual audits miss, at a fraction of the effort.

Your notes aren't failing because you're disorganized. They're failing because your tools don't account for the half-life of what you wrote.

[Start writing with background verification. Try Scribelet free.](https://scribelet.app)
]]></content:encoded>
            <author>hello@scribelet.app (Scribelet Team)</author>
            <category>knowledge-decay</category>
            <category>note-taking</category>
            <category>ai</category>
            <category>productivity</category>
            <category>knowledge-management</category>
        </item>
    </channel>
</rss>