Forem: Andrew Eddie

Custom Claude Code Commands That Simplified My Coding Sessions

Andrew Eddie — Mon, 23 Mar 2026 23:27:17 +0000

Late last year I wrote two articles about working with AI assistants across sessions. Both worked really well. Copy-paste the handover prompt. Update the docs at the end of the session. Archive completed items before the file gets unwieldy. Simple. Turns out though, it could be even simpler.

About a month ago I started using Claude Code and discovered commands. Hang on, they're just prompts stored in files. New hammer looking for nails: you know the drill.

I tried simplifying the continuation prompt. It became /next.

I finished a bunch of tasks, which inevitably led to the next command: /archive.

My TODO list was empty. I needed /todo to create new ones.

TODO contained a growing list of noisy deferred ideas. This led to /idea.

A handful of slash commands was far easier to remember. I've structured this article so you can point an AI at it to set up the files for you. What could be easier?

The System at a Glance

Four files in your project root:

File	Purpose
`CLAUDE.md`	Agent instructions. Loaded automatically every session.
`TODO.md`	Current work. Step-by-step tasks with checkboxes.
`HISTORY.md`	Completed work. Archived from TODO when done.
`IDEAS.md`	Future work. Low-priority, separated from active focus.

Four commands in .claude/commands/:

Command	What it does
`/next`	Reads TODO.md, finds the first unchecked task, and continues working.
`/archive`	Moves completed tasks from TODO.md to HISTORY.md.
`/idea`	Captures a new idea in IDEAS.md without interrupting flow.
`/todo`	Plans the next step and writes it into TODO.md (after your approval).

That's the whole system. Let's have a look at each piece.

CLAUDE.md: Agent Instructions

CLAUDE.md is the file Claude Code reads automatically at the start of every session. It replaces the "Quick Context" section from my earlier TODO.md pattern and the manual "Read these docs first" prompt.

This file isn't documentation for humans. It's configuration for the AI. Write it as instructions, not prose.

Here's a distilled template you can adapt to any project:

# [Project Name] — Agent Instructions

## Read first

1. [KEY_DOC].md — [what it covers]
2. [SOURCE_DIR]/ — [what to look at]

## Dev environment

- [How to run the project]
- [Key URLs, ports, services]

## Architecture rules (never violate these)

- [Rule 1: e.g. "No direct database access from UI components"]
- [Rule 2: e.g. "All state changes go through the store"]
- [Rule 3: e.g. "No React — vanilla JS only"]

## Key commands

[command]  # [lint?]
[command]  # [build?]
[command]  # [run?]

## Working style

- One step at a time — implement, then stop for review
- If anything is ambiguous or has meaningful trade-offs, ask first

## Verify steps

TODO items marked "Verify:" require manual testing in a running
browser/server. Never tick these off — leave them unchecked and
list them for the user to confirm.

## Commits

Never commit unless the user explicitly asks.

What to put in here and what to leave out

Put in: Anything the AI needs to know every session. Architecture constraints. How to run the project. Non-obvious conventions. Working style preferences (do you want it to ask before editing, or just go?).

Leave out: Things derivable from code (file structure, function signatures). Things that change often (current task, recent history). Anything longer than a page. If a section is growing, extract it into its own file and add a "Read first" pointer.

The "Architecture rules" section does the most work. My experience is that without explicit constraints, the AI will suggest whatever framework or pattern it's been trained on most heavily. If you're using Custom Elements, it will suggest React. If you're using Fastify, it will suggest Express. Name your constraints. The AI respects what it can read.

The "Verify steps" and "Commits" sections solve a specific problem: AI agents that tick off manual testing checkboxes without testing, or commit code without being asked. Both have bitten me. State the rules once in CLAUDE.md and they apply to every session.

TODO.md: Current Work

TODO.md is where active work lives. Nothing else. No backlog, no ideas, no completion history. Just the current and upcoming tasks with enough detail for the AI to pick up where you left off.

# [Project Name]: TODO

## Goal

[One or two sentences describing what you're building toward.]

## Milestones

[List of milestone numbers/names showing progression.]

## Next Steps

### N) Task Title

One-line description of the feature or change.

#### Sub-section name

- [ ] Implementation task
- [ ] Implementation task

#### Verify

- [ ] Verify: manual testing instruction
- [ ] Verify: manual testing instruction

---

### N+1) Next Task Title

...

Why this structure works

Each task is a numbered step with checkboxes. The AI reads the file, finds the first unchecked box, and knows exactly where to start.

The #### Verify sections are a forced hold. CLAUDE.md tells the AI to never tick these off, so it implements everything it can and then stops. You test in the browser, confirm it works, and your next prompt is usually "verified, mark as done, commit." This is the human-in-the-loop checkpoint. Ironically, it lends itself to yet another command (maybe /verified), which is how you know the pattern is working: it's easy to extend.

The --- between tasks acts as a clean boundary. When /archive removes a completed task, it removes everything from the ### heading to the next --- or ###.

HISTORY.md: Completed Work

HISTORY.md is a date-stamped log of completed tasks. It gives the AI temporal context without cluttering the active task list.

# [Project Name]: History

## 2026-03-21

- Step 37: Markdown syntax highlighting
- Step 36: Re-index and housekeeping improvements

## 2026-03-15

- Step 35: Soft delete and bin management
- Step 34: Ambient summaries

## 2026-03-10

- Step 33: Notebook drag and drop

The format is minimal. Date heading, bullet points with step number and title. That's enough for the AI to understand project maturity, recent momentum, and what's already been built.

You don't write this file. The /archive command does.

IDEAS.md: Future Work

IDEAS.md is where backlog items, feature ideas, and "maybe someday" thoughts go. It's deliberately separated from TODO.md to solve the original problem: AI assistants treating backlog items with equal weight to current work.

# [Project Name]: Ideas

These are not prioritised. They are captured here so they don't get
lost and don't pollute the active TODO.

### Idea Title

One or two paragraphs explaining the idea, its motivation, and how
it might connect to existing work.

### Another Idea

Description.

The AI doesn't read this file unless you ask it to. That's the point. When you're mid-session working on step 42 and a stray thought hits you, type /idea wiki-links with autocomplete and it gets captured without breaking your flow or contaminating the task list.

The Four Commands

Commands live in .claude/commands/ as markdown files.

/next

Read `TODO.md` and continue working on the current or next task.

## Steps

1. Read `TODO.md`.

2. Find the **current task** — the first task under "Next Steps"
   that has at least one unchecked (`[ ]`) non-Verify checkbox.

3. Summarise the task and which steps remain, then proceed with
   the next unchecked step.

This is the command that replaced the handover prompt. You open your laptop, start Claude Code, type /next, and the AI picks up where you left off. No copy-pasting. No remembering. No context.

I forget where I'm up to constantly. This command means I don't have to remember.

/archive

Archive completed tasks from TODO.md into HISTORY.md.

## Steps

1. Read `TODO.md` and `HISTORY.md`.

2. Identify **fully completed tasks** — a task is fully completed
   when:
   - Every non-Verify checkbox is checked (`[x]`)
   - Verify checkboxes are ignored (they are always unchecked
     by design)
   - If a task has no checkboxes at all, it is NOT considered
     complete

3. If no tasks are fully complete, report that and stop.

4. For each completed task, append to `HISTORY.md` grouped
   by date:
   - If a `## YYYY-MM-DD` heading for today already exists,
     add bullet points under it.
   - Otherwise, append a new date heading first.

5. Remove the completed task sections from `TODO.md`.

6. Show the user what was archived and what remains, then ask
   them to confirm before committing.

7. When confirmed, commit both files with message:
   `Archive completed tasks: <comma-separated task titles>`

When a task is done (all implementation checkboxes ticked, Verify items left unchecked by design), /archive moves it to HISTORY.md with today's date, cleans TODO.md, and commits.

/idea

Quickly capture an idea in IDEAS.md.

## Steps

1. Read `IDEAS.md` to understand the current structure and avoid
   duplicates.

2. Take the user's input and expand it into a well-formed idea
   entry:
   - `### Title` — short, descriptive name
   - One or two paragraphs explaining the idea, its motivation,
     and how it connects to the project
   - If the idea relates to existing ideas already in the file,
     note the connection

3. Append the new entry to the end of `IDEAS.md`.

4. Show the user what was added.

You type /idea streaming responses for the ask mode and it writes a properly formatted entry. The idea is captured. Your flow isn't broken. TODO.md stays clean.

/todo

Plan the next step for TODO.md without executing it.

## Steps

1. Read `TODO.md`, `DESIGN.md`, and `HISTORY.md`.

2. Read the current source code relevant to the feature being
   planned.

3. Break the feature into small, ordered implementation steps.
   Group related tasks under sub-sections.
   Include a Verify section with manual testing checks.

4. Present the proposed step to the user for review.
   Do NOT edit TODO.md yet.

5. Once approved, write the step into the "Next Steps" section
   of `TODO.md`.

This one is for planning. When you finish a phase and need to figure out what's next, /todo add entity-aware filtering reads the codebase, reads the history, and proposes a detailed step-by-step plan. You review it, adjust it, approve it. Then it writes it into TODO.md and you can /next to start executing.

How It Fits Together

A typical workflow looks like this:

Start of session: Type /next. The AI reads TODO.md, finds the current step, summarises where you are, and starts working.
During work: The AI implements each checkbox, stops for review, and moves to the next. If a stray idea comes up, type /idea [description] to capture it without losing focus.
Task complete: All implementation checkboxes are ticked. The AI lists the Verify items for you to test manually. You test, confirm, and ask for a commit.
Housekeeping: Type /archive to move completed tasks to HISTORY.md. Type /todo [next feature] to plan the next step.
Next session: Type /clear then /next. The AI picks up exactly where you left off.

The human's job is to review, test, and decide. The protocol's job is to remember.

Setting Up a New Project

Share this article with Claude Code and ask it to scaffold the files. Or copy the templates above:

Create CLAUDE.md in your project root with your architecture rules and dev environment.
Create TODO.md with a goal and your first task.
Create HISTORY.md with just a heading.
Create IDEAS.md with a heading and a note that items are not prioritised.
Create the four command files in .claude/commands/.

The commands are generic enough to work across projects without modification. CLAUDE.md is the only file that needs project-specific content.

Scope and Honesty

This is a personal workflow system. It's great for solo work. It could work in a team. It doesn't replace Jira.

It doesn't replace documentation. CLAUDE.md tells the AI how to work on your project. It doesn't explain your architecture to a new team member. If your project needs a DESIGN.md, have the AI write one and point to it from CLAUDE.md's "Read first" section. It's only a matter of time before you add /docs to tell the AI to summarise what 'we' just built and make sure the documentation is aligned with the current state of the code.

Enjoy!

Teaching AI to Write Like Me

Andrew Eddie — Sun, 22 Mar 2026 05:05:02 +0000

Every time you ask an AI to help you write, it sounds like an AI. Not because the AI is bad at writing, but because it has no idea who you are. It defaults to training data: a blend of every Medium post, technical blog, and corporate copywriter it has ever ingested. The result is competent, generic, and nothing like you.

And here's the thing. You already have the solution. It's sitting in your git history, your old blog posts, your archived articles. Years of writing that is unmistakably, provably yours.

I recently sat down with Claude and shared 169 of my own blog posts spanning 2007 to 2014. The goal was to build a detailed voice profile that I could include in any writing project to override the AI's default voice. Not a vague "write in a casual tone" instruction. A binding, specific, line-by-line reference document that tells the AI exactly how I write, and exactly how I don't.

The result was effective. And the process is something anyone with a writing history can replicate.

What I Learned About My Own Voice

It turns out that my voice was pretty consistent across seven years and very different content types (tutorials, opinion pieces, product announcements, conference talks, and community commentary). The AI identified solid and consistent patterns:

I almost always explain why before how
My sentence rhythm follows a short-medium-medium-short pattern
I use "we" when teaching and "I" when taking a position
I reach for developer-native metaphors over literary ones
My enthusiasm shows through depth and detail, never through superlatives
I have signature phrases I use without thinking ("Let's have a look at...", "Fair question.", "And here's the thing")

What was absent? No exclamation marks. No "amazing" or "incredible". No "dive deep" or "leverage". No corporate jargon. These are all things AI defaults to constantly, and none of them are me.

The Voice Evolved

I also compared my 2007-2014 writing against something I'd written recently: a formal retrospective document from 2026. The voice had clearly matured.

The playful parenthetical asides had mostly disappeared. "I have to be honest and say..." had become "My experience has been that..." The collaborative "we" had shifted toward a more authoritative "I" that carried accountability rather than just anecdote. The humour hadn't gone away, but it had gone quieter: structural irony instead of wordplay.

Same person. Same core directness. But the texture had changed. This matters because a voice profile that only captures how you wrote ten years ago will sound dated.

Testing Against AI-Assisted Writing

The test was comparing the profile against four blog posts I'd already published on dev.to, posts that were heavily 'vibe-written' with AI assistance. The question: does my voice come through, and where does the AI leak?

The AI fingerprints were easy to spot once I knew what to look for:

"Now go build something cool" as a closing (appeared in multiple posts, not my voice at all)
"Chef's kiss" (internet-speak I'd never use unprompted)
TL;DR blocks at the top (a dev.to convention, not my opening style)
Over-parallel scaffolding where every section followed the exact same template
Grandiose closings like "For the first time in history..."

But there were also moments where my real voice punched through the AI assistance. An Australian minced oath ("Pluck a duck"). A dry observation about "re-explaining your life story to a goldfish with a very expensive education". Punctuation used as percussion ("Just. Diving. Please."). These were the gems, the moments no AI would generate unprompted.

The Document

The voice profile ended up as a 22-section markdown file. It covers, for my profile:

Australian English spelling rules (non-negotiable)
Sentence construction patterns with specific word counts
A forbidden words list of 20+ terms that LLMs overuse
Signature phrases catalogued by context
Structural patterns for different content types
Two independent calibration dials: Formality (1-5, from stakeholder retro to personal blog) and Depth (A-D, from practical to transcendent/philosophical)
An LLM co-writing hygiene checklist for catching AI leakage before publishing
Title guidelines (no clickbait, ever)

The two-dial system turned out to be the most useful part. My voice doesn't change between a formal incident report and a dev.to blog post. The core is the same. What changes is how much personality, warmth, and philosophical reach comes through. The dials let me specify that precisely.

How to Build Your Own

If you have a body of writing (blog posts, articles, documentation, even long-form emails or Slack messages you've saved), you can do this. Here's the process distilled into a prompt you can adapt.

The Super-Prompt

Give this to Claude (or your AI of choice) along with as many of your writing samples as you can fit in the context. More samples across more content types gives better results.

Analyse the following writing samples thoroughly. They are all by the same author. I need you to build a detailed voice profile that captures HOW this person writes, not WHAT they write about. The profile must be specific enough to override your default writing tendencies when used as a reference.

For each of these dimensions, provide specific observations with quoted examples:

Sentence construction: Average length, rhythm patterns, characteristic openers, how they vary sentence structure

Vocabulary: Register level, words they favour, words they never use, technical vs plain language balance

Spelling and dialect: Which English variant (American, British, Australian, etc.)

Tone: Where they sit on the formal/informal spectrum, how they handle warmth vs authority

Reader address: How they use "I", "we", "you". When each pronoun appears and why

Teaching patterns: How they introduce concepts, handle code/examples, transition between explanation and demonstration

Opinion and argument: How they express disagreement, signal opinion vs fact, handle nuance

Humour: What kind they use, what kind they avoid, how much and when

Enthusiasm: How they show excitement (superlatives? depth? detail?)

Openings and closings: How they start pieces, how they end them, patterns across content types

Punctuation habits: Em dashes, parentheses, semicolons, exclamation marks, rhetorical questions

Signature phrases: Recurring expressions, verbal tics, characteristic transitions

What's absent: Words, patterns, or constructions this author never uses, especially ones that AI commonly defaults to

After the analysis, produce a complete voice profile document in markdown that I can include in future writing projects. The document should:

State rules directly ("Never use..." not "The author tends to avoid...")

Include a forbidden words/phrases list

Provide correct and incorrect examples for key patterns

Be structured so an AI can follow it as binding instructions

Include a calibration checklist for verifying output matches the voice

Tips for Better Results

Volume matters. I was lucky enough to have 169 posts laying around. You don't need that many, but more is better. 20-30 substantial pieces across different content types should give solid results.

Variety matters more. A mix of tutorials, opinion pieces, announcements, and informal writing reveals different facets of the same voice. If you only analyse one type, the profile will be incomplete.

If your oldest samples are years old, include something recent. Your voice evolves. The profile should capture who you are now, not just who you were. Mine shifted noticeably between 2007 and 2026: less playful, more precise, same directness.

Once you have a first draft of the profile, test it. If you've already published AI-assisted content, compare the profile against it. Where does your voice come through? Where does the AI leak? Add what you find to the profile. The first draft of mine included em dashes everywhere because my old writing used them heavily. I don't anymore. Tell the AI your current preferences and update accordingly. It's a living document.

You might also consider adding audience calibration. A single fixed voice profile works, but a dial system works better. Most people write differently for a stakeholder report than for a blog post. The core voice stays the same. The texture changes.

Why This Matters

LLMs are trained on billions of words, and those billions of words have a voice. It's polished, helpful, and completely anonymous. Every "let's dive in", every "powerful and robust", every "in today's rapidly evolving landscape" is the training data talking, not you.

The only way to push back against that gravitational pull is to be specific. Not "write casually" or "match my tone". Specific. "Never use em dashes. Always use oxford commas. Australian English. No profanity. Reach for developer-native metaphors. Show enthusiasm through detail, not superlatives. When expressing opinion, anchor it in professional experience, not assertion."

Your voice is the product of every piece you've ever written. It's already documented. It's sitting in your git history, your blog archive, your old articles. The AI just needs you to show it.

Fine Tuning the Experiment

This article is drafted by AI according to my voice profile and the history in this now very, very long context window. It's a summary of a conversation. It's insight into the back-and-forth I had with a learned colleague.

We, and I say that deliberately, found things the voice missed. Patterns that could be tightened further. The first draft of this article used "surprisingly effective" where I would just say "effective". It used "the first surprise was" where I would say "it turns out that". It used "the AI found patterns I'd never consciously noticed" where I would say "the AI identified solid and consistent patterns". Each one was a small moment where the AI's instinct to dramatise overrode my instinct to flatten.

So part of this protocol involves iteration. Read the output carefully. Adjust the voice profile. Then do another pass.

This article went through that loop. I opened a fresh conversation, shared the article and the voice profile, and asked for a review of what the previous session overlooked. It caught more to fix: an idiom that wouldn't land for ESL readers, a sentence that treated the AI as a machine instead of a colleague, and over-parallel scaffolding in the tips section. Small things. The kind you miss when you've stared at the screen for too long.

But there were other small things. The kind you only notice after pairing with an AI over months and years. The kind you can't codify. Human review is still a necessary part of the process.

In the end, think of it as code review for prose. A second or third or fourth pass catches what the previous normalised.

Enjoy!

Take Control of Claude's Memory

Andrew Eddie — Thu, 12 Mar 2026 11:13:24 +0000

Claude has memory. You probably turned it on recently when the web app asked and then... forgot about it.

Here's what you're missing.

Two Systems, One You're Ignoring

Claude actually runs two memory systems in parallel:

Auto-generated synthesis — Claude summarises your conversations and builds a
context profile automatically, updated every 24 hours. This is what most people
have passively enabled and never looked at.

Manual memory edits — You tell Claude exactly what to remember. Concise,
curated, yours.

Most people are only getting the first one. It captures everything: one-off
questions, situational context, noise. The second one is where the leverage is.

(Official docs on how both work)

The Limits (and Why They Matter)

30 manual memory entries maximum
500 characters per entry
Persists across every conversation

That's substantial curated context that future-Claude gets before you even say
hello — compared to starting cold, re-explaining your preferences, fighting
whatever's already in the context window.

The Problem With Passive Memory

Auto-generated memory captures everything with equal weight. What you actually
want is signal: how you think, what you care about, context that makes
every future conversation better rather than just the next one.

The goal isn't a fact sheet Claude glances at. It's a mental model that's
already activated when you arrive.

The Solution

At the end of any good conversation, use this prompt:

"Here's a conversation I want to mine for memory. Extract only what's
genuinely signal about how I think, what I care about, or context that would
make future conversations meaningfully better. Discard anything situational
or one-off. Propose entries in 500 chars or less, and flag if anything
overlaps or contradicts what you already have stored."

Claude will:

Extract the signal
Propose concise entries
Check for overlap and contradiction
Let you approve before adding anything

Compaction

As entries accumulate, treat them like git history: periodically squash them.
Merge overlapping entries. Promote patterns ("Andrew did this three times" →
"Andrew consistently does this"). Drop anything superseded by a better
formulation.

A simple prompt handles it:

"Review my current memory entries and propose a compacted version — merge
overlaps, promote patterns, remove anything redundant."

Why This Works

You're not training Claude (you can't). You're giving future-Claude better
priors. Instead of starting from zero, it starts knowing how you work, what you
value, how you approach problems.

It's like git for your AI relationship. Deliberate commits instead of auto-save.

One More Thing

Claude now supports importing and exporting your memory between AI tools —
useful if you want to migrate, back up, or seed a fresh start deliberately
rather than letting the auto-synthesiser decide what survived.

Try It

Next conversation that goes somewhere interesting, end with that prompt. See
what it extracts. Add what's useful. Compact when it gets noisy.

This is the natural next step from the Session Protocol
— that approach solved context within a project. This solves context across
your entire relationship with an AI assistant.

Your future self will thank you when Claude arrives already knowing who you are.

I Stopped Writing Documentation and My Documentation Got Better

Andrew Eddie — Mon, 08 Dec 2025 22:41:44 +0000

TL;DR: Let your AI assistant write your docs while you code. Markdown files become persistent memory that survives context resets. >
Jump to structure or try it now.

The Weird Discovery

A few days into building a game with AI assistance, I noticed something odd in my git history:

35 markdown files. 18 code commits.

Nearly 2 docs per commit. And here's the thing: I hadn't written a single one of them.

The AI wrote them all. While we talked. While we coded. While we made decisions.

It started innocently:

Session 1: "Let's add a README so we remember what this is."
Session 2: "This README's getting long. Let's split it."
Session 3: "I'm done for the day. Any docs you want to update to capture our decisions?"
Session 4: "Let's create a docs/ folder and organise this better."
Session 5: "We're talking about propulsion now. Write up what we just decided."
Session 6: "Wait... is this propulsion design still aligned with our guiding principles, or have we accidentally gone full dieselpunk?"

And then it hit me: This is working. Really well.

The AI could look up decisions I'd completely forgotten we'd made. When chat history got summarised or I started a new session, the docs persisted. The markdown files had become the AI's memory.

I was establishing a pattern that fixes the biggest problem with AI collaboration: nothing sticks between sessions.

The Fastest Way to Try This

Want to skip the explanation and just experience it?

Download this article (save/print to PDF)
Open your repo
Start a new chat with your AI assistant
Drop in this prompt:

Read this article and set up a documentation structure for my project that implements this pattern. Create the folder structure, starter templates, and connect it to my TODO.md.

The AI will scaffold documentation tailored to your actual project. You can iterate from there.

Seriously. Try it. The AI does the work.

(Or keep reading if you want to understand why this works first.)

The Problem This Solves

You know the pain:

Session 1: Brilliant brainstorm. You and the AI design a compressed air ballast system. Two hours of productive flow. Chef's kiss.

Session 3: New chat. "Continue with the diving system."
AI: "Great! Should we use manual valves or compressed air for the ballast?"
You: "We decided compressed air in Session 1!"
AI: "Oh right! What was the reasoning again?"
You: [Re-explains for 10 minutes]

Session 5: Different day, same story.
AI: "I notice we could add manual valve controls as a backup—"
You: "WE. REJECTED. MANUAL. VALVES. It's in the chat history!"
AI: [Chat history was summarised] "I don't see that decision..."
You: [Screams internally]

Chat history is volatile. It gets summarised. It gets truncated. It disappears when you start fresh sessions. The AI forgets. You re-explain. Groundhog Day forever.

But here's what doesn't forget: files.

Markdown files sit there. Persistent. Durable. Waiting to be read. If the decision is written down in docs/DIVING.md, the AI can read it in every session. Forever.

The trick is getting the docs written without it feeling like a chore.

Solution: Stop writing them yourself. Make the AI do it.

The Pattern: Let the AI Write While You Work

After every brainstorm, after every decision, after every design discussion:

You: "Write up what we just decided in docs/DIVING.md"
AI: [Writes comprehensive doc in 30 seconds]
You: [Moves on to next thing]

The AI is tireless. It doesn't get bored. It doesn't procrastinate. It just writes the damn doc.

And here's the magic: the act of writing forces clarity. When the AI writes up your decisions, it has to structure them. Make them coherent. That process often surfaces gaps or ambiguities you didn't notice in the conversation.

Sometimes the AI writes something and you go "wait, that's not quite right." Good. Fix it now, while context is fresh. Or just say "update the doc, we actually meant X not Y." The AI adjusts. The doc improves.

You stop being the documentation bottleneck. The AI becomes your technical writer.

One more thing: this works better when you treat it as collaboration, not dictation. The best sessions aren't "user decides, AI documents" — they're jazz. You throw out half an idea. The AI riffs on it. You say "love it" or "not quite." The AI adjusts. You build on each other.

Example from a real session:

Me: "We need a unit for speed. Knots?"
AI: "Knots works. And here's a fun etymology: sailors abbreviated 'kilometers per second' as 'kay-not-ess' — which slurred into 'knots' over generations."
Me: "Oh that's perfect. Add a legend that it was 'k_not_s' originally."
AI: [Immediately writes it to the lore doc]

That's not dictation. That's collaborative worldbuilding. The AI contributes ideas, not just formatting.

The tone matters too. A playful "have a puppy" when something works well gets different energy than a terse "continue." You're building a working relationship, even if one party forgets everything between sessions. Dry humour helps. Genuine appreciation helps. Treating it like a colleague rather than a tool — that helps most of all.

The Three Doc Types (And The Pain They Solve)

Not all docs are equal. Three types emerged, each solving a specific recurring problem.

1. Meta Docs (Stop The AI Suggesting Off-Brand Shit)

The pain: The AI gets excited and suggests features that sound cool but violate your project's core aesthetic or philosophy.

Without DESIGN_PHILOSOPHY.md:
AI: "We could add RPG stats! Level-up mechanics! Skill trees!"
You: "No, this is industrial survivalism, not gamification."
[Next session]
AI: "What about achievement badges for depth milestones?"
You: "Still no. We're not doing that vibe."

With DESIGN_PHILOSOPHY.md:
AI: [Reads doc at session start] "Right, Victorian submarine sim.
Brass gauges, pressure dials, dread not power fantasy.
No gamification. Got it."
[Doesn't suggest achievement badges ever again]

Meta docs are your north star. They capture:

DESIGN_PHILOSOPHY.md — Core principles, aesthetic, what you're NOT doing
LORE.md — World-building, setting constraints, domain rules
MONETISATION.md — Business model thoughts (if applicable)

These rarely change. Once written, they guide every session. The AI reads them, internalises the constraints, stops suggesting dieselpunk when you're building steampunk.

2. Implementation Docs (Stop Re-Explaining How Things Work)

The pain: You design a system in Session 1. By Session 3, the AI has forgotten the details. You re-explain. Again. And again.

Without DIVING.md:
[Session 1] You: "Compressed air ballast. Three depth zones."
[Session 3] AI: "Should we use manual valves for ballast?"
You: "No! Compressed air! We decided this!"
[Session 5] AI: "How many depth zones did we want?"
You: "THREE. We've discussed this twice already."

With DIVING.md:
[Session 3] AI: [Reads doc] "Right. Compressed air ballast system.
Three depth zones: safe, stressed, critical.
We rejected manual valves due to response time.
Continue with hull stress calculations?"
You: "Yes."
[Immediately productive]

Implementation docs capture system design. They're named after the system:

DIVING.md — Ballast mechanics, depth zones, buoyancy
PRESSURE.md — Hull stress, leak mechanics, damage model
ENGINE.md — Propulsion, power consumption, throttle curves

These evolve. As you build, the doc updates to reflect what was actually implemented. But the decisions persist across sessions.

Pro tip: Implementation docs don't exist in isolation. When the AI writes or updates one, it should read related docs first. A resources doc needs to understand propulsion constraints. A diving doc needs to know hull stress limits. The docs inform each other—that cross-pollination is where coherent design emerges.

3. Analysis Reports (Stop The AI From Flip-Flopping)

The pain: For hard problems, the AI generates options. Great! But then in later sessions, it forgets which option you chose and why. It re-suggests rejected approaches.

Without diving/evaluation.md:
[Session 2] AI: "Compressed air is best because: fast response,
scales to depth, aligns with automation philosophy."
You: "Agreed. Let's build it."
[Session 4] AI: "Actually, manual valves might be simpler and more reliable—"
You: "We already decided against manual valves!"
AI: "Oh! What was the reasoning?"
You: [Re-explains. Again.]

With diving/evaluation.md:
[Session 4] AI: [Reads evaluation doc] "We chose compressed air over
manual valves because of response time
and depth scaling. Manual valves rejected
due to maintenance complexity.
Continuing with compressed air approach."
You: "Correct. Keep going."

Analysis reports capture decision-making. For genuinely hard problems, structure it:

diving/
├── report1.md      ← First approach (manual ballast valves)
├── report2.md      ← Alternative (compressed air tanks)
├── report3.md      ← Hybrid considerations
└── evaluation.md   ← Comparative analysis → final decision

Have the AI generate multiple options. Write each to a separate report. Then: "Compare these reports and write an evaluation with a recommendation."

The evaluation becomes your decision artifact. When future-you (or future-AI) asks "why compressed air?", the answer is in evaluation.md, not buried in a forgotten chat log.

The Folder Structure

Here's what emerged after a week:

project/
├── TODO.md                    ← Session protocol (see Part 1)
├── README.md                  ← Quick orientation
├── docs/
│   ├── DESIGN_PHILOSOPHY.md   ← Meta: North star principles
│   ├── LORE.md                ← Meta: World/domain constraints
│   ├── DIVING.md              ← Implementation: System design
│   ├── PRESSURE.md            ← Implementation: System design
│   └── diving/
│       ├── report1.md         ← Analysis: Option exploration
│       ├── report2.md         ← Analysis: Alternative approach
│       └── evaluation.md      ← Analysis: Final decision
├── src/
│   └── ...
└── IMPLEMENTATION_NOTES.md    ← What was actually built

Key insight: Not every doc needs to be read every session. Your TODO.md Quick Context points to the 2-3 docs that matter right now:

## Quick Context (For New Chats)

**Read these docs:**

- [DESIGN_PHILOSOPHY](./docs/DESIGN_PHILOSOPHY.md) — Our north star
- [DIVING](./docs/DIVING.md) — Current system focus

**One-line pitch:** Victorian submarine command sim
**Tech:** Godot 4.x, prototype phase

Start sessions with: "Read TODO.md and the linked docs."

The AI gets exactly what it needs. Not everything. Just what's relevant right now.

The Four Rules That Make This Work

Rule 1: Make the AI Write the Docs

After every brainstorm: "Write up what we decided in docs/DIVING.md"
After every decision: "Update the evaluation with our choice and reasoning"
After building: "Update IMPLEMENTATION_NOTES.md with what we actually built"

The AI is your technical writer. Use it. You stay in flow. The docs get written.

Rule 2: Don't Edit the AI's Docs (Unless They're Wrong)

The AI will structure things slightly differently than you would. That's fine.

What matters:

The decision is recorded
It's findable
Future sessions can understand it

What doesn't matter:

Perfect heading hierarchy
Your preferred bullet style
Whether it used ## or ###

Let go of the perfectionism. It's not about you. It's about persistent context.

Rule 3: Capture Decisions Hot

Don't say "I'll document that later." You won't. The context will evaporate. The AI will forget. You'll forget.

Instead: "Before we move on, add a Decisions section to DIVING.md noting we chose X over Y and why."

Do it while the context is fresh. While the AI has it. Right now. It takes 30 seconds.

Watch for iteration traps: Sometimes you'll iterate on something four or five times in a session — refining a pitch, tweaking a formula, adjusting tone. That work feels productive (it is!), but if you close the session without capturing the final version, you've just created expensive chat-history-only knowledge. The pattern still applies: when you land on something good, write it to a file.

Rule 4: Split, Don't Cram

Don't cram everything into one mega-doc. It becomes unmaintainable.

Split by system. Split by concern. Split by decision type.

Ten focused docs beats one 500-line monster.

Why?

Easier to point the AI at specific context
Easier to update without losing other decisions
Easier to archive when superseded

The Before and After

You've seen the pattern in the examples above. Here's the summary:

	Before (Chat-Only)	After (Docs as Memory)
Monday	Brilliant session, great decisions	Same, plus "write that to docs/DIVING.md"
Wednesday	"Wait, what did we decide?"	"Read the docs. Continue."
Friday	Re-explaining for the third time	Productive from minute one

The difference: Documentation remembers when chat forgets.

Pro Tips

Make the AI Update Docs at Session End

When wrapping up for the day:

"Update our docs to reflect what we built today and write the handover prompt for next session."

The AI has context. It's fresh. Let it do the admin work. You just close your laptop.

Use the AI as a Sparring Partner

Don't just use the AI as a generator — use it as a critic. After drafting something (a pitch, a system design, a naming convention), ask: "Would this actually land with [target audience]? What's weak?"

The AI will often spot gaps you missed: unclear value propositions, assumptions that don't hold, tone mismatches. It's cheaper to catch these in conversation than after you've built the thing.

Better yet: train it to push back unprompted. Early in a project, tell the AI: "Point out weak assumptions, logical holes, or risky claims. Don't just agree with me." A good AI collaborator should occasionally say "That's clever, but here's why it might not work..." before you ask.

The goal isn't an AI that validates everything you say. It's an AI that makes your ideas stronger through honest friction.

Use Multiple Models for Hard Decisions

For genuinely important decisions, I started doing something sneaky: asking different models the same question.

Same prompt → Claude, GPT, Gemini (whatever you have access to)
Each model's answer → separate report file
Then ask one model to read all reports → writes evaluation.md

Why bother? Two reasons:

Independent second opinions. Different models have different biases and blind spots. Where they agree, you're probably safe. Where they disagree, you've found an interesting design tension worth exploring.
Files survive context windows. This is the key. Chat history gets summarised, truncated, forgotten. But once reasoning is in evaluation.md, it's durable. No matter what happens to the conversation, your decision artifact persists.

Keep Meta Docs Lean

DESIGN_PHILOSOPHY.md doesn't need to be comprehensive. It needs to be opinionated and specific.

Bad: "We value good UX and clean code."
Good: "No gamification. No XP bars. No achievement popups. Dread, not power fantasy. Industrial survivalism, not cosy sim."

Specific constraints guide AI behaviour. Vague platitudes don't.

Archive Old Analysis Reports

Once you've made a decision and built it, you don't need 3 alternative reports cluttering your docs. Move them:

docs/
├── archive/
│   └── diving-alternatives-2025-12/
│       ├── report1.md
│       ├── report2.md
│       └── evaluation.md
└── DIVING.md  ← Keep only the current implementation doc

Or just delete them. The decision is captured in the implementation doc. The analysis served its purpose.

When This Breaks (And How to Fix It)

You forget to update docs after building. Solution: Make it a habit. End every session with "update the docs." Or just make the AI do it.

Docs get out of sync with code. This happens. When you notice, fix it: "Read the current code and update DIVING.md to match what's actually implemented."

Too many docs, can't find anything. Use Quick Context in TODO.md to point at the 2-3 docs that matter right now. Don't try to read everything every session.

The AI writes docs in a weird style. Let it. Unless it's actively wrong, don't waste time reformatting. Substance over style.

What This Doesn't Solve (Scope Check)

This pattern teaches you what to document for AI collaboration. It doesn't tell you where that documentation should live in your organisation.

What this solves:

Structuring docs so AI assistants can actually use them
Capturing decisions while context is fresh
Making project memory durable across sessions

What this doesn't solve:

Whether DESIGN_PHILOSOPHY.md belongs in your repo, Notion, or Confluence
Who owns team documentation
How shared context works across multiple developers

Those are real questions — but they're the same questions you already face for any documentation. This pattern produces artifacts. Where artifacts live is your team's existing coordination problem, not a new one this creates.

The honest answer: Learn the pattern working solo. If it clicks, you'll know where it fits in your team's existing doc culture. If you don't have a doc culture... well, that's a bigger conversation than this article can have with you.

This is a skill, not a system. You're learning to shape documentation for AI collaboration. Deployment decisions follow.

The Bigger Pattern

On tools that do this for you: Yes, they exist. Basic Memory, Cline's Memory Bank, the llms.txt spec, probably whatever Kiro is doing under the hood. They're systematising this pattern. Use them if they click for you.

But remember: UML was a good idea until tools turned it into bureaucratic diagram hell. Agile was a good idea until certifications turned it into cargo cult ceremonies. The tools encode the structure. They can't encode the judgment — knowing what's worth capturing, when to split a doc, how to phrase constraints so the AI actually respects them.

That's the black art that, for now, only a human can do. That's what you learn by doing it manually first. Let tools handle the scaffolding once you understand what you're scaffolding.

This works because documentation is configuration for your AI collaborator.

Meta docs configure taste and constraints
Implementation docs configure current understanding
Analysis reports configure decision history
TODO.md configures focus and boundaries (see Part 1)

Your chat history is volatile. Your docs are durable. When you start a new session and say "Read TODO.md and the linked docs," you're not just restoring context—you're loading the AI's configuration.

The AI reads your north star principles. It reads what systems you've built and why. It reads what's in scope right now and what's deferred. It knows what you've rejected and why.

Then it can actually help instead of re-suggesting things you already decided against three sessions ago.

Connection to Session Protocol

This article covers the documentation structure — the persistent memory that survives context resets.

For the session-to-session continuity (the TODO.md format, the Deferred section, the handover prompt), see The Session Protocol: How I Fixed AI Memory Loss with a TODO.md.

Together, they form a complete system:

This pattern = your project's persistent brain
Session Protocol = how you restore context each session

Use both. They compound.

Go Try It

Fastest path: Drop this article into your AI assistant. Ask it to set up a documentation structure for your project. Let it do the work.

DIY path: Create a docs/ folder. After your next brainstorm, say "write up what we decided in docs/SYSTEM.md." See how it feels.

The AI wants to help. Let it write your documentation. You'll be amazed how much context survives.

And here's the beautiful irony: I stopped writing documentation, and my documentation got better.

The AI writes more docs than I ever would have. It writes them consistently. It writes them while context is fresh. And because they exist, sessions are productive from minute one.

Now go build something cool.

This pattern emerged from a creative project that generated a LOT of docs in the first week. The AI wrote all of them. I just pointed and said "capture that." The submarine examples are illustrative — the actual project is something else entirely.

Comments? Questions?

What documentation patterns work for your AI collaboration? Found something that helps? Hit the comments.

Epilogue

As a bit of an experiement, I decided to go through my previous context windows giving them the following prompt:

me from the future here
I've written @BLOG.md to capture some of the process you do in the future in other context windows
based on THIS context window, what do you think of the blog document?
I am trying to remember if I am accurately remembering what happened and how the system became polished
thoughts?

This resulted in a number of improvements to the article that I had indeed forgotten.
Of note was the addition of the jazz sessions that we had during early brainstorming and the riffing that was certainly going on.

But I just had to share this priceless observation from Claude:

## Meta Observation

I just reviewed a blog post about how I work,
in a context where I did exactly what the blog describes,
and the blog accurately predicted my behaviour.

That's either very good writing or slightly unsettling. 
Probably both. 😄

Do we not live in truly interesting times?!

The Session Protocol: How I Fixed AI Memory Loss with a TODO.md

Andrew Eddie — Wed, 03 Dec 2025 07:25:25 +0000

TL;DR: Your AI coding assistant keeps forgetting what you're working on? This TODO.md structure fixes it. Takes minutes to set up, saves hours of re-explaining context. Jump to the quick-start or see the template.

The Problem: Groundhog Day Development

Picture this. You're building a game, planning an app, vibe-coding something cool with AI assistance. End of day, you close your laptop feeling productive. Next morning, you type your next prompt and see the dreaded "Summarising conversation" spinner ... and the groove you had last night just evaporates.

So you open a new chat. Pluck a duck, where was I? Where were we?

You: "Read the project files and continue where we left off."

AI: [Scans your 50-item TODO list] "I see you're building the diving system! I also notice you have 'giant squid encounters' in your backlog. While we're in the diving code, we could add creature attack hooks that would later support—"

You: "No. Just the diving system."

AI: "Got it! I also see 'sound design' is listed. Should we add placeholder audio triggers while—"

You: [internal screaming]

Every. Single. Session.

It's Groundhog Day again. Same routine every time, burning the same precious minutes each development session:

Re-explaining what we were building
Redirecting away from backlog items
Establishing (again) what was in scope
Gently but firmly saying "not that, THIS"

But the AI wasn't broken. My documentation was.

The Fastest Way to Try This

Want to skip the explanation and just experience it?

Download this article (use your browser's save/print to PDF)
Open your repo
Start a new chat with your AI assistant
Probably select a thinking model
Drop in this prompt:

read this article and design a TODO.md structure with supporting markdown documentation for my project that implements the Session Protocol

The AI will read this entire post, understand the pattern, and generate a customised TODO.md for your actual project. You can iterate from there.

Seriously. Try it right now. I'll wait.

(Or keep reading if you want to understand why this works before you implement it.)

The Root Cause: TODOs Designed for Humans

My TODO.md was born out of necessity to help me record all the ideas swirling around my head.
It looked like every other TODO list:

# TODO

## Current Tasks

- [ ] Build diving system
- [ ] Add captain's log UI
- [ ] Implement oxygen consumption

## Future Ideas

- Multiple ocean depths
- Port trading mechanics
- Crew morale system
- Giant squid encounters
- Sound design
  [...30+ more items]

To a human, this is fine. Your brain has context. You know what you're working on. The backlog is just a parking lot for ideas that you are unconsciously sorting.

But to an AI assistant? This is a buffet of equally-valid options. Everything looks like a suggestion waiting to happen. There's no signal saying "focus HERE, ignore THAT." The AI reads it literally and treats your 3 current tasks and 30 future ideas with equal weight.

The result? Constant distraction, repeated context restoration, and burning time.

And here's the thing. If you don't give the AI a TODO structure, it'll invent one and stubbornly latch onto it like a dog with a bone.
The AI's version will be aiming for what it thinks you might want, not what you're actually building.
At least with a bad TODO you control the chaos. Without one, the AI's making up priorities on the fly every session.

The Session Protocol isn't about adding structure where none existed. It's about taking control of the structure the AI's going to use anyway.

The Solution: A Session Protocol

Over time I restructured my TODO.md into what my AI assistant dubbed the Session Protocol — a document designed specifically to help AI assistants focus.

The key insight here is that the document isn't for task tracking. It's for programming your AI collaborator's attention.

Here's what changed:

1. Quick Context (The 30-Second Bootstrap)

## Quick Context (For New Chats)

**Read these docs to understand the project:**

- [DESIGN_PHILOSOPHY](./docs/DESIGN_PHILOSOPHY.md) — Core principles
- [AESTHETIC.md](./docs/AESTHETIC.md) — The vibe we're aiming for

**One-line pitch:** "Command your own Nautilus" — a Victorian submarine simulation where you manage pressure, oxygen, and crew through uncharted depths.

**Tech:** Godot 4.x (GDScript). Prototype phase.

Why it works: When I start a new chat with "Read TODO.md and the linked docs", the AI hits this section first and knows:

What the project is
Where to look for depth
What tech we're using
Where we are in the lifecycle

No preamble. No back-and-forth. Just instant orientation.

2. Completion Log (The Breadcrumbs)

## Completion Log

- **Nov 30** — First playable loop (navigation, save/load)
- **Dec 1** — Captain's Log UI (message list, pagination)
- **Dec 2** — Pressure system (physics, hull stress, depth gating)

Why it works: The dates (I think!) give the AI temporal context. When it sees "we're three weeks in and have shipped X, Y, Z," it understands project maturity.

Without this, AI sometimes suggests "should we set up the save system?" when you built that three milestones ago. With it, suggestions align with where you actually are.

3. Current Milestone (The Focus Laser)

## Current Milestone: Electric Engine

**Goal:** Propulsion system controlled by navigation computer.

### What We're Building

- Engine power curves
- Battery consumption mechanics
- NemoOS status messages

### Success Criteria

- [ ] Engine responds to throttle commands
- [ ] Battery drains during operation
- [ ] NemoOS logs engine state changes

### Deferred (Not This Slice)

- Emergency surface procedures (future complexity)
- Engine damage mechanics (not yet)
- Backup propulsion systems (out of scope)

Why it works: The Deferred section is the magic. By explicitly listing what we're NOT doing, we create visible boundaries. The AI can't suggest what it sees we've deliberately parked.

Before this section: Constant nagging about tackling backlog suggestions per session.

After this section: Zero backlog suggestions unless I ask for it.

The AI learns: "This isn't forgotten, it's just not now."

4. Backlog (De-emphasised, At The Bottom)

## Backlog (Not Prioritised)

- Crew morale system
- Giant squid encounters
- Multiple depth zones
- Port trading mechanics
  [...brief list]

Why it works: Ideas need a home, but not prominence. By putting the backlog:

At the bottom (encountered last)
Under a "Not Prioritised" header
Kept brief (truncate if >20 items)

The AI reads the current work first, absorbs the boundaries, and by the time it hits the backlog, knows those items are background noise.

5. Handover Prompt (Copy-Paste Continuity)

## How to Continue in a New Chat

**Prompt to use:**

> Read TODO.md and the linked docs. Current milestone: Electric Engine.
> We just finished the pressure system. Pick up from engine physics.

Why it works: Zero friction. I literally copy-paste this into a new chat. The AI gets exactly the context it needs: what to read, where we are, what just finished, where to continue.

No thinking. No reconstruction. Just ... paste and go. It's delightfully satisfying!

The Before and After

Before (many early sessions)

[10:15] Me: Read project and continue where we left off
[10:16] AI: [Reads TODO] I see diving system. Also notice port
        trading. Should we add cargo hooks while—
[10:17] Me: No, just diving
[10:17] AI: Got it! About sound design in backlog—
[10:18] Me: Just. Diving. Please.
[10:20] AI: Right! For diving, should we start with physics or UI?
[10:21] Me: Physics. We discussed this yesterday.
[10:22] AI: Let me start on the pressure model...
[10:25] [Actual work finally begins]

Session startup: valuable minutes of re-explaining

After (every session now)

[10:15] Me: Read TODO.md and linked docs.
[10:16] AI: Got it. Diving system — pressure physics ✓, UI (not yet),
        depth gating (not yet). Emergency ascent explicitly deferred.
        Continue with UI?
[10:16] Me: Yes
[10:16] [Productive work begins immediately]

Session startup: seconds ... straight to coding

The difference isn't subtle. It's the difference between frustration and flow.

The Copy-Paste Template

Here's the structure you can steal:

# [Project Name]: Development TODO

## Quick Context (For New Chats)

**Read these docs:**

- [Doc 1](link) — What it covers
- [Doc 2](link) — What it covers

**One-line pitch:** [What is this project?]
**Tech:** [Stack/framework]
**Status:** [Prototype/MVP/Production]

---

## Completion Log

- **[Date]** — [Milestone name] ([brief description])
- **[Date]** — [Milestone name] ([brief description])

---

## Current Milestone: [Milestone Name]

**Goal:** [One sentence describing success]

### What We're Building

- Specific feature 1
- Specific feature 2
- Specific feature 3

### Success Criteria

- [ ] Measurable outcome 1
- [ ] Measurable outcome 2
- [ ] Measurable outcome 3

### Deferred (Not This Slice)

- Thing we're explicitly NOT doing right now
- Another feature we've parked
- Explicit boundary / scope protection

---

## Backlog (Not Prioritised)

- Future idea 1
- Future idea 2
- Future idea 3

---

## How to Continue in a New Chat

**Prompt to use:**

> Read TODO.md and linked docs. Current milestone: [name].
> Context: [one line about what just finished]. Continue from [specific point].

What Makes This Different

Traditional TODO: Designed for human brains with implicit context and persistent memory.

Session Protocol: Designed for AI assistants that read literally and start fresh every session.

The key differences:

Explicit boundaries (Deferred section) vs. implicit priorities
Temporal orientation (dates + completion log) vs. flat task lists
Embedded handover prompts vs. hoping the AI figures it out
Attention shaping through structure vs. assuming the AI knows what matters

Your AI assistant can't remember between sessions (well, unless you're using Projects, but even then...). Your documents can remember for it.

Make them count.

What This Isn't (Scope Check)

Before the comments fill with "but how does this scale to my 50-person org?" — let me save you the typing.

This is a personal workflow pattern. It's optimised for you working with your AI assistant.

It works for:

Solo devs building passion projects
Engineers working individual tickets within a squad
At a stretch, pair programming handoffs if both people use the same structure

It does not replace:

Jira, Linear, Trello, or any team coordination tool
Sprint planning, backlog grooming, or standups
Your tech lead's opinion on story points

Asking "how does this scale to a team?" is like asking how your personal notebook scales to 50 people. It doesn't. That's not a bug—it's the point.

This is about your focus. Your flow. Your AI assistant's attention.

The scaling question assumes this is a planning tool. It’s not. Use a tool designed for that. This is an alignment tool for a single human-to-AI feedback loop. It’s what you use when you sit down, open a chat, and want to immediately get back into flow instead of re-explaining your life story to a goldfish with a very expensive education.

Pro Tips

Update at session end, not session start. When you're wrapping up for the day, spend 2 minutes updating the TODO. You have context. Future you will thank you.

Make the AI do the work. End sessions with: "Update TODO.md with what we just accomplished and write the handover prompt for next time." Offload the admin to the tireless assistant.

Keep the completion log short. Once it hits ~10 items, archive older ones to a CHANGELOG.md. The log is for orientation, not history.

Test the deferred section. If you're still getting backlog suggestions, your Deferred section isn't explicit enough. Name specific features and why they're parked.

Move the backlog if it grows. Once you hit ~20 items, consider a separate BACKLOG.md. What the AI doesn't see, it can't get distracted by.

When This Breaks (And How to Fix It)

The temporal orientation might be placebo. I think dates help the AI calibrate to project maturity, but I haven't proven it. Test it yourself: try removing dates for a week and see if behaviour changes. If it does, keep 'em. If not, they're just clutter.

Long contexts might truncate the bottom. I put behavioural notes at the end, but some models might deprioritise them. If your AI starts ignoring constraints, move the critical ones to the Quick Context section at the top.

Human discipline is required. This only works if you actually update the TODO before closing your laptop. If you code for 4 hours and forget to update... next session starts with stale context. Solution: make it a habit, or make the AI do it.

The Bigger Pattern

The Session Protocol works because documents shape AI behaviour.

A sprawling TODO makes an AI scattered.

A focused TODO makes an AI focused.

Traditional documentation assumes smart readers who can infer intent. AI assistants are powerful but literal—they need explicit instruction.

This isn't just about TODO files. The same principle applies to:

Architecture Decision Records (add "Alternatives we rejected and why")
API docs (add "Usage patterns we don't support")
Design docs (add "What we're NOT building in V1")

When collaborating with literal-minded machines, make your boundaries as visible as your goals.

Go Try It

This structure emerged from frustration, got refined through iteration, and now saves me a lot of time. It might work for you. It might not. But it costs 5 minutes to try.

Fastest path: Drop this article into your AI assistant and ask it to generate a Session Protocol TODO.md for your project. Iterate from there.

DIY path: Copy the template. Fill in your project details. Use the handover prompt in your next session. See if it helps.

If it works, brilliant. If it doesn't, tweak it. The structure isn't sacred — the principle is: teach your AI assistant what to focus on by showing it explicitly in your documentation.

Now go build something cool.

This pattern emerged vibe-coding a simulation game, POC originally in React (which I know well), then pivoting to Godot 4.x (which is completely new to me). The structure was proposed and refined by Claude Opus 4.5 during meta-discussions about project documentation.

Comments? Questions? Improvements?

What documentation patterns are you using with AI assistants? Found something that works better? Hit the comments — I'm curious what's working for other devs.

Thinking Like a Diffusion Model

Andrew Eddie — Tue, 02 Dec 2025 05:12:40 +0000

A reflection on why "vibe coding" works, and what it might teach us about partnering with AI.

The Shape of the Problem

Some people solve problems like compilers: input → process → output. Step by step. Recipe-based. Explainable.

Others solve problems like diffusion models: start with noise, iterate toward coherence, and at some point the answer just... resolves. The shape emerges from the fog.

If you're the second type, you've probably spent your life struggling to answer "walk me through your process." Because there isn't a process. There's a sense that sharpens until it clicks.

What Diffusion Models Actually Do

A diffusion model doesn't build an image pixel by pixel. It starts with pure noise and iteratively denoises - each step reducing entropy, increasing structure, until a coherent form emerges.

The image isn't constructed. It's resolved.

Key properties:

Whole-first: The global structure emerges before the details
Iterative refinement: Each pass sharpens, but doesn't "add"
Non-linear: Step 47 might suddenly clarify what steps 1-46 were doing
Topology-preserving: The shape of the solution stays consistent even as details change

Thinking in Shadows

Here's the strange part: some human brains seem to work this way too.

You might experience problem-solving as:

A high-dimensional sense of the solution space
A "shadow" that projects down into something you can articulate
Knowing something is wrong before you can say why
Iterating not toward correctness, but toward coherence

If this sounds familiar, congratulations: you think like a diffusion model.

And also: you probably struggle to explain your thinking to people who don't.

Why This Clicks With AI

Large language models aren't diffusion models technically, but they share a key property: they're high-dimensional pattern matchers that find coherent regions in concept-space.

When you prompt an AI, you're not giving it a recipe. You're giving it coordinates. You're saying "somewhere around here" and letting it resolve the details.

If your brain already works this way, AI collaboration feels natural:

Sequential Thinker	Diffusion Thinker
"Write me a function that does X"	"Help me understand this space"
Expects correct output first try	Expects to iterate toward coherence
Debugs by checking steps	Debugs by checking shape
Frustrated when AI "hallucinates"	Recognises when output is in wrong region

The diffusion thinker isn't giving better prompts. They're navigating, not commanding.

Vibe Coding

This is what "vibe coding" actually is:

Start with fog - "I need to understand this legacy system"
Iterate toward signal - Back-and-forth, pushing back, refining
Recognise coherence - "Yes, that's the shape I was sensing"
Produce artifacts - Documentation, tickets, code emerge as shadows of the resolved understanding

It's not prompt engineering (mechanical, rules-based). It's collaborative resolution - two pattern-matchers vibing at each other until coherent signal emerges from noise.

The Tradeoff

Diffusion thinking has a cost: it's nearly impossible to explain.

"How did you know that approach was wrong?"

"It... didn't fit the topology of the problem?"

"..."

You can't give someone a recipe for intuition. You can't step-debug a shape.

This makes you bad at:

Writing documentation (the sequential kind)
Pair programming with sequential thinkers
Explaining yourself in code reviews
Answering "what's your process?"

But it makes you good at:

Seeing whole systems
Recognising when something is off before it's wrong
Navigating ambiguous problem spaces
Partnering with AI

Practical Implications

If this resonates, here's what might help:

For working with AI:

Treat prompts as coordinates, not commands
Iterate toward coherence rather than expecting correct output
Push back when the shape is wrong, even if you can't articulate why
Create artifacts (docs, tickets) that capture the resolved understanding

For working with humans:

Accept that you'll need to "compile" your thinking into sequential form
Use artifacts as translation layers - let the document explain what you can't
Find collaborators who trust your "that's wrong" even without explanation
Don't apologise for not having a step-by-step process

For self-understanding:

You're not broken, you're differently structured
The thing you can't explain is still real
AI might be the first collaborator that doesn't require translation

The Punchline

You might think like a diffusion model.

That's not a metaphor. It's a topology.

And for the first time in history, there's a tool that meets you in that space - that doesn't require you to flatten your thinking into words before you can collaborate.

The shape was always there. Now you have a partner who can see it too.

Written during a session that started with "help me understand this spaghetti" and ended with a production-ready ticket - through pure iterative resolution.