1. Identify jobs to be done

At my last job, I advised the lead on a new project to define several tasks that customers might use our new features to accomplish. Then we could go through workflows from the perspective of an actual user and make sure everything could be done smoothly. I only have a passing familiarity with the "jobs to be done" technique, having been introduced to it years ago as a software consultant at a company where a lot of emphasis was put on design thinking, but on greenfield products and features, I do find it helpful to know exactly what the user wants to accomplish. When starting my own product, I choose to take my own advice.

I took some long walks to think about the product I wanted and how past me would have used it. For example, I spent a year or so practicing free throws, for no other reason than to unwind at the end of the day, but being a dataphile, I counted shots made and baskets sunk and calculated my accuracy, to track whether I was getting any better. That was something for which I could have used the product I envisioned. I captured voice memos describing exactly what I would want to do for that job: get a reminder each day, create a new entry from it from a template of fields to fill out, then plot a graph of my success rate over time.

I came up with a couple dozen more ways I could have used such a product in the past, had it been available. That many definitions of jobs to be done probably isn't necessary, but the exploration had two significant side-benefits for me. First, they enabled me to see how many times I had already built this app in half-baked ways (a couple times as a DSL for producing EDN, as well as several jury-rigged ways in Obsidian), which proved I had an idea I would use, whether or not anyone else did. The second benefit is that it forced me to—

2. Define a vocabulary

As I compiled notes on the many and diverse tasks I could have used the product for, it was easy to mix up terminology. What was a "visualization", and how did it differ from a "plot"? To keep the documented use cases straight, I wrote out a glossary file that defined each term and what it meant. Then I used those terms consistently.

I've worked on teams that document glossaries before, but it's usually an afterthought, needed when the team becomes large enough that new developers need a reference for the jargon they hear. By then, though, it's usually too late. Different developers refer to different things by the same word, or the same thing by different words. I've never seen a glossary wiki page that went into so much detail it spelled out who called what by what term. Every new dev just had to learn that for themselves.

Defining a specific vocabulary up front, before writing any code, made it clearer to myself what I was describing, and I like to think that it also helped keep the LLM implementors on the right track. In fact, the only file I put in my repo at the start was my glossary file. I wrote the initial prompt using the same terms, and told the LLM to refer to the file for additional details.

3. Tease apart functionality

Defining a vocabulary identified different capabilities the app needed. Rather than overloading the term "notification" to mean, in one context, "remind the user" and in another context "warn the user", I chose the more specific terms "reminder" and "alert". That clarified the documentation, but more importantly it told me I had two separate features masquerading as one.

A clear mental model of the app's behavior makes a difference for user comprehension. Maybe it helps LLMs too.

4. Start with the backbone — and a bigger model

Years of working as a backend software developer helped me understand what parts of the app needed to be designed in from the beginning. For example, I wanted the app to be local-first, which would dictate the data model and database structure. An LLM might be able to overhaul the codebase to fix misaligned architectural decisions, but I already had low expectations about how far an LLM could get before becoming tangled in the complexity of its creation, and I wanted to give it a fighting chance.

I also specified in my initial prompt what order to build the core functionality. Had I built the app by hand, they would have been "milestones" or "phases", structured to let me test the most important capabilities first and validate my idea, then build additional features on top of them. As it was, the LLM built all the phases in one go. I haven't tested this hypothesis, but I like to think that structuring the implementation helped the LLM work from simple to complex with less churn and correction along the way. The result it spit out was pretty close to what I hoped to have, given the prompt I gave.

Before this project, I'd mainly used the medium-sized Sonnet model, but my initial prompt was complex enough that I tried Opus. I didn't want to burn credits going Opus all the way, though, so I backed down to Sonnet for simple tweaks and discovered that Sonnet was more than adequate for intermediate changes too. (Probably my requests are too moderate.) I doubt Sonnet could have created the original scaffolding as well as Opus, so I credit Opus with creating an internal setup that has enabled Sonnet to succeed.

5. Be hands-on

Since I have personal use for the app, I've had plenty of reason to try it, find what I don't like, and ask an LLM to make fixes or add features. Working incrementally like that, most of the changes are small, quickly handled by Sonnet.

I suspect this is the main differentiator between my experience vibe coding and my expectation that LLM agents would quickly stumble into complexity they couldn't manage. My original prompt was only about a thousand words, and subsequent requests, with no context other than the code base, have only been a few sentences. I'll only know certain details when I have software I can play with. I'm not trying to one-shot anything, then finding that a prompt I thought was thorough missed some edge cases and now I have to make the LLM backtrack.

The process has been a dialogue. I would have done the same with a human developer, refused to unload a grand vision then be uninvolved while they crafted perfection. For me to be perfectly satisfied, they would have had to not only read my mind but read thoughts that I didn't yet have. Being a participant in the process may have taken my time and attention, but it also helped the results.

6. Work solo

One luxury I have is that I'm working on this project by myself. There are no other developers writing documentation or prompts that use words differently than than outlined in the glossary, no conflicting paradigms clashing in the code base, no pull requests opened in parallel that make massive changes to the same parts of the code. I doubt vibe coding on a team would have worked this well.

Conclusion

I've only tried this once, so I can't say with certainty that the factors above made the difference between vibe coding the project into a wall and ending up with a product that fits my needs. I do plan to experiment with future projects. It's tempting to test whether a more expensive model is necessary at the outset. Some future projects will require vibe coding collaboratively. Over time, models may become big enough (or cheap enough) that I don't have to be so hands-on.

The product-level preparation, however, will be difficult to abandon. That's legwork that matters to the end user—figuring out the workflows, vocabulary, and the features that can compose together into powerful combinations. I doubt an LLM can do those for me. They may be able to help, especially with finding the right words for terms or detecting when I'm conflating two subtly different features, but as a product owner, I represent the users of the app, and if users can be replaced by an LLM, probably the app isn't needed.

The app is available here as a static site. It runs fully in the browser, with zero data sent anywhere. Entries are saved to the browser's local IndexedDB, so they persist after closing the tab. There's no documentation yet, so if you find the UI, terminology, or interactions unintuitive, email me. Also let me know if you have comments, find bugs, have suggestions for features, or questions about how you might use it for a particular purpose. I'd love to hear from you!

I source PocketMod pages from the same stack of scrap paper as the half sheets for the pocket notebook, but I don't care if one side is completely printed so long as the other is mostly blank. On occasions when the opposite side does have some blank space, I can flip the fold inside out to get additional writing space.

I tried carrying a bare PocketMod, but despite the thickness of the folded paper, my pocket still gave it wrinkles that made the paper difficult to write on. For a long time I used a thin piece of cardboard cut to the same size as the PocketMod and held on with a tiny binder clip. That worked alright, though I did lose the occasional binder clip. I worried about the cardboard wearing out, especially at the corners, so I wrapped it in contact paper. The cardboard eventually acquired a curl, which led me to look for alternatives that didn't need a binder clip.

When I asked on Mastodon, one person suggested gluing cardstock to the cover pages to provide a bit of rigidity. I haven't tried that, but it's an interesting idea.

Claude suggested a 3D printed solution and gave me an OpenSCAD file for a PocketMod-sized base and lid, with the lid slightly smaller than the base so it holds on when printed in TPU:

The OpenSCAD file is here. The lid's fit isn't tight, but there's enough friction that I haven't had trouble with it falling off. The lid also fits on the back, so you don't have a second thing to hold when using the paper inside. Most of the time in my pocket I keep the lid on. When I have kept the lid on the back, the lip of the base tends to keep the booklet in place.

The corners of both the lid and base are rounded to let it slide in and out of a pocket more easily. The original design included nubs to hold the PocketMod in, but they didn't work well and I cut them out with a knife.

The wallet works well enough, but I've only been using it a few days. We'll see how long it lasts. It's bulkier than cardboard, but less fiddly than needing a binder clip and easier to stuff with new sheets than gluing on cardstock covers.

It's also fun to have a use for TPU filament. Most prints for TPU seem to be toys, though arguably, this isn't all that different.

The problem, of course, is that a single piece of paper shoved repeatedly into a pocket doesn't last long enough to be filled. It gets rumpled until it's no longer nice to write on. To get some protection for such sheets, I wanted something thin and lightweight to fit in a pocket, but flexible so I wouldn't notice it. For half a year now, the job has been done by the cover part of this 3D print. It's intended to be printed with TPU, a rubber filament. After it was printed, I folded it in half and held it between two books while I used a heat gun to lock the crease into the rubber. I tried the PLA clips to hold in pages, and while they do work, they couldn't hold very many pages, and they made the cover pinch closed more than I liked, instead of staying open. I traded the clips for a traveler's journal binding: just an elastic band. It holds pages in by a fold down the middle. Shock cord works nicely, though a plain rubber band is also the right size.

Ever since those high school days, I've collected paper printed on only one side to use as scratch paper. Often I doodle an idea, or fold them into quarters and stick them in the car for when the kids demand something to draw on. Every now and then I'll riffle through the collection to find a few top or bottom halves that are mostly blank on both sides. Then I'll cut them in half, fold them, and slide the stack under the elastic band of the notebook cover. That source of paper solves the pristine problem. I have no trouble scribbling on a sheet I saved from the garbage.

This approach also lets me decide how much paper to fill the notebook with. A few half-sheets is usually all I need until the next time I can refill it. For a long weekend with a chance to write, I add more sheets. I haven't tested the capacity. It fits more than I can typically use.

I've learned to alternate between writing in the front of the notebook and writing in the back, which fills up half sheets sooner, rather than only filling the left half of all the sheets and not being able to throw any pages away until I fill the right halves. Being able to throw sheets away prevents me from carrying around a bunch of information I've already ingested into long-term storage or otherwise addressed.

I like how thin the notebook is. It slides in and out of my pocket easily. The rubber cover is flexible, provides some protection from rain, and has so far held up to life in and out of my pockets. If you have suggestions for improvements, email me!

To quantify that assessment, Wikipedia reports that the US interstate highway system is 48,890 miles of road and that it was originally proposed to connect all US cities with a population of over 50,000, though the Smithsonian National Museum of American History says 100,000. According to this Wikipedia page, there are 330 cities of more than 100,000 people in the 2020 census. Here's a minimum spanning tree of those cities, excluding those in Alaska and Hawaii:

That's a highway system with only 16,035 miles of pavement, one-third that of the current highway system. Some of the reduction is due to fewer roads, some is due to connecting cities by straight lines instead of following the easiest terrain.

Of course, the downside to using a minimum spanning tree is that some cities are relatively close to each other geographically but far from each other by road, requiring longer trips between those cities, at least if traveling by interstate. The worst case is traveling from Mobile, Alabama to Montgomery, Alamaba, a straight-line distance of 153 miles, but which this highway system extends to almost 3,000 miles, 18 times longer, having to route west to Oklahoma City, north to South Bend, Indiana, then south through Nashville, Tennessee:

Instead of a special sequence of characters, type a caret and a word, such as ^here. That's a block reference that marks the preceding paragraph with a label. You can jump to that mark with any internal link, such as [[Your file#^here]], but I use it in the file itself by creating a frontmatter field called marks with the value [[#^here]]. That gets rendered as a link which when clicked jumps to the ^here mark.

I put ^here on a blank line between paragraphs. Jumping to it briefly highlights the preceding paragraph, but I know the mark is a separator and resume editing below that point.

If you make the marks field a list, you can include multiple links in one frontmatter field. You can also create a template that works with both the Templates core plugin or the Templater community plugin:

---
marks:
  - '[[#^here]]'
---
^here

That will add the link to the marks field, creating the field if it doesn't exist, and add ^here wherever your cursor is.

Be warned that not all Markdown renderers recognize Obsidian's ^ syntax. While exporting from Obsidian won't render the in-document marks, other Markdown formatters might, and I've occasionally ended up with stray ^here paragraphs.

Obsidian has a huge number of community plugins. Plugins support custom HTML and logic, so I could have rebuilt the web apps as dedicated plugins, but I didn't want to make a custom plugin for each tool, just one plugin that bridged between Obsidian and my web apps. I've dabbled a little in making Obsidian plugins, but since I could define the solution clearly and was more interested in the end product than in the process of building, I tried my hand at vibe-coding and asked Claude to make a plugin. You can find it here. I reviewed the code enough to be familiar with it, so if you have suggestions for improvements, feel free to open an issue or pull request.

At heart, all the plugin does is transmit data back and forth between the Obsidian note and the web app. It loads the web app in an iframe and passes data to it in a message. Web apps pass messages back with data that the plugin saves to the file. The web app can be the whole tab, in which case the note's YAML frontmatter is passed to the app as JSON, or the web app can be sourced from a code block, and only the code block's YAML content is given. More details on the message-passing protocol are in the README.

The plugin supports multiple web apps. Configure names and URLs in the plugin's settings, then specify which web app to load by adding a webapp key whose value is the name you gave the web app. There is a toolbar with a "Save" button to ask the web app for the current state. When the web app is sourced from a file, you can switch to a Markdown view. When sourced from a code block, you can specify the height of the iframe.

It can also be used in the mobile version of Obsidian.

I've been using the plugin here and there for about a month, so it's far from battle-tested, but in my experience the weak point is my web apps, not the plugin. I'm not 100% convinced this is a good idea. The plugin allows web apps to read data from and write data to the Obsidian notes you use it in, so only use web apps you trust. You should also have Obsidian Sync, Git, or some other version control system that backs up files you use with the plugin, since a web app that returns empty values will remove data from the file. If you have security concerns, definitely email me.

Do you have other techniques for managing specialized documents across devices? I'm all ears.

I don't want to read a novel where most of the words are written by an LLM, even if a human designed the novel at a high level. It feels gross. I think this is the reason. The statistical profile of LLM writing is close to the normal. That's literally how LLMs work. They sample from a distribution that captures a median way of writing. I simply don't want my mind pushed towards the statistically normal when I am reading fiction. That's the exact opposite of what I want from the experience.

I may finally read The End of Average, now that LLMs have given us The Revenge of Average. Average output is acceptable for computer code, for which the purpose is to get a computer to operate in a specific way, but the human central processor works differently. We tend to ignore sameness and remember novelty. That's the root of a lot of our cognitive biases.

I've used LLMs as research assistants for fiction, and sometimes they can break me out of my self-imposed mental boxes, but any time I've accepted their offer to write a sample for a story, I've been profoundly bored by the result. Possibly my prompts could be better. I learned a little about writing from asking an LLM to write a simple scene in the styles of various authors, in order to learn more about pacing narrative prose, and while the scenes were readable, they weren't interesting. Same for a couple vignettes I've generated to entertain my kids with a scene of a Muppet exploring space or under the ocean. LLMs are competent language calculators, but they can't intrigue. They have no personality. They can nerd out about anything, and thus can't obsess over something to the exclusion of everything else.

Chris's post gives me a much better appreciation for how much writing is, at heart, about connecting with another human. We want to know that a person thought it was worth putting these words together, was willing to spend the time creating this story, sharing these characters, composing this sentence, and that when challenged about what they've written will defend it and maybe, in so doing, teach us something valuable. Reading fiction isn't about assembling information; it's about gaining understanding. Sometimes wisdom comes from juxtaposing information, but more often it comes from the enigmatic other, the person across the table or at the other end of the fiber optic cable. It comes from someone who's had skin in the game and had to make difficult choices.

My hope in the era of LLMs is that we as humans learn to find each other more fascinating.

Local-first software is distinct from local-only software. My local-only apps require the user to transfer state between devices, but local-first software is local first, replication second. As far as I've learned so far, that typically means having a server that can relay state changes, often using CRDTs. I've started listening to the localfirst.fm podcast to learn more. There's also a Local-First Conf and the website lofi.so. A related term I like is "LEAF computing", which stands for Local Execution, Autonomous, and Federated (I've also heard Local, Encrypted, Autonomous, and Federated). The term "LEAF computing" stands in contrast with "cloudy computing".

I treasure the values of the local-first software movement, specifically giving users ownership of their data, the ability to run software fully offline, much lower UI latency, and using local compute resources rather than servers in a data center. It's not the right architecture for many types of software, among them e-commerce and social media platforms. The former needs stronger authorization controls than local-first software can guarantee, and the latter operates at larger scales than can easily run locally (though there is Scuttlebutt).

Given those constraints, much of the local-first software I see advertised appears to be note-taking software. Obsidian is the clearest example, used for managing images and Markdown notes. BrainFrame looks similar. Allume captures whiteboard-style notes. Somewhere I saw a recipe tracker. Those uses are great, but I'm more interested in how local-first software can go beyond the zettelkasten. The best examples I know are Actual Budget, which tracks home finances, and some music players.

Do you use local-first software? Anything you'd recommend, either for using directly or for learning from? If so, email me!

foreignObjects

The first was in Causation, my simple cause-and-effect diagrammer. It renders everything in an SVG, and makes the text in nodes editable by embedding HTML using foreignObject. Turns out Safari has multiple foreignObject bugs. I ran into one which rendered every foreignObject in the wrong location, and another that rendered the elements on top of the elements that cover the SVG.

I fixed the positioning problem by calculating view transforms myself. I haven't yet fixed the overlay problem with foreignObjects, but I think I'll move the HTML content into a purely HTML layer over the SVG, then position elements absolutely. Most of the UI is an infinite canvas, so some glitches over the toolbar at the top are minor.

grid-template-columns and grid-template-rows

On another project, I used CSS's grid-template-columns and grid-template-rows to create a square grid:

.grid {
  display: grid;
  grid-template-columns: repeat(var(--column-count), 1fr);
  grid-template-rows: repeat(var(--row-count), 1fr);
}

The .grid DOM element can then specify its size by setting an element-level style attribute with the value --column-count: 5; --row-count: 5.

But on Safari, switching from a grid of fewer tiles to one with more tiles in the same width caused the grid to overflow its bounds:

The layout gets fixed on the next reflow. A couple suggested workarounds didn't help, so I ended up removing the CSS grid properties and instead set a percentage width for the tiles.

None of the apps are polished, nor bulletproof. I made them to learn, not just about a set of ClojureScript libraries but also about new developments in web technologies. Consider them scrappy fiddles. If you find any of them useful, let me know, and certainly report any bugs.

Here's a quick rundown of each app.

Tinycal

This is the fourth iteration of this tiny calendar. The first implementation is lost to time, but the second version (which I covered a few years ago) recreated it and just showed one year from beginning to end with buttons to export it to SVG or PNG. The third iteration let you configure the start date, end date, what day of the week to start on, which dates to show, and provided a print option. Those versions now redirect to the latest take.

The new version I built because my brother uses the exported PNG in an image editor to outline his plans for the year ahead, and I realized I could make that at least a little easier. Now Tinycal allows selecting dates and highlighting them in one of several colors. You can also add a note that labels events to the right of the calendar.

It's still a tiny calendar, so it gets crowded fast if you try to use it for scheduling, but I like it less for seeing the day-to-day obligations and more for mapping the broad strokes of the coming months, especially for seeing what weekends I have free. To help with that, the app can be saved to your phone's home screen and run as a progressive web app.

Conflict resolution diagrammer

Years ago I made a web-based diagrammer for conflict resolution diagrams, but I was never totally happy with it. Revisiting it recently to explore some tensions at work, I was pleasantly surprised to learn that CSS now has a grid layout that you can template using an ASCII diagram. That made it a lot easier to handle a more two-dimensional layout.

Most people aren't familiar with a conflict resolution diagram, so I added some documentation below the app to explain how to use it. It's easy to miss when you land on the page, so if you have design tips to improve it, send them my way.

QuizBoard

The very first real software I made was a pared-down version of Jeopardy! for a kids' study group. I implemented it in Visual Basic in junior high school and called it "Answers & Questions". It loaded categories and questions from a text file. The layout was hard-coded to an 800x600 screen resolution, so every time it was used on a higher resolution monitor, the computer's screen size had to be changed for the game to fill the screen. Eventually I made a version that scaled to screen resolution, but by then I didn't need the game and the rewrite was mostly a learning exercise.

A couple months ago I was asked for a new version, which I dubbed "QuizBoard". While Answers & Questions followed a strict Jeopardy! layout of six categories with five questions each, QuizBoard allows any number of categories, each category can have any number of questions, and each question can have multiple clues. At first I required a game to be made by editing the downloaded YAML file and re-uploading it, but that proved both cumbersome and error-prone, so I added a simple game editor.

I also added a presentation mode. Launching it opens a new window that can be shown on an external monitor and controlled from the original window. That gives the operator a chance to see all the clues on a question, as well as the answer, so they can decide if a team got the right answer.

Causation

In high school, I had to make a cause and effect diagram of the American Civil War, and I got carried away, spreading it onto multiple sheets of printer paper that I taped together into a poster. In college, I made diagrams for some of the European periods covered in freshman history, and when my classmates saw them, they asked for copies to study from. Probably if I had learned to make such diagrams sooner, I would have been interested in history sooner. I've also drawn cause and effect diagrams to explore complex systems.

Since college, I've tried a few different graphing tools for making cause and effect diagrams, but I haven't found any I've liked. Graphviz and Mermaid are text-based and easy to lose my place in. Excalidraw is more visual and manual, and arrows stay connected to boxes, but when drawing a current reality tree) I want to link edges together to denote multiple conditions that need to be true to produce an effect, and Excalidraw doesn't offer that without jumping through hoops like intermediate nodes.

I finally sat down to make something suited to my usage. It snaps nodes to a coarse grid, doesn't require drawing arrows manually, allows inserting nodes in the middle of existing links, and most importantly, lets you link edges to each other. My favorite feature is being able to move whole subgraphs, dragging all of a node's descendants or ancestors with it to make more room.

Home Electric Cost Optimizer

My father has a hybrid vehicle and was curious if he got solar panels whether he should charge the car with surplus solar power during the day or use cheaper rates from the grid at night and sell surplus solar power back to the grid. I made this calculator to explore possibilities.

There are a lot of factors in the conversion of solar irradiance to actual power output. Latitude is the main one, but it's also affected by your local climate's tendency toward cloudiness, the efficiency of the panels, the direction the panels face, and their angle. I simplified all of that by asking for max power output on the summer solstice, then scaling solar irradiance to produce that.

Making it for someone other than myself meant more back and forth communication with a "customer". The physicist in me desperately wanted to reduce units like kilowatt-hours per hour to just kilowatts, but to a layman looking at his electric bills that was less intuitive than kWh/h.

Timeliner

Another history-related project is Timeliner, which I started because I frequently find myself either surprised by how far apart different events were or how unrelated events happened at the same time. For example, I tend to forget Mozart lived during the American Revolution. To gain a better perspective, I wanted a timeline visualization tool that let me add arbitrary historical events and zoom and scroll horizontally. Probably there's a good tool for this, but I forgot to look.

Making it, I discovered there's a native HTML color element, and while the Mac color picker lets you define swatches, it pops up a new window that can lose focus to the original window, which for me caused some odd behavior.