{ "version": "https://jsonfeed.org/version/1", "title": "enumerator.dev", "icon": "", "home_page_url": "https://enumerator.dev/", "feed_url": "https://enumerator.dev/feed.json", "items": [ { "id": "https://enumerator.dev/brain-burger/", "title": "Brain Burger", "content_html": "

I have tried to describe my agentic coding workflows as they’ve evolved and Emily captures it perfectly. I use a Brain Burger (or Brain Sandwich):

\n
    \n
  1. My brain, and then
    2. \n
  2. AI, and then
    3. \n
  3. My brain
    4. \n
\n

via The Brain Sandwich

\n", "date_published": "2026-09-29T00:00:00+00:00", "url": "https://enumerator.dev/brain-burger/", "tags": ["ai"] }, { "id": "https://enumerator.dev/differently-difficult/", "title": "Differently Difficult", "content_html": "

In AI Didn’t Make Programming Easier. It Just Made It Differently Difficult, Jeremy Osborn writes:

\n
\n

In other words, the hard part moves from recall (“How do I write this?”) to judgment (“Does this actually make sense?”). This shift from recall-based to judgment-based programming represents the fundamental cognitive transformation at the heart of AI-assisted development. Where traditional programming demanded that developers maintain vast internal libraries of syntax, patterns, and idioms, AI-enabled programming demands instead they maintain robust evaluative frameworks for assessing correctness, coherence, and appropriateness. The cognitive burden has not disappeared—it has relocated from retrieval to reasoning.

\n
\n", "date_published": "2026-09-29T00:00:00+00:00", "url": "https://enumerator.dev/differently-difficult/", "tags": ["ai","career-growth"] }, { "id": "https://enumerator.dev/how-i-use-ai-when-writing/", "title": "How I use AI When Writing", "content_html": "

I use AI when I write for work.

\n

And like you, I hate slop.

\n

Despite LLMs writing like someone I would never want to spend time with, I still find some of their output useful.

\n

They speed up research, even if they are confidently wrong.

\n

And they are mediocre grammar checkers and good enough document structure editors, even if they are obtuse.

\n

My Writing Standards

\n

When My Writing is Personal

\n

I don’t write personal things with AI. This includes text messages, emails to friends and family, and Slack messages, comments on documents.

\n

When I Write for this Blog

\n

Most of my writing on this blog is free form with limited edits. I hit publish and then find a mistake when I read it on my site and I’m quite okay with that.

\n

However, I use LLMs to assist with research and validation. Every now and then, I’ll do a double check on grammar and structure with a writing tool like LanguageTool or Grammarly, and I’ll occasionally accept phrasing that an LLM suggests if it suits my needs.

\n

When My Writing is An Artifact for Work

\n

At work I write documentation and proposals that are artifacts the company can discuss and work with.

\n

I use today’s AI tools to research ideas, validate my assumptions, fact-check my work, and edit the document’s structure. More on this later.

\n

When Writing Generates Code

\n

I write to AI agents in the form of chat interfaces, documents, and structured prompts to generate code. I use all the tools available to me:

\n\n

Essentially, there are no rules when I write in order to generate code. I don’t even consider most of this “writing.” But it does result in generated text that has my name attached to it.

\n

How I use AI to Write an Artifact

\n
    \n
  1. Use a number of agents to do research. This often involves getting a coding agent to research and test ideas in a code repository, sending an agent with computer use off to do web research and produce a document, or chatting with an LLM to validate ideas.
    2. \n
  2. Save agent-generated artifacts. Between chat sessions, I get the agents to save artifacts other agents can find. Coding agents write docs, desktop agents find and read those docs and generate text files or docs through an MCP connector, and chat agents generate text I copy-paste elsewhere.
    3. \n
  3. Write a doc in my own words. After iterating with agents to build an understanding of what I’m writing, I start writing in my own words. The result is a document that is well-researched and thought-through. And very human. It has my tone, thought process, and mistakes.
    4. \n
  4. Edit with an LLM. I have two prompts that I use to edit both my work and docs the agent generates. For my own writing, I prefer to make the edits myself. Occasionally, I agree with the LLM’s feedback but am stumped on how to make a change, so I’ll ask for ideas.
    5. \n
  5. DON’T TRUST THE LLM. I use my judgement when the LLM gives me feedback. Its generated response often has good points that slightly miss the mark. I take those into account and use my own words.
    6. \n
  6. Use LLM-generated text when it helps. It feels like I’ve admitted to a mortal sin here. I am writing for business, and LLMs are trained on business applications. I have no problem copy-pasting a sentence from an LLM at this point because I’ve done the legwork and the LLM is helping with polish.
    7. \n
  7. DON’T ARGUE WITH THE LLM. It is going to generate text that makes no sense. Ignore this. When I have tried to correct things the LLM gets wrong, it begins to misunderstand the task overall. I often tell it what was good and then say something like “You can do better than this, I know you can. Give it a second, more thoughtful pass.” If is WEIRD to say things like that to a computer, but it works for me.
    8. \n
  8. Share my work. I share a document with two sections. The first is my writing. The second is a summary of the LLM’s research, generated by the LLM. I flag this as AI-generated content in a BIG banner at the top. [EDIT: Oct 3, 2026] I no longer find value in the AI generated section. I share my writing with a notice at the top explaining the document was written by me with AI assisted research.
    9. \n
\n

AI Agent Prompts

\n

Research Prompts

\n

In my research prompts, I tell the agents my objectives, opinions, and assumptions. This context helps the agent focus on the outcome I am asking for. It also forces me to think about my opinions and assumptions. I expect the agent to confirm my assumptions and push back on my opinions. If it doesn’t do this, I ask it to.

\n

Here is a template of a prompt I use:

\n
I am researching <feature>. I need you to research <technology> in this\nrepository and write a summary that explains the current state.\n\nFocus on <area of code>.\n\nIgnore <similar but irrelevant area of code>.\n\nMy objective is to <write your objective>.\n\nMy opinion is that <what I think the research will reveal and what decision\nI lean towards already>.\n\nMy assumptions are <how the repo works, how the technology works with the\nrepo, etc.> \n

Prompts for Editing

\n

I have been working on a skill I call “Writing for Understanding” that is based on a number of accessible writing standards from government websites and based on my own experience. I pass all of the writing through this with the following prompt:

\n
/writing-for-understanding read @doc and give me feedback one bullet\npoint at a time. Don't edit the doc. I will make the edits myself.\n

I also use Anil Dash’s Better Documents with a similar prompt. This is where I often get stuck! The LLM makes good recommendations based on Anil’s skill, but I sometimes don’t have an idea at my fingertips. In this case, I ask the LLM for ideas for restructuring the doc.

\n

I prefer to make these edits myself, even if it means copying some AI-generated text into my final output.

\n", "date_published": "2026-09-21T00:00:00+00:00", "url": "https://enumerator.dev/how-i-use-ai-when-writing/", "tags": ["ai","writing"] }, { "id": "https://enumerator.dev/self-host-something/", "title": "If You Make Software, You Should Self-Host Something", "content_html": "

If you write software for your job, you probably write software that runs “in the cloud” somewhere that users access it over the internet.

\n

Do you know how all of this works?

\n

Probably not.

\n

I don’t doubt your skills and knowledge as a developer. Software deployments are so complex, even small companies have teams dedicated to managing deployment and uptime.

\n

Self-hosting something–anything–can teach you a lot about how software runs on the web. Knowledge that is essential to being an excellent engineer.

\n

While your company might deploy with Kubernetes triggered by your git workflow, the fundamentals of how software runs on a computer aren’t that different between a small self-hosted VPS and a k8s deployment.

\n

What Should You Self Host?

\n

There are plenty of open source projects you can self-host these days. You can deploy any of these just to try them out and then tear down your server. Here are a few ideas:

\n\n

Where Should You Host?

\n
    \n
  1. Your own computer.\n
      \n
    1. Start here. You already have this computer! Edit your local /etc/hosts file to give yourself a fun domain that you can access from your local system. But you write software for the web, right? So you should deploy to a virtual private server.
      2. \n
    \n
    2. \n
  2. A Virtual Private Server\n
      \n
    1. Find a provider of your choosing and deploy a small VPS. Get this connected to the internet and deploy an app. Find a free subdomain provider and connect it to your VPS.
      2. \n
    \n
    3. \n
  3. A Computer at Home\n
      \n
    1. If you have a spare computer you can keep running, set up a web server on it. This will require more tinkering and probably require a reverse proxy to expose it to the public internet.
      2. \n
    \n
    4. \n
\n

How To Host?

\n
    \n
  1. Manual! You’ll learn the most this way. Follow the install instructions on the app you chose to get it up and running. Once you can log in, celebrate!
    2. \n
  2. Automated(ish). YunoHost is a software for managing your server. Once you’ve done it manually, you’ll appreciate all the work that’s gone int to YunoHost. The docs help you understand how user roles work on the operating system and how applications are protected from reading one another’s data.
    3. \n
\n

Self Host for Fun

\n

You really don’t need to keep apps up and running. Remember that the point is to get something out here, break it, and learn to fix it. Along the way you’ll learn about unix systems, application processes, resource management, backups, downtime and application resiliance.

\n

Try self-host something and have some fun.

\n", "date_published": "2026-09-21T00:00:00+00:00", "url": "https://enumerator.dev/self-host-something/", "tags": ["self-hosting","career-growth"] }, { "id": "https://enumerator.dev/what-is-mcp/", "title": "What is MCP: A No Bull Explainer", "content_html": "

Model Context Protocol (MCP) is a way for AI Agents to connect to an external application (usually on the internet) to gather information and perform tasks.

\n

That’s it. No magic.

\n

Breaking Down the Jargon

\n

I have read so many descriptions of AI tools that are riddled with jargon. “MCP is a HTTP-stream-based protocol for agentic interfaces.” “MCP does not use SSE because it now favours streamable HTTP.” “MCP is a stdio-based server to connect to an LLM.”

\n

Blah blah blah.

\n

Model context protocol is a standard that uses existing technologies. The standard is new. The technologies are not.

\n

HTTP is a transport protocol that defines how two applications connect and communicate over the internet.

\n

MCP is a semantics protocol that defines how LLM-based software can perform actions in another application. MCP connections are often transmitted over HTTP using POST requests.

\n

The Simplest MCP Connector

\n
    \n
  1. An HTTP endpoint that responds to POST with JSON-RPC in the content type, and GET that returns 405 Method Not Allowed. The GET endpoint can be used for an event stream, but we’re focusing on simplicity here.
    2. \n
  2. The POST body is a JSON-RPC request object and the server replies synchronously with a single JSON-RPC response object.
    3. \n
  3. The client sends id, method: "initialize", protocolVersion, capabilities, and clientInfo.
    4. \n
  4. The server responds with protocolVersion, capabilities, serverInfo.
    5. \n
  5. The client then POSTs notifications/initializedand the server replies 202 Accepted with empty body.
    6. \n
  6. Tada! We have a connection!
    7. \n
  7. The AI Agent POSTs tools/list to fetch tools or tools/call with an id.
    8. \n
  8. The server always responds with an id that matches request id.
    9. \n
  9. The AI Agent uses the id to keep track of which response belongs to which request. We’re doing HTTP here, so the ID is superfluous, it is essential if you add an HTTP stream that can respond to multiple calls.
    10. \n
  10. Errors: JSON-RPC error object (code/message) in place of result, still plain POST/JSON, no special HTTP status needed beyond 200.
    11. \n
\n

NEW!

\n

MCP sessions are now stateless. Are you managing Mcp-Session-Id? No need!

\n
sequenceDiagram\n    participant C as AI Agent\n    participant S as Server\n    C->>S: POST / {method: initialize, id: 1}\n    S-->>C: 200 result: protocolVersion, capabilities, serverInfo, id: 1\n    C->>S: POST / {method: notifications/initialized}\n    S-->>C: 202 Accepted (empty body)\n    C->>S: POST / {method: tools/list, id: 2}\n    S-->>C: 200 result: tools, id: 2\n    C->>S: POST / {method: tools/call, id: 3}\n    S-->>C: 200 result or error, id: 3
\n

Misconceptions About MCP

\n

MCP No Longer Recommends Server Sent Events

\n

This confusion comes from the semantics of “Streamable HTTP” vs SSE (Server Sent Events). The MCP spec used to require SSE for remote connections and std IO when the MCP was on the same host as the agent. The original specification in 2024 required an SSE endpoint and a separate /messages endpoint.

\n

In the current spec, MCP requires one endpoint with an optional upgrade to SSE. The wording is confusing here because the spec references Streamable HTTP under “Transports” and states that this is a replacement for HTTP+SSE. These statements are accurate, but once you read the spec, you realize that the only way to implement Streamable HTTP is by using server-sent events.

\n

MCP Is Just an API

\n

If you want to split hairs and say that since API stands for “Application Programming Interface,” then, yes, it is an interface of sorts for programming an application.

\n

But your hair splitting would be out of touch with the way people talk. API these days usually means a set of HTTP endpoints that responds with JSON accessed over REST or GraphQL.

\n

JSON APIs have been around for a long time now! And many of them don’t work well with AI agents. A large API specification is hard for an agent to reason about, which makes it difficult to accomplish tasks with a 1-1 mapping between an API and an MCP tool.

\n

MCP defines the semantics that give agents the information they need to string together novel workflows and tasks.

\n

MCP is a New Technology

\n

MCP is only a new standard. It is based on existing technologies, and this is what makes it powerful. The MCP standard lets us quickly develop new user experiences because it uses existing technologies for connecting two applications.

\n", "date_published": "2026-09-18T00:00:00+00:00", "url": "https://enumerator.dev/what-is-mcp/", "tags": ["ai","mcp"] }, { "id": "https://enumerator.dev/everything-was-done-with-an-ascii-editor/", "title": "Everything was done with an ASCII editor", "content_html": "

The Super Metroid – FAQ/Speed Guide is 17,000 words of perfectly-spaced, full justified, mono-spaced text. It’s beautiful to look at.

\n

From the FAQ

\n
\n

What program did you use to justify the text?

\n

None. I just chose words carefully so that everything lined up on the right hand side. Everything was done with an ASCII editor.

\n
\n

via Unsung via Hacker News

\n

This reminds me of the hours I spent in a trance tracking, kerning, and editing text to create a triangular brochure that folded out into a tessellation with full-justified text that fit perfectly into each repeated triangle.

\n", "date_published": "2026-08-31T00:00:00+00:00", "url": "https://enumerator.dev/everything-was-done-with-an-ascii-editor/", "tags": ["writing","ai"] }, { "id": "https://enumerator.dev/llms-dont-write-they-generate/", "title": "LLMs Don't Write, They Generate", "content_html": "

Everyone is mad about AI watermarking.

\n

The thing is.

\n

These machines don’t write.

\n

They generate text.

\n

Writers write. Machines generate. LLMs can watermark text without affecting the quality of the output because they are benchmarked on the usefulness of their output rather than the meaning of the text.

\n

LLMs don’t reflect on meaning, consider their audience, and convey thoughts with care.

\n

LLMs generate a probable output to the input. That’s all.

\n

AI companies don’t value writing because they’ve never thought about writing. AI companies value the likelihood that the machine produces useful output. Not a meaningful output.

\n

LLMs have gotten really good at generating probable outputs that are productive.

\n

But it’s still probable. And only mostly productive. But rarely meaningful.

\n

Saying that an LLM writes is as accurate as saying a lawn mower gardens, an airplane vacations, or a microwave is a chef.1

\n
\n
\n
    \n
  1. \n

    Ha! Oh dear. I wanted to write the word “cooks” here but I can’t. Is there another word for “cooks with great culinary skill” in English? Perhaps language is changing and LLMs do, in fact, “write” with the same skill that a microwave cooks. ↩︎

    \n
    2. \n
\n
\n", "date_published": "2026-08-18T00:00:00+00:00", "url": "https://enumerator.dev/llms-dont-write-they-generate/", "tags": ["writing","ai"] }, { "id": "https://enumerator.dev/tenets-of-storytelling-how-to-write-a-technical-document/", "title": "Tenets of Storytelling: How to Write a Technical Proposal", "content_html": "

Sophie Alpert recently posted her internal policy on the acceptable use of AI for writing technical documents, which included this line:

\n
\n

More time should be spent authoring a document than consuming it.

\n
\n

Similarly, Over at The Marginalian Maria Popova has been posting about reading more and writing better.

\n

This week, she posted Kurt Vonnegut’s 8 Tenets of Storytelling, which includes a similar line:

\n
\n

Use the time of a total stranger in such a way that he or she will not feel the time was wasted.

\n
\n

Vonnegut’s tenets can teach us something about technical writing, especially these days when an LLM can generate a seemingly polished technical document in seconds.

\n

I’m sure Vonnegut would loath being a technical writer and despise being quoted for technical writing.

\n

Nonetheless, here are Vonnegut’s eight tenets rewritten by yours truly as tenets for writing technical proposals. Unsurprisingly, some of these tenets work, word-for-word.

\n
    \n
  1. Use your colleagues’ time wisely. They will thank you for it.
    2. \n
  2. Give your audience at least one thing to be excited about.
    3. \n
  3. Every component should do something useful, even if only to write a log.
    4. \n
  4. Every sentence must do one of two things — reveal details or propose action.
    5. \n
  5. Start as close to the solution as possible.
    6. \n
  6. Be a Sadist. No matter how much you or your team love a feature, show its faults so you can make good decisions.
    7. \n
  7. Write to please just one person. If you solve every technical problem, your proposal will get pneumonia.
    8. \n
  8. Give your readers as much information as possible as soon as possible. To hell with suspense. Readers should have such complete understanding of what is going on, where and why, that they could finish the design themselves, should entropy degrade the last few bytes.
    9. \n
\n", "date_published": "2026-08-13T00:00:00+00:00", "url": "https://enumerator.dev/tenets-of-storytelling-how-to-write-a-technical-document/", "tags": ["writing"] }, { "id": "https://enumerator.dev/technical-diagrams-for-communication/", "title": "Technical Diagrams for Communication", "content_html": "

How many ways are there to draw the same diagram? Lots! It turns out. The screenshot below shows image search results for “google oauth login diagram.” Some of these diagrams are clear while others are cluttered and confusing.

\n

\n

Diagrams are a communication tool. Used well, they focus a conversation, communicate objectives, and enforce guidelines. Used poorly, they can derail conversations and result in frustration.

\n

The slides below are from a short workshop I gave on how I use diagramming in my technical proposals.

\n
\n
\n

Reasons to Draw

\n
    \n
  • Explore a problem
    • \n
  • Make a decision
    • \n
  • Share a solution
    • \n
\n\n
\n
\n
\n ❮\n 1 / 18\n ❯\n
\n
\n

I am going to talk about three different reasons to draw diagrams and why each reason requires a different thought process.

\n

Diagrams are a powerful communication tool. If they are done wrong, they will send your audience off in the wrong direction and you’ll misunderstand each other. If they are done right, you’ll have a focused, productive conversation.

\n\n
\n
\n
\n

Diagrams Create a Shared Mental Model of a System

\n\n
\n
\n
\n ❮\n 2 / 18\n ❯\n
\n
\n

Put yourself in your audience’s position when you draw a diagram.

\n
    \n
  • What are their goals when they read your diagram?
    • \n
  • What context do they have that will affect how they read it?
    • \n
  • What do you need from them when they see the diagram? Are you telling them how something works? Proposing a solution? Demonstrating a tradeoff?
    • \n
\n\n
\n
\n
\n

What Makes a Good Diagram?

\n
    \n
  1. Follows a formula
    2. \n
  2. Minimal colour
    3. \n
  3. Clear visual hierarchy
    4. \n
  4. Incorporates time, relationships, & decisions as needed
    5. \n
\n\n
\n
\n
\n ❮\n 3 / 18\n ❯\n
\n
\n
    \n
  1. Following a formula makes it easy for your audience to understand the content. They will spend less time trying to take in the colours, symbols, and lines and instead see the whole picture.
    2. \n
  2. Minimal colour. Too much colour is distracting. Only use colour to focus the eye on important details.
    3. \n
  3. Clear visual hierarchy. The reader should clearly see the important parts of the diagram on the first glance. Cut extra details.
    4. \n
  4. Incorporates time, relationships & decisions. Don’t use a single formula for every diagram. If time is an important factor, pick a structure that adds time on an axis. If relationships are important, use a diagram with symbols to indicate this aspect.
    5. \n
\n\n
\n
\n
\n

A Diagram Should Explain Itself

\n\n
\n
\n
\n ❮\n 4 / 18\n ❯\n
\n
\n

I have drawn many diagrams and when I step back I wonder, “What do these scribbles mean?” If you have to write extensive notes to explain a diagram, take another pass at it. Try using a different diagramming syntax or cut out unnecessary elements.

\n\n
\n
\n
\n

Diagram to Explore a Problem

\n
    \n
  • Rough drawings
    • \n
  • Good for collaborating live and figuring out ideas
    • \n
  • Only make sense in the context of exploration
    • \n
\n\n
\n
\n
\n ❮\n 5 / 18\n ❯\n
\n
\n

Diagrams for exploring problems are the kind that I make when I’m pairing with a group to solve a problem or hashing something out on a notepad for myself. These diagrams only make sense in the moment and only to the people present.

\n\n
\n
\n
\n

Example: OAuth Flow

\n

\n\n
\n
\n
\n ❮\n 6 / 18\n ❯\n
\n
\n

Here’s an example of a very rough diagram of an OAuth flow. This is the kind of diagram I’d draw to understand the key elements involved. But this diagram is useless for communicating the components and sequences involved.

\n\n
\n
\n
\n

Diagrams for Exploring are Not Diagrams for Communication

\n\n
\n
\n
\n ❮\n 7 / 18\n ❯\n
\n
\n

Draw lots of diagrams! Exploring problems with diagrams is great. But they are for a small audience. These diagrams are not good for communicating to a broader audience.

\n\n
\n
\n
\n

Diagram to Make Decisions

\n
    \n
  • Communicate options
    • \n
  • Include time component when relevant
    • \n
  • Distinguish current and future state
    • \n
\n\n
\n
\n
\n ❮\n 8 / 18\n ❯\n
\n
\n

Drawing to make decisions means you have an external audience. This is where it is important to think about your audience’s context and pick the right visual language.

\n\n
\n
\n
\n

OAuth Flow as Flow Chart

\n
flowchart LR\nUser -->|Enter credentials| Browser\nBrowser -->|POST /login| App[App Backend]\nApp -->|Verify password| DB[(Database)]\nApp -->|Set session cookie| Browser\nBrowser --> User
\n\n
\n
\n
\n ❮\n 9 / 18\n ❯\n
\n
\n

The flow chart in this example works for a simple flow but makes the details of OAuth very hard for an audience to understand.

\n\n
\n
\n
\n

Auth Flow as Sequence Diagram

\n
sequenceDiagram\nactor User\nparticipant Browser\nparticipant App as App (Backend)\nparticipant DB as Database\nUser->>Browser: Enter email + password\nBrowser->>App: POST\nApp->>DB: Verify credentials\nDB-->>App: Valid\nApp-->>Browser: Set session cookie\nBrowser-->>User: Logged in
\n\n
\n
\n
\n ❮\n 10 / 18\n ❯\n
\n
\n

Here’s the basic auth flow as a sequence diagram. There is a clear syntax. You don’t even have to read “user” to know that the stick person is a human, and the x axis clearly distinguishes components while the y axis delineates time.

\n\n
\n
\n
\n

OAuth Flow as Sequence Diagram

\n
sequenceDiagram\nactor User\nparticipant Browser\nparticipant App as App (Backend)\nparticipant Google\n\nUser->>Browser: Click "Sign in with Google"\nBrowser->>Google: Redirect to authorize\nGoogle->>User: Show consent screen\nUser->>Google: Authenticate + grant access\nGoogle-->>Browser: Redirect with auth code\nBrowser->>App: Send auth code\nApp->>Google: Exchange code for tokens\nGoogle-->>App: Return tokens\nApp-->>Browser: Set session cookie\nBrowser-->>User: Logged in
\n\n
\n
\n
\n ❮\n 11 / 18\n ❯\n
\n
\n

And here’s the OAuth flow. You can now look at the two side by side and clearly see the difference. If we were building a product and wanted to decide between Google OAuth or basic auth, these two diagrams could help us understand the tradeoffs.

\n\n
\n
\n
\n

An Artifact to Build From

\n
    \n
  • Document a desired state
    • \n
  • Can be used in Jira tickets
    • \n
  • Can change if you discover gotchas along the way
    • \n
\n\n
\n
\n
\n ❮\n 12 / 18\n ❯\n
\n
\n

Diagrams as artifacts are like blueprints for projects. A good diagram can be referenced over the course of a project and shared with the team. Nothing is certain in software, though! It’s good practice to update artifacts to keep a shared mental model of the system.

\n\n
\n
\n
\n

OAuth Artifact

\n
sequenceDiagram\n    participant User\n    participant Browser\n    participant App as App (Backend)\n    participant Google\n\n    User->>Browser: Click "Sign in with Google"\n    Browser->>App: GET /auth/google\n    App-->>Browser: 302 Redirect to Google authorize URL<br/>(client_id, redirect_uri, scope, state, response_type=code)\n    Browser->>Google: GET /o/oauth2/v2/auth\n    Google-->>Browser: Show account picker + consent screen\n    User->>Google: Authenticate + grant consent\n    Google-->>Browser: 302 Redirect to redirect_uri<br/>(authorization code, state)\n    Browser->>App: GET /auth/google/callback?code=...&state=...\n    Note over App: Validate state (CSRF check)\n    App->>Google: POST /token<br/>(code, client_id, client_secret, redirect_uri, grant_type=authorization_code)\n    Google-->>App: access_token, id_token (JWT), refresh_token\n    Note over App: Verify id_token signature + claims<br/>(read sub, email, name)\n    Note over App: Find or create user, establish session\n    App-->>Browser: Set session cookie, redirect to app\n    Browser-->>User: Logged in
\n\n
\n
\n
\n ❮\n 13 / 18\n ❯\n
\n
\n

As an artifact, the OAuth flow has more detail and notes on each interaction. You could reference this diagram if you needed to sort out the requirements to implement a part of this flow.

\n\n
\n
\n
\n

Four Types of Diagrams

\n\n
\n
\n
\n ❮\n 14 / 18\n ❯\n
\n
\n

I used sequence diagrams today as an example. There are many other diagramming syntaxes. Here are four more that I find useful.

\n\n
\n
\n
\n

Flow

\n

Use when a sequence of events can have alternative branches.

\n
flowchart LR\nStart([Start]) --> Decision{Condition met?}\nDecision -->|Yes| Path1[Do this]\nDecision -->|No| Path2[Do that]\nPath1 --> Stop([Stop])\nPath2 --> Stop
\n\n
\n
\n
\n ❮\n 15 / 18\n ❯\n
\n
\n

Don’t go overboard on syntax. Stick to simple diagram syntax that your audience will understand.

\n\n
\n
\n
\n

Entity Relationship Diagram

\n

Use when entities (often database tables) have relationships to one another.

\n
erDiagram\nUSER {\nint id\nstring email\nstring password_hash\n}\nSESSION {\nint id\nint user_id\nstring session_token\ndatetime expires_at\n}\nOAUTH_ACCOUNT {\nint id\nint user_id\nstring provider\nstring provider_user_id\n}\nUSER ||--o{ SESSION : has\nUSER ||--o{ OAUTH_ACCOUNT : has
\n\n
\n
\n
\n ❮\n 16 / 18\n ❯\n
\n
\n
\n

Network Architecture

\n

Use when describing how software systems interact over a network.

\n
architecture-beta\n\tgroup api(cloud)[API]\n\n\tservice db(database)[Database] in api\n\tservice disk1(disk)[Storage] in api\n\tservice disk2(disk)[Storage] in api\n\tservice server(server)[Server] in api\n\tdb:L -- R:server\n\tdisk1:T -- B:server\n\tdisk2:T -- B:db
\n\n
\n
\n
\n ❮\n 17 / 18\n ❯\n
\n
\n
\n

Resources

\n\n\n
\n
\n
\n ❮\n 18 / 18\n ❯\n
\n
\n
\n
\n\n", "date_published": "2026-08-07T00:00:00+00:00", "url": "https://enumerator.dev/technical-diagrams-for-communication/", "tags": ["tools"] }, { "id": "https://enumerator.dev/smitten-with-whats-written/", "title": "Smitten with What's Written", "content_html": "

As much as I use AI at work every day I find its writing harder and harder to understand. The code? It usually makes enough sense to me and I can follow its logic. But my brain goes foggy when I read the LLM’s reply to me.

\n

The same thing happens to me when I read a blog post or article with the hallmarks of AI. It always starts with me wondering if I’m misunderstanding something in the article and then it clicks, “Oh, this is AI content.”

\n

AI writing is a disaster. It falls apart so quickly. While LLMs can produce grammatically correct text, their writing does not stay on topic and they frequently invent phrases that sound correct but have have no real meaning.

\n

In spite of this, there is so much AI writing out there now. It is exhausting.

\n

On The Curiosity Shop Brené Brown proposes that the grammatical correctness of AI writing is so appealing that people overlook the weak content it produces (emphasis my own):

\n
\n

I think with the advent of AI, people who struggle with written communication, persuasive written communication, the problem is they’re smitten with what’s written.

\n

They are so smitten with the idea that they can hand off a work deliverable or anything that’s well written…because that’s new for them. Like, all of a sudden, this is this beautifully crafted thing that I can turn into someone when for 40 or 50 years, I have not been able to make something basically perfect.

\n
\n

In a work context, Brown’s idea resonates with me. Writing is difficult. English grammar is hard enough! Never mind connecting ideas and creating a coherent argument in text. People publish AI content because it has the veneer of good grammar. Who needs Strunk & White when you have an LLM!

\n

I have long detested prescriptive rules for writing. I endured lectures on commas in English 101 and still don’t know how to use a comma. I see rules and freeze. How can I write if there are all these rules to follow?!

\n

Ironically, Strunk & White is too relevant today:

\n
\n

Omit needless words.

\n

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that he make every word tell.

\n
\n

The Elements of Style

\n

I Want to Read Human Words

\n

It is almost cliché to say this today, but, I want to read human-written words. I really don’t care how polished human writing is. Especially in a work context. I want human thought process, rigour, taste, and decisions. I don’t want writing that’s been passed through an LLM and I absolutely don’t want an LLM to generate writing.

\n", "date_published": "2026-08-03T00:00:00+00:00", "url": "https://enumerator.dev/smitten-with-whats-written/", "tags": ["ai"] }, { "id": "https://enumerator.dev/plants/", "title": "Plants", "content_html": "

I have been looking for ways to improve my home office’s air quality by increasing ventilation. Naturally, I wondered if I could add a few plants.

\n
\n

Humans make carbon dioxide. Carbon dioxide is bad for cognition. But plants turn carbon dioxide back into oxygen. And plants are the one true home decoration strategy. So maybe if you get a lot of plants, you can you can keep carbon dioxide in check and keep your brain working?

\n
\n

So you want to use plants to reduce indoor CO₂

\n

I’m so glad someone did the math for me!

\n
\n

Realistically, we’re talking about something like 5,000-10,000 watts [of light], most of which is lost to the room as heat. Imagine five space heaters blasting you on high all the time.

\n
\n
\n

(1 kg carbon dioxide)
\n× (0.273 kg elemental carbon / kg carbon dioxide)
\n× (2 kg dry plant / kg elemental carbon)
\n× (8.5 kg actual plant / kg dry plant)
\n= 4.6 kg actual plant.

\n

Your garden must grow that much, every day. That’s 140 kg per month. You must prune and discard all that outside, or your garden is not actually sequestering anything

\n
\n", "date_published": "2026-07-31T00:00:00+00:00", "url": "https://enumerator.dev/plants/", "tags": "misc" }, { "id": "https://enumerator.dev/safe-claude-code-settings/", "title": "Safe Claude Code Settings", "content_html": "

Here are a few commands I have in my Claude Code deny-list to prevent bad things from happening. I wish Claude shipped with these by default!

\n

The following commands disallow Claude from force pushing and skipping pre-commit hooks.

\n
{\n  "permissions": {\n    "deny": [\n      "Bash(git push -f)",\n      "Bash(git push --force)",\n      "Bash(git commit:*-n:*)",\n      "Bash(git commit:*--no-verify:*)"\n    ]\n  }\n}\n

To be extra careful, I also have a pretty thorough gitignore that I install globally which includes common patterns for secret credentials.

\n
*.key\n*.pem\n*.p12\n*.pfx\n*.cer\n*.crt\n**/secrets/**\n**/credentials/**\n.env\n.env.*\n**/config/secrets.toml\n
", "date_published": "2025-11-26T03:08:00+00:00", "url": "https://enumerator.dev/safe-claude-code-settings/", "tags": ["claude","ai"] }, { "id": "https://enumerator.dev/planning-building-reviewing-why-the-jj-workflow-works-better-than-git/", "title": "Planning, Building, Reviewing: Why The JJ Workflow Works Better Than Git", "content_html": "

\n

After a week of experimenting with using git and jj to plan and build, I’ve landed on jj as the winner.

\n

Rebasing Kills the Git Workflow

\n

Automatic rebases are the winning feature here. When I tell Claude to update a change, it will automatically rebase all its descendants. This is a MASSIVE time saver for both me and Claude.

\n

When I use empty commits in git, Claude performs the same until it has to start editing code. Then things get messy.

\n

Rebasing in git is almost always painful. Claude can clunk through the rebase workflow faster than I can, but it still gets lost at times.

\n

My Current Workflow

\n

Here is the CLAUDE.md that’s been working well for me lately. It teaches Claude how to use the jj workflow.

\n

1. Start plan mode

\n

I start a new session in plan mode and give Claude Code all the information I can think of. I describe what I need, reference files, and explain the outcome.

\n

2. Iterate on the Plan

\n

I almost always refine the plan with Claude. I verify the code samples it provides and verify that the implementation meets my expectations.

\n

3. Turn the plan into commits

\n

I’m still in plan mode, and I ask Claude to break the plan down into empty jj changes.

\n

4. Review the jj Plan

\n

This is key. I am still in plan mode here, and I need to ensure the steps Claude has planned make sense and have no gotchas. Iterate on this step.

\n

5. Auto-accept edits

\n

Finally, I let Claude rip. Once the plan looks good, I auto-accept edits and allow Claude to use jj commands as needed.

\n

6. Do Something Else

\n

While I refined this workflow, I watched Claude work to keep it on track and assess whether we had come up with a good enough plan. But I’ve found that with a focused plan, Claude can work away just fine.

\n

7. Code review with Claude

\n

I use a code-review command to kick off code review with Claude. We walk through one change at a time. I sometimes make manual edits, other times I get Claude to refactor things.

\n

8. Use gh to create PRs

\n

Depending on the scope of the change, I’ll make a PR stack and ask Claude to manage the stack for me, or I’ll create a single PR with a linear history.

\n

9. Code Review Again

\n

Yes, I do code review again. The code is mine, after all. I go through the GitHub UI and review the code myself. If I want Claude to make a change, I ask it to edit the jj change set where the code was introduced.

\n

The result is a clean commit history that implements a feature one change set at a time.

\n

Why JJ Works So Well

\n

In steps 7 and 9 above, I review code and often want to make changes to specific change sets. In git, this would involve git rebase -i, picking the commits to edit, making the edits, then git rebase --continue. In jj, all that is done for you.

\n

Two Takeaways

\n

Agent or not. These two things are true in software development. Planning and reviewing are the most critical steps.

\n

Plan, Plan, Plan Again

\n

Working with an AI agent emphasizes the importance of planning. Planning your work has always been essential for successful feature development. Now with agents, we have really fast researchers who can help us refine a plan.

\n

The more time you put into planning, the more successful your work will be, regardless of whether you’re using an agent.

\n

Review, Review, Review Again

\n

Like planning, reviewing your work ensures it is accurate, bug-free, and performant. This is YOUR work after all. Even if an agent wrote it, you own the code.

\n", "date_published": "2025-11-08T14:04:00+00:00", "url": "https://enumerator.dev/planning-building-reviewing-why-the-jj-workflow-works-better-than-git/", "tags": ["jj","claude"] }, { "id": "https://enumerator.dev/use-git-to-plan-and-build-with-claude/", "title": "Use Git to Plan and Build With Claude", "content_html": "

\n

When I shared my new JJ and Claude workflow last week, I wondered whether JJ was too much friction for developers. It requires learning a new version-control tool in addition to learning to use Claude. I had an idea in the back of my mind to use plain git for this.

\n

And then Claude did it for me!

\n

Towards the end of the week, I was working in a codebase where I hadn’t initialized JJ yet. Claude tried to use the JJ workflow, saw that JJ wasn’t initialized, and started implementing the same workflow using plain old git. We were working on a relatively simple feature, and Claude created planning commits and implemented it.

\n

You Don’t Need to Learn a New Tool

\n

JJ is a good workflow if you need a graph of related features. I find this happens most often when I’m building a new feature or working in an old codebase where I find bugs.

\n

Most day-to-day work can be done in linear branches. Plus, everyone knows git already.

\n

This morning, I worked with Claude to refine a CLAUDE.md that uses plain old git to plan and build features. This looks really promising so far.

\n", "date_published": "2025-11-01T12:57:00+00:00", "url": "https://enumerator.dev/use-git-to-plan-and-build-with-claude/", "tags": ["claude"] }, { "id": "https://enumerator.dev/why-is-claude-code-different-from-cursor-if-they-both-use-claude/", "title": "Why is Claude Code Different from Cursor if they Both Use Claude?", "content_html": "

I get this question often. Here’s how the story goes:

\n\n

Few developers have had time to learn these tools. They’ve been forced to use them as productivity enhancers, without the time to learn.

\n

I have seen performance gains in my work. I shipped the first version of Uplift in a few hours! But I’ve also taken an enormous amount of time learning, training others, and trying terrible AI tools.

\n

I work with many developers who use Cursor daily. This is good! Cursor seems to work better with their workflow. While I have a distaste for Cursor, others find it useful. Agents, like IDEs, are a preference, after all.

\n

Going faster means slowing down to learn your tools. Changing IDEs or using a CLI is a BIG workflow change for most people, and if Cursor is your first brush with AI, I do not blame you for thinking it’s a waste of time.

\n

In this post, I want to demystify “It’s all Claude in the end” to help people understand why some agents are good and others are frustrating.

\n

Defining Terms

\n

Let’s start with defining three standard terms. I’m going to use the common nomenclature in this post, but it’s important to note that their meanings are often blended in different contexts.

\n
    \n
  1. AI: These two small letters carry the weight of “agents”, “LLMs”, “automation”, “autocomplete”, and everything else. When someone says “AI,” they mean any one of these. In this post, “AI” refers to coding agents that have some autonomy in their work.
    2. \n
  2. Agent: This term comes up in phrases like “agentic workflow” or “coding agent”. The agent is the engine of AI coding. The agent connects the user’s input to the local environment’s context (files, available tools) and provides it to the LLM. In this post, “agent” is a loop that takes user input, provides context to the LLM, and calls tools.
    3. \n
  3. LLM: We all know LLMs like Claude, ChatGPT, or Codex. “LLM” stands for “large language model”. “LLM” is a misnomer. Many of these models accept multiple types of input and produce various outputs. A more accurate name is “Large Multimodal Model”. The models we use for coding are autoregressive, meaning they predict the following sequence based on previous context. For consistency with vernacular usage, I’ll refer to them as LLMs.
    4. \n
\n

AI: Distinguishing the Agent from the LLM

\n

In the diagram below, the “environment” is your computer and the tools you let your agent use. If you’ve given your agent access to find, for example, it will show up in the list. Depending on the agent, it might also collect some project stats to send to the LLM.

\n

When you have a CLAUDE.md or AGENTS.md file, this will get sent with the context, too.

\n
sequenceDiagram\n    participant U as User\n    participant AS as Agent\n    participant E as Environment\n    participant LLM as LLM (API)\n    \n    U->>AS: "Fix bug in auth.js"\n    \n    box rgba(0,0,0,0.05) Your Computer\n      participant AS as Agent\n      participant E as Environment\n    end\n    \n    Note over AS,E: Agent Orchestration Layer<br/>Manages loop, provides tools, maintains context\n    loop Until task complete\n        AS->>LLM: Context + Available Tools + User Request\n        Note over LLM: Parse intent<br/>Reason about next step<br/>Choose tool to call\n        LLM->>AS: Tool call decision\n        AS->>E: Execute tool (view/edit/bash)\n        E->>AS: Return result\n        AS->>AS: Append result to context\n    end\n    \n    AS->>U: "Fixed: added null check<br/>Tests passing ✓"\n    \n    Note over U,E: Different agents = different tools, autonomy levels,<br/>and orchestration strategies (even with same LLM)
\n

Notice that most of the work actually happens on your own machine. The agent interacts with your environment to collect information to send to the LLM, makes edits, and reports back.

\n

An agent is not intelligent. This is really important to understand. An agent without an LLM is a loop with conditionals. Much like the code we write every day.

\n

Adding an LLM into the loop gives the agent the ability to reason and make decisions beyond pattern matching.

\n

Every agentic coding company will write its agent differently. The tools available, the actions the agent takes, and the system prompts it sends to the LLM are the product the company builds.

\n

Cursor is different from Claude Code because Cursor’s agent is different, even if they both use a Claude model to reason and make decisions.

\n

The LLM Reads the Entire Conversation Every Time

\n

The LLM is an outside actor. If you are using Cursor or Claude code, every message you send and every agent loop involves API calls to the LLM provider you are using. If you are running a model locally, the model is separate from your agent system.

\n

Every time the agent calls the LLM API, it is the first time the LLM has ever seen your message. The LLM reads THE WHOLE MESSAGE THREAD EVERY TIME.

\n

That’s right. Do you have a long-running conversation where you’ve worked on three or four different tasks? When you ask the agent a question, the LLM reads the whole message thread and can easily confuse instructions you previously gave it with your current task.

\n

In my experience, this is the most common reason agentic coding starts as highly accurate and quickly degrades into chaos.

\n

How do you fix this? Start a new chat. It’s that simple. Start a new chat for every task you work on.

\n

Warp has a great feature in its agent that detects a change in subject and suggests starting a new chat. I wish other agents would do that too.

\n

This is an important distinction to make. The agent’s capabilities and system prompt affect how it works. Cursor tends to be very ambitious, which means the context window can quickly become bloated with failed attempts and misdirection.

\n

More cautious agents will confirm actions with the user and detect when the conversation is drifting, keeping the context focused on the task at hand.

\n

No agent is perfect, which is why I’ve explored using the Jujutsu VCS to give the agent memory between sessions and narrow the context the LLM receives on each turn.

\n
sequenceDiagram\n    participant CC as Agent\n    participant LLM as LLM (API)\n    \n    box rgba(0,0,0,0.05) Your Computer\n\n    end\n    \n    Note over CC: Context:<br/>[System prompt]\n    \n    CC->>LLM: [System prompt, User: "Fix bug"]\n    LLM->>CC: "I'll check the file"\n    Note over CC: Context:<br/>[System, User,<br/>Assistant]\n    \n    CC->>LLM: [System, User, Assistant, Tool: file contents]\n    LLM->>CC: "I'll edit line 42"\n    Note over CC: Context:<br/>[System, User,<br/>Asst, Tool,<br/>Asst]\n    \n    CC->>LLM: [System, User, Asst, Tool, Asst, Tool: edit result]\n    LLM->>CC: "Fixed! Tests passing"\n    Note over CC: Context:<br/>[System, User,<br/>Asst, Tool,<br/>Asst, Tool,<br/>Asst]\n    \n    Note over CC,LLM: Each API call sends the ENTIRE context<br/>Context grows with every message<br/>and tool result.
\n

Key Principles

\n

The diagram below illustrates the capabilities of a coding agent. The Agent Loop is the central capability. This is the part that each company builds (Claude Code, Cursor, Zed, Warp, etc.)

\n

The LLM is separate from the agent loop. Many different agents can use the same LLM, and most agents let you pick which LLM to interact with.

\n
flowchart LR    \n    AgentLoop[Agent Loop] --> LLM[Calls LLM]\n    \n    AgentLoop --> AL1[Stateful Orchestration]\n    AgentLoop --> AL2[Maintains state and history]\n    AgentLoop --> AL3[Executes tools]\n    AgentLoop --> AL4[Manages context window]\n    \n    LLM --> L1[Stateless Reasoning]\n    LLM --> L2[Processes full context each turn]\n    LLM --> L3[Selects tools & plans actions]\n    LLM --> L4[No memory between calls]
\n

Conclusion

\n

Try lots of agents! I know this can feel slow and frustrating, but when you do this, you are learning how different agents work. You are learning the new tools you can use in your job.

\n

Take 15 minutes each day to build a small project with an agent. Pick something simple, like a to-do list app. Build the same app with different agents and see how they perform.

\n

In the future, I think we will standardize on a handful of coding agents that developers can pick to work with their preferred workflow, much as we have standardized on a handful of IDEs for different use cases.

\n

I prefer Claude Code for its built-in protections and customization options.

\n

If you want an agent integrated in your IDE, you can run /ide to hook Claude Code up to VSCode. It’s not as deeply integrated as Cursor is, but it works okay. Another good option is to try out Zed, their agent has similar capabilities to Claude Code and is built into the IDE.

\n

I’ve tried Warp a few times, and the deep integration of chat, CLI, and editing is promising to me, but sometimes confusing.

\n

In the end, Vim is my home row, so the setup that works for me is Claude Code in one pane and Vim in the other.

\n", "date_published": "2025-10-27T13:30:00+00:00", "url": "https://enumerator.dev/why-is-claude-code-different-from-cursor-if-they-both-use-claude/", "tags": ["ai","claude"] }, { "id": "https://enumerator.dev/use-jujutsu-to-plan-and-build-with-claude/", "title": "Use Jujutsu to Plan and Build with Claude", "content_html": "

\n

This week, I read about Steve Yegge’s Beads.

\n

I was skeptical.

\n

He writes like someone trying to prompt inject your LLM. But he’s always written that way.

\n

I tried beads, and it was pretty good. I wrote all of uplift using beads.

\n

But it was also pretty buggy. I noticed I had multiple bd daemons running and checking git status. Not cool.

\n

Jujutsu

\n

I shared beads with Nate Smith, and he said, “You could do that with Jujutsu.”

\n

We both tried it and it rocks.

\n

Here is my current CLAUDE.md , which teaches Claude to use Jujutsu to plan and track issue progress.

\n

Jujutsu is a Git-compatible version control system. The graph foundation of Jujutsu makes it perfect for this kind of work because Claude can add empty TODO commits along the way and connect them to one or more tasks that also need to be done.

\n

Here is the gist of the instructions Claude gets:

\n
\n

Planning Best Practices

\n

Create Descriptive Empty Commits:

\n\n
\n

The steps for you are:

\n
    \n
  1. Enter plan mode and build a plan with Claude.
    2. \n
  2. When you’re ready, tell Claude to make empty commits for each step in the plan.
    3. \n
  3. Tell Claude to work through one commit at a time until it is done.
    4. \n
  4. If at any point Claude struggles or decides to compact memory. Kill your session and start a new one with “We are in the middle of working through a to-do list created in jj. Find the task you were in the middle of and finish it, then move on to the next task until you are done.
    5. \n
\n

On Friday, I refactored a small Ruby library with Claude and Jujutsu, and it was really nice. I knew what I wanted the end state to look like and described that to Claude. Claude then made a plan with detailed acceptance criteria for 12 distinct steps. Once I approved, Claude turned the plan into jj commits and worked through them.

\n

Around step 7, Claude slowed down and suggested that steps 7 through 12 were tightly coupled. I ran /clear to start a new session and pick up where we left off. Claude still saw that steps 7 through 12 were coupled, but no longer tried to implement them all at once. It methodically worked through the steps.

\n

At the end, Claude suggested a five-PR stack so developers could review PRs implementing the requirement in separate logical steps.

\n

Why This Works (My Theory)

\n

Steve Yegge is right about why this works, but more than a little off base about needing a whole buggy go program to do it.

\n

Claude works better with this workflow because the context you send is focused and clear. A big old markdown doc is fine, but Claude has to read the whole thing multiple times to find the next task.

\n

With the Jujutsu workflow, Claude can read a summary of what is done with jj log and pick up the following task with jj edit

\n

The LLM on the other side of the Claude agent receives a more focused context. As the conversation continues, the thread narrows to specific tasks.

\n

In past work, when I’ve used a plan.md or Claude’s default todo list, Claude struggles because it reads the entire plan every time, multiple times, since the whole chat is sent to the LLM with each message. This means the context gets bloated with planning and loses focus on accomplishing tasks.

\n

With the Jujutsu workflow, planning shows up exactly once in the context. Then jj log shows incremental progress.

\n

I Want This

\n

It’s good! You should try it. Get Jujutsu set up and copy my CLAUDE.md.

\n

If you don’t know how to use Jujutsu, Claude can learn by using jj help.

\n

The most important thing to remember is: if you think the agent is lost, you’re probably lost too!

\n

You can /clear your session, take a break, and start fresh. Claude will pick up where it left off because it knows to use jj log to find the next task.

\n", "date_published": "2025-10-26T12:58:00+00:00", "url": "https://enumerator.dev/use-jujutsu-to-plan-and-build-with-claude/", "tags": ["ai","jj","claude"] }, { "id": "https://enumerator.dev/navigating-to-get-things-done/", "title": "Navigating to Get Things Done", "content_html": "

\n

In engineering culture, we sometimes refer to managers and Staff Engineers as “shit umbrellas” for their team. I’ve never liked this idea. It paints a picture that individual leaders create a peaceful oasis for their team while chaos reigns outside.

\n

Sounds nice to be one of those engineers! Not a care in the world. Just flow. It must feel special to have a shit umbrella manager.

\n

But the shit umbrella is a lie.

\n

If every manager believes they create a sphere of deep focus and flow, where is all the shit coming from? One team’s flow is another team’s dysfunction.

\n

The “shit umbrella” metaphor entrenches an “us versus them” culture and isolates individual teams from the rest of the company. It pits leaders against lowly engineers and ensures communication starts with arguments rather than curiosity.

\n

Be a Navigator

\n

Effective engineers engage across an organization and know how to navigate its complexities. Effective engineers recognize that people are complex, have diverse emotions, make mistakes, and struggle to communicate effectively. And that’s okay because we are all human.

\n

Teams need to understand how an organization operates to be effective engineers, and people leaders are responsible for helping teams focus, navigate complexities, and achieve their goals.

\n

Being a navigator for a team means helping them find their way and letting them do the work to reach their destination by helping the team understand who is who in the organization and what these individuals care about. Working with the complexities in an org is about curiosity and learning.

\n

Helping your team navigate an organization begins with trust and focus: trust that your team can handle what comes their way and that the people they work with understand their part of the organization better than you do.

\n

In Matheus Lima’s recent post on politics, he says:

\n
\n

The engineers who refuse to engage with politics often complain that their companies make bad technical decisions. But they’re not willing to do what it takes to influence those decisions. They want a world where technical merit alone determines outcomes. That world doesn’t exist and never has.

\n
\n

The same goes for managers who choose to be shit umbrellas. Protecting your team from politics isolates them from the business and creates an insular culture where “everything could be better if…” while not improving anything.

\n

Protecting Your Team Protects Dysfunction

\n

When people leaders try to protect their team from organizational chaos, they are unintentionally ensuring the dysfunction stays in place.

\n

The purported “shit” that a shit umbrella protects people from is just people being human. To quote Will Larson:

\n
\n

[T]he reality is that executives are human. You’ll make much more progress by focusing on improving how you communicate with them than by blaming them for their deficiencies.

\n
\n

Larson’s comments apply to anyone you work with in your org. Improving your communication skills ensures that you approach conversations with a clear understanding of the core business needs.

\n

Blaming others for their deficiencies ensures organizational dysfunction is the norm and prevents the business from growing.

\n

People at all levels of an organization need to make mistakes and learn from them. The shit-umbrella culture breaks this feedback cycle. It allows new leaders to fail without receiving feedback and support from their peers, isolates senior leaders from the teams they need to work with, and isolates your team from the business.

\n

Focus

\n

People who talk about being a shit umbrella want to maintain their team’s focus and limit distractions. It comes from a well-meaning place, but creates a culture of isolation instead of focus.

\n

As a navigator, show your team what to focus on and how to reach their destination. Trust them to raise concerns when things get hard, and trust your peers on other teams to support their work.

\n

Provide your team with a map and help them to focus on the business impact of their work, so that they can approach complex parts of the org with curiosity and an ambition to build great things for the business.

\n", "date_published": "2025-10-07T11:55:00+00:00", "url": "https://enumerator.dev/navigating-to-get-things-done/", "tags": ["organizational-culture"] }, { "id": "https://enumerator.dev/willow-camp-updates-october-7-2025/", "title": "willow.camp Updates - October 7, 2025", "content_html": "

I’ve spent most of my willow.camp work on finding a new backend language. But I’ve still updated the Rails app! Here’s what’s changed since my last update.

\n\n", "date_published": "2025-10-07T11:25:05+00:00", "url": "https://enumerator.dev/willow-camp-updates-october-7-2025/", "tags": ["willow-camp","release-notes"] }, { "id": "https://enumerator.dev/willow-camp-next/", "title": "willow.camp: Next", "content_html": "

I have spent the past few weeks figuring out the future of willow.camp.

\n

It turns out I love making it, and I love that a handful of people are using it.

\n

I built willow.camp in Rails because I could prototype quickly without having to think about things like auth, logging, or building forms. Rails was great for that.

\n

Now that I have a version of willow.camp I like, I want to be more hands-on with what I’m building, and I find that I’ve spent more time working around the framework and various libraries than I have creating the things I want.

\n

Learning other people’s code isn’t particularly enjoyable.

\n

Aside: Rails and Ruby have also had a public meltdown lately, and I’m tired of feeling like a puny developer watching giants fight and say evil things.

\n

Finding the Next Tech Stack

\n

This was a long journey.

\n

I started with Hanami. It is still Ruby, and the community is much friendlier. Hanami didn’t work for me. It felt like I kept bumping up against the framework, telling me I was doing it wrong. The community is friendly, but the framework is very rigid about “the right way” of doing things.

\n

Then I hopped over to Crystal and tried Lucky, Amber, and Marten. They were all okay to work with, but didn’t strike my fancy.

\n

Lucky was the easiest to get going. I had the data models for willow.camp up and running with a couple of rough-looking views in a few hours.

\n

Marten’s “apps” are nice to work with (think slices in Hanami). But the framework doesn’t natively support subdomain routing, and I didn’t want to fight that design.

\n

Crystal is also very slow to compile. A straightforward Lucky app took over 30 seconds on my M1 to compile! Who has that kind of time when you need to compile multiple times an hour?

\n

Finally, the community. The Lucky devs are really active, which is nice. But Crystal itself seems to have a fragmented community. When I interacted with people, I didn’t really see someone like me in any of the channels.

\n

What I Want in A Language and Framework

\n
    \n
  1. An active, welcoming community that builds trust.
    2. \n
  2. Helpful error messages from the language.
    3. \n
  3. Good documentation.
    4. \n
\n

That’s about it. I don’t need huge framework features. I need a language with a helpful design and friendly people.

\n

The Next willow.camp Tech Stack

\n

Once I realized that I valued community and friendly docs more than I valued framework features, I found Gleam.

\n\n

Oh, and I’ve already written a Gleam package! willow.camp needs an accurate domain name parser, so I wrote psl to parse domains using the Public Suffix List.

\n

The Next willow.camp Features

\n

I have a long list of features I want to build for willow.camp, and it’s these features that inspired me to change the language and framework.

\n
    \n
  1. A WYSYIG editor that supports markdown. This is the best of both worlds and opens willow.camp up to non-technical writers.
    2. \n
  2. An image library via openverse with an image editor UI.
    3. \n
  3. Email newsletters! I’m excited about this one. You will be able to collect a list of subscribers and send blog posts to your distribution list.
    4. \n
  4. ATProto and ActivityPub support.
    5. \n
  5. An RSS reader so you can follow blogs without a social profile.
    6. \n
  6. Private bookmarks with notes and highlights.
    7. \n
\n", "date_published": "2025-10-07T01:26:24+00:00", "url": "https://enumerator.dev/willow-camp-next/", "tags": ["willow-camp"] }, { "id": "https://enumerator.dev/willow-camp-updates-september-21-2025/", "title": "willow.camp Updates September 21, 2025", "content_html": "

Quiet on the updates this week. I could rename “Major Features” to “Major Worries” because I’ve spent more time worrying about how images should work than testing them with real users!

\n

I enabled image uploads on the marksmith text editor this week, and a few people tested it out for me. Turns out marksmith doesn’t work how I thought it would with images. Image uploads are still enabled, but I’m going back to the drawing board with the editor UI and media management.

\n

Major Features

\n\n

Improvements

\n\n

Security & Dependencies

\n\n", "date_published": "2025-09-21T12:58:00+00:00", "url": "https://enumerator.dev/willow-camp-updates-september-21-2025/", "tags": ["willow-camp","release-notes"] }, { "id": "https://enumerator.dev/how-much-does-it-cost-to-run-willow-camp/", "title": "How Much does it Cost to Run willow.camp?", "content_html": "

\n

I recently enabled image uploads in the marksmith text editor on willow.camp. I’ve been hesitant to add media management to willow.camp for two reasons: it is hard to get the user experience right, media management adds extra cost.

\n

I am being cost-conscious on willow.camp because it doesn’t make any money. This is a passion project, and I’m having lots of fun doing it. But the more fun I have, the more it might cost.

\n

It turns out adding storage is way cheaper than I thought. I would have to have a whole lot of media and a few really busy willow.camp sites to start getting charged more for data transfer fees.

\n

I will eventually build a pricing plan for willow.camp to cover costs for active sites. In the meantime, if you want to support willow.camp, you can send me a tip on https://ko-fi.com/cassiascheffer.

\n

Claude Code

\n

I include Claude Code in here because it is part of my development process. I’m on the Max plan, and I use it enough that it pays off.

\n

In the past 30 days, I’ve used CAD $188.49 of tokens, and I even took a week off in the woods.

\n

I use Claude Code to scaffold ideas, experiment with features, and improve test coverage. I’ve been able to build willow.camp so quickly because Claude Code is pretty good at scaffolding a blog in Rails.

\n

August Breakdown

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
servicefee (CAD)
DigitalOcean Droplet (1 vcpu, 1 gb memory)$8.25
DigitalOcean Postgres ( 1gb ram, 10 gb disk)$20.82
Hatchbox.io Deployments$14.13
Claude Code Max$158.2
Honeybadger Error Tracking$0
Total$201.40
Total without Claude Code$43.20
\n

September Estimate

\n

Here is my estimate for September based on today’s exchange rate.

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
servicefee (CAD)
DigitalOcean Droplet (1 vCPU, 1 GB memory)$8.26
DigitalOcean Postgres ( 1 GB RAM, 10 GB disk)$20.87
DigitalOcean Spaces (half a month)$3.44
Hatchbox.io Deployments$14.13
Claude Code Max$192.84
Honeybadger Error Tracking$0
Total$239.54
Total without Claude Code$46.70
\n
\n

Photo by StellrWeb on Unsplash

\n", "date_published": "2025-09-21T12:21:00+00:00", "url": "https://enumerator.dev/how-much-does-it-cost-to-run-willow-camp/", "tags": ["willow-camp"] }, { "id": "https://enumerator.dev/naming-things-for-what-they-do/", "title": "Naming Things for What They Do", "content_html": "

I just saw the Rails World announcement that flavorjones is working on ActiveRecord::Tenanted and all I can say is, “What a reasonable name!”

\n

When I started willow.camp I chose not to use apartment partially because the name and the metaphor were too confusing. I didn’t like tho have to get used to the idea of requests taking “elevators” and all that. The “apartment” metaphor doesn’t work for databases even though “tenant” does.

\n

Always choose descriptive names over clever ones. It doesn’t matter how well you think the metaphor fits; you’ll always end up with something confusing in the end.

\n", "date_published": "2025-09-09T11:23:33+00:00", "url": "https://enumerator.dev/naming-things-for-what-they-do/", "tags": ["ruby","rails"] }, { "id": "https://enumerator.dev/willow-camp-updates-september-7-2025/", "title": "willow.camp Updates September 7 2025", "content_html": "

It’s been a busy month! I took some time off for a much-needed vacation and forgot to post about willow.camp. I’ve worked on some fun features in the past few weeks.

\n

New Features

\n
    \n
  1. Favicons now use OpenMoji emojis! I think these are adorable icons. I have a few qualms with how they fit in the willow.camp design (they’re all a little bottom-heavy), but it’s not a deal breaker.
    2. \n
  2. New favicon picker! You can now search for an emoji by name to pick for your blog.
    3. \n
  3. Now you can have two blogs! You can click on the profile icon and add a second blog. I’m going to use this to document my garden and remind myself what I want to do next year.
    4. \n
\n

I also fiddled around with auto-generating OG images for each blog. I wrote a script that uses your OpenMoji favicon and your blog’s colours to create an Open Graph image for your blog.

\n

Here’s what the tiled image looks like for enumerator.dev.

\n

\"willow.camp

\n

Ultimately, the best approach for images is to enable users to upload them instead of doing some clever auto-generation. I’m going to put this on my project board and figure out how to do it. Since storage costs me, I might need to change the license on willow.camp and start charging for image uploads.

\n

Here is the Claude-generated summary of the last few weeks.

\n

Summary - August 17 - September 7, 2025

\n

Major Features

\n\n

Improvements

\n\n", "date_published": "2025-09-08T00:20:35+00:00", "url": "https://enumerator.dev/willow-camp-updates-september-7-2025/", "tags": ["willow-camp","release-notes"] }, { "id": "https://enumerator.dev/willow-camp-updates-august-16-2025/", "title": "willow.camp Updates August 16, 2025", "content_html": "

It felt like a quiet week on willow.camp but somehow I still got lots done.

\n

Aside from the release notes below, I’m focusing my energy on getting proper favicons for willow.camp blogs.

\n

My first version of this will use OpenMoji emojis for favicons. I like their simple design principles and especially like that they are CC-BY-SA 4.0, similar to willow.camp’s source code.

\n

Here’s how I think I’ll approach this:

\n\n

OpenMoji provides pngs in two sizes, so I’ll need to resize them for the best cross-device compatibility.

\n

Okay, on to this week’s summary!

\n

Improvements

\n\n

Security & Dependencies

\n\n

Bug Fixes

\n\n", "date_published": "2025-08-16T12:32:00+00:00", "url": "https://enumerator.dev/willow-camp-updates-august-16-2025/", "tags": ["willow-camp"] }, { "id": "https://enumerator.dev/end-to-end-tests-with-minitest-and-rails/", "title": "End To End Tests with Minitest and Rails", "content_html": "

willow.camp has a small system test suite that runs on CI. It used to use the out-of-the-box settings that come with Rails: Capybara, Selenium, etc.

\n

I noticed a flaky test on CI, which launched a journey to replace Selenium with Cuprite.

\n

Fixing the Flaky Test

\n

I worked through the flaky test with Claude Code, and as Claude was running the tests, I noticed this pop-up from Chrome.

\n
\n

A data breach on a site or app exposed your password…

\n
\n

I don’t use Chrome very often, so this jumped out at me. Of course, I use the oh-so-secret password “password” in my test suite, and Chrome flagged it as unsafe.

\n

Disabling password leak detection fixed this for me.

\n
browser_options: { "disable-features": "PasswordLeakDetection" }\n

But I still got timeouts on CI that looked like the tests were running before the browser was ready.

\n

Waiting for CI is a bit painful. You can see my hilariously bad Git history with Claude’s gleeful overconfidence:

\n
* 0c514d1 - nosandbox (15 minutes ago) <Cassia Scheffer>\n...\n* 57ac55b - bump timeout to 30 sec for ci (21 minutes ago)\n* 9d6e86e - rewirite cuprite/capybara configs (26 minutes ago)\n* 39f3238 - fix: simplify Cuprite configuration following best practices (10 hours ago)\n* 68bfd53 - fix: simplify Cuprite configuration and fix CI timeout issues (24 hours ago)\n* cebfae7 - fix: resolve Cuprite websocket timeout issues in CI (24 hours ago)\n* dc288b7 - fix: make Cuprite configuration more robust for CI environments (24 hours ago)\n...\n* e5bb4df - fix: increase Cuprite timeout and add CI-specific settings for GitHub Acti>\n...\n* cb36eaa - feat: migrate system tests from Selenium to Cuprite (35 hours ago)\n* 39f0ff1 - disable selenium chrome password detection (35 hours ago)\n

That Looks Bad, Cassia. Why Would You Let Claude Do That!?

\n

Because Claude is faster at making mistakes than I am, and I am tired of waiting for CI. Making mistakes quickly means speedier feedback. So I sent Claude off on a fool’s errand to help me learn from the mistakes I would otherwise have made myself.

\n

In the meantime, I read the Evil Martians article about better system tests.

\n

Using Cuprite in Rails with Minitest

\n

The Evil Martians article on system tests uses RSpec, but willow.camp uses Minitest. Here’s what I had to change to make it work with Minitest.

\n

1. PrecompileAssets becomes a module and gets called when setup runs.

\n
# Precompile assets before running tests to avoid timeouts.\n# Do not precompile if webpack-dev-server is running (NOTE: MUST be launched with RAILS_ENV=test)\n\nmodule PrecompileAssets\n  def self.setup\n    # Check if we're running system tests by looking at the test files being loaded\n    running_system_tests = caller.any? { |line| line.include?("test/system") } ||\n      ARGV.any? { |arg| arg.include?("test/system") } ||\n      ENV["RAILS_TEST_TYPE"] == "system"\n\n    unless running_system_tests\n      puts "\\n🚀️️  No system test selected. Skip assets compilation.\\n"\n      return\n    end\n\n    puts "\\n🐢  Precompiling assets.\\n"\n    original_stdout = $stdout.clone\n\n    start = Time.current\n    begin\n      $stdout.reopen(File.new(File::Constants::NULL, "w"))\n\n      require "rake"\n      Rails.application.load_tasks\n      Rake::Task["assets:precompile"].invoke\n    ensure\n      $stdout.reopen(original_stdout)\n      puts "Finished in #{(Time.current - start).round(2)} seconds"\n    end\n  end\nend\n\n# Run the setup when this file is loaded\nPrecompileAssets.setup if defined?(Rails)\n

2. BetterRailsSystemTests Becomes a Moduel

\n
module BetterRailsSystemTests\n  # Make failure screenshots compatible with multi-session setup.\n  def take_screenshot\n    return super unless Capybara.last_used_session\n\n    Capybara.using_session(Capybara.last_used_session) { super }\n  end\nend\n

3. Modules are included in ApplicationSystemTestCase

\n
require "test_helper"\nrequire "capybara/cuprite"\nrequire_relative "system/system_helper"\n\nclass ApplicationSystemTestCase < ActionDispatch::SystemTestCase\n  include BetterRailsSystemTests\n  include CupriteHelpers\n\n  driven_by Capybara.javascript_driver\n\n  def setup\n    super\n    # Use JS driver always\n\n    # Store original host for cleanup\n    @original_host = Rails.application.default_url_options[:host]\n    # Make urls in mailers contain the correct server host.\n    # This is required for testing links in emails (e.g., via capybara-email).\n    Rails.application.default_url_options[:host] = Capybara.server_host\n  end\n\n  def teardown\n    # Restore original host\n    Rails.application.default_url_options[:host] = @original_host\n    super\n  end\nend\n

Flakiness Still Included on CI

\n

I still see a bit of system test flakiness on CI, but far less than before. I am running on the default GitHub Actions runner, which is pretty small. So there’s a good chance that the flakiness is due to low resources on the machine. So far, tests have consistently passed when I run these on my M1 MacBook Air.

\n

I’ll dig into these flaky tests another day! But this looks like an improvement overall to me!

\n", "date_published": "2025-08-13T22:27:26+00:00", "url": "https://enumerator.dev/end-to-end-tests-with-minitest-and-rails/", "tags": ["willow-camp","rails","capybra","minitest"] } ] }