Give the Brain a Room to Think In

Markdown gives me one direction, down the page. Heading, heading, paragraph, bullet, bullet, code block, each looking very similar to the last. I can't easily correlate related sections together in markdown, so I am forced to rely on my unreliable working memory to make connections between sections. Here's the same implementation plan, one in rendered markdown, and the other in html. Even though it's the same information, the HTML version is much easier to absorb! It sort of reads as one "thing" rather than a sequence of information.

I used to have Claude write plans in a markdown template, Goal / Context / Steps / Tests, the same shape every time. On the long ones I'd think I understood the plan, then after it was implemented and tested I'd realize I had missed something big. After some experimentation, I found that making the steps draggable and having the ability to give feedback and ask questions directly inline helps with my understanding. I have the page save my comments in a form Claude can read (Chrome saving to the filesystem, to avoid having to constantly redownload the feedback to my Downloads folder), and then I can easily iterate with Claude instead of having to copy and paste parts of the plans back and forth in the terminal for editing and questions. Occasionally I edit the plan, but more often I just insert questions asking Claude, "What the heck is this part doing?"

Normally in my plans, there is a LOT of detail. Not all of it is important for me to read. HTML lets me fold everything away so I only have to drill into the parts I'm not as familiar with. Here's that same rate-limit plan with every step collapsed to its headline.

// src/rate-limit.ts
import { rateLimiter } from "express-rate-bucket";

export const apiLimiter = rateLimiter({
  window: "1m",
  max: 60,
  keyBy: (req) => req.session?.userId ?? req.ip,
});

// src/api.ts
import { apiLimiter } from "./rate-limit";

app.use(requireAuth);
app.use(apiLimiter); // must sit after auth to read req.session

// src/middleware.ts
  export function requireAuth(req, next) {
-   if (!req.session?.userId) return redirect("/login")
+   if (!req.session) return redirect("/login")
    return next(req)
  }

// src/routes.ts
router.post("/login", { limit: { max: 10 } },  loginHandler);
router.get( "/feed",  { limit: { max: 120 } }, feedHandler);

Knowing what each step does is one thing. Understanding the impact, what else shifts when it lands, is another. That's the half I need a picture for. Mapping files to steps, and steps back to files, is what makes a change legible to me; once I can see which modules move, I get a much better sense of the side effects before I read a single diff. Loosen the guard in middleware.ts and I know auth.ts and login.tsx are downstream.

I split those into four demos to talk about each point individually. The artifact below puts all four back together, with some extra features. The plan is for a made up photo sharing app. Today, when someone uploads a photo, the server resizes and compresses it while they wait, up to thirty seconds on a big file, then hands back the finished image. The plan moves that processing into a background queue so uploads answer instantly, and the web gallery and mobile app poll until the photo is ready. The mobile app that calls the backend service is represented with a dashed circle since its code is not modified as part of this plan.

Press play, or scrub. Each step lights up the files it touches on the graph and narrates what the system looks like once the step lands. A few minutes of poking around and you know which files are load-bearing and why the mobile app constrains the whole rollout. Geoffrey Litt calls this kind of interface an AI HUD, an instrument that extends your perception instead of riding shotgun and talking at you. The page compiles your questions entered in after pressing the flag buttons into review notes at the bottom, ready to paste back to Claude to make the plan doc better and more clear. Plan review has never been this fun 😏.

Write an implementation plan for the change I describe below, as a single self-contained HTML file.

Lay it out spatially: a Goal at the top, then a Context section with everything I need to understand the change (the current behavior, why we're touching it, the key files and how they relate, and any constraints or gotchas), and the tests at the bottom, so the whole thing reads as one object instead of a scroll.

Give me numbered Steps, each with a one-line plain-language summary and a fold I can expand for the diff and the reasoning. Make every step flaggable so I can type a question back to you inline, and mark the risky steps.

Above the steps, draw a small dependency graph of the files the change touches, sized and colored by blast radius, wired so clicking a file lights the steps that touch it and expanding a step lights its files. Include consumers of the change even if they aren't in this repo.

Then make the plan walkable: add a timeline that lands the steps one at a time when I press play or scrub it, lighting up each step's files on the graph and narrating what the system looks like after that step, with a warning note on the risky ones.

Compile my flags into a review-notes block I can copy back to you.

Save it to plan.html so I can open it in the browser and iterate with you.