Adam Keys is Thinking

You’re deep in eldritch code, a product problem, or a cross-functional issue that is affecting your team. Hours have passed, and you feel like you’re only starting to get your bearings with the issue. Finding a solution, let alone considering its consequences, seems further hours away.

You’re down a rabbit hole. You need to explore a very open-ended concern, but you also need to maintain a bias toward action.

Don’t go without a time box or teammate. Set a time limit. Or, ask a colleague to keep you accountable. You want a constraining mechanism to pull you out of the hole if you get lost.

“Rubber duck” the issue before you start. Explain it out loud or write a summary in your notes. You may activate a different part of your brain and talk yourself out of the rabbit hole entirely.

Keep notes. Track every conceptual tunnel you explore. Note the dead-ends and red herrings. Show something for your effort, even if you don’t find what you were looking for.

Tell teammates what the rabbit hole is and why you think it’s necessary. Ideally, you can explain this in a sentence or two at most. Think about how long you think it’s worthwhile to go down that rabbit hole. Don’t spend more than that in the rabbit hole!

When you encounter black boxes, rabbit holes in rabbit holes, note them and keep moving. You’re already distracted by this rabbit hole, don’t get distracted from your distraction! Not all rabbit holes are worth exploring – some lead to deeper problems without payoff.

“Puzzling Evidence”, The Talking Heads. Somehow I’ve just noticed this song. It sounds like if the E-Street Band helped write a Talking Heads song. Which is not a thing I would expect of The Talking Heads.

Get Up With It, Miles Davis – I missed this in my deep dive. It’s real good! Very clanky.

Naked Lunch soundtrack – Howard Shore, Ornate Coleman, London Philharmonic Orchestra. Another fantastic discovery. Jazz/bop film soundtracks - I did not realize this is a sub-genre!

The Birthday Concert, Jaco Pastorious – like the opening of SNL was a whole album. Also, a curious preponderance of steel drum solos. This was an extremely formative album for 16-years old Adam, but I recently revisited it and still love it.

The Great Concerts, Dave Brubeck – another favorite of 16-year old Adam. Most notable: in the liner notes, the drummer noted they took every song way too fast. I think this worked out.

Mercy, Mercy, Mercy, Cannonball Adderley Quintent – “the” soul jazz album. More traditional Joe Zawinful, great contrast to the Weather Report stuff. Could you pull off the name “Cannonball”? I could not. The title track is one of the only songs I taught myself on piano, but I can only play one hand at a time. 🤷‍♂️

Don’t sweat the network or medium.

It’s all tinkering at the margins! Serving at the pleasure of the algorithm! The core concern, the thing that really matters, is doing interesting things. You can literally forget about everything beyond that. Interesting can mean whatever you want!

— Aaron Francis, Reputation is portable

I could clip the whole article! 👏🏻

Networks come and go. Platforms come and go. Followers come and go.

Your reputation is portable. You take it with you wherever you go.

This works because the particular networks don’t matter (much) in the end. It’s the people! If a network has reached critical mass, and your people or scene are there, then you don’t need to think much about anything else. How you post to a particular network, or how popular you are on any given network, matters less than participating in the network at all.

What matters is doing and sharing the work. Finding the network with your people or scene. Telling people about your work. Supporting the work of others on the scene.

When you focus on the core, the craft, you’re free from the algorithms. Good tweet flopped? No worries, I’ve got plenty more. Bad tweet succeeded? Awesome, I’ve got plenty more. Keep doing things, keep hitting the publish button. By all means learn from your successes and failures. Adjust your strategy to meet your goals. But remember, you can afford to play the slow game. Building something durable takes a long time.

It’s tough to play the long game lately. In particular, because social networks (and news media) are primed to tell us the short game is everything.

Should my favorite social platform collapse tomorrow, I’ll take my reputation with me.

Granted, these networks can boost us in pretty amazing ways. But, we exist largely outside of them. At the end of the day, we are what we’ve done and who we’ve helped along the way. These networks aren’t built to track our value as people, so don’t sweat it.

In short: like any method of working that is copied from one organization and pasted into another, very different organization, there are chutes and ladders. Habits and practices that will help you move faster or skip ahead outright. Anti-patterns and missteps that will set you back days and weeks.

Herein, some things I learned whilst using Shape Up over the course of a few years across teams of varied experience and specializations.

How teams succeed at Shape Up

Three practices that might help your first Shape Up projects:

The Model-T button. The first slice of your solution is crucial to success at Shape Up. I found that the more that slice was constrained, the better. I often tried to pitch the first working demo as “just a button that does the thing; you can have any button, as long as it’s black”. No ornamentation, no workflow, no layering, only a button that solves the pitched problem end-to-end without any “magic behind the curtain”. When the team quickly arrives at this milestone, it opens up the rest of their time to iterate on everything else that makes a suitable solution. And, they can do so with confidence that the big question of “can we solve this?” is already answered.

Coherent jargon leads to the good team-think. It warms my heart, a big moment of pride, when teams start using language as a tool for thinking about their project at a higher level. Even if the jargon is a little silly or requires explanation to an outsider. When teams wield conceptual compression to make sure they’re aligned on the specifics of the problem and how they’re solving it, I’m pretty sure they’re going to succeed at delivering the pitch. Even if the underlying problem or solution spaces are complicated!

Save some margin for finishing, details, socialization, delivering, etc. The most successful projects I saw left time at the end of the iteration to finish. I often called it “pencils down” time. In part, this was a breather and a milestone to let the team know they were done with the development part. It also lets them mentally shift into the mindset required for QA, fixing details, finding bugs, writing documentation, preparing release checklists, sharing changes with colleagues outside the product team, etc.

Rakes I’ve stepped on whilst Shaping Up

Three (bad) habits that could stymy your first Shape Up project:

Aligning work based on individual specialization. If all your tasks have “front-end” and “back-end” labels, you might end up with something you can’t quickly demo, iterate, and release. Related, if the first slice of your project doesn’t show an end-to-end solution, you don’t actually have your first slice. Lesson: you may need to work together more intensely, and decompose the work differently, than you do with processes that regard the work as simple queues.

Pitches and product docs so deep, you can’t see the ending from the beginning. You may need to split it up. Shape Up is, in many ways, about splitting work up more sensibly. But, if your pitch doesn’t work as independent components/solutions, you’ve got a problem! The good news is, splitting up a pitch into tasks is very similar to splitting a pitch into multiple pitches; it’s all about chasing down the dependencies, minimizing them, and thinking about how to build off existing work. Splitting up a too-large pitch is potentially a good way to practice at an essential activity of Shape Up without committing to a particular project just yet.

Pressing on with a wobbly project. Path dependence is tough. If you aren’t willing to use the Circuit Breaker on your first few projects, it becomes increasingly difficult to do so later. Without the ability to cut loose from a project that isn’t going to expectations, you’ll have lost the ability to do fixed time and scope. That’s (probably) why you looked into Shape Up in the first place. I find it important to keep in mind that Shape Up is, in part, about working with hypotheticals and options. It’s often better to stop a project that isn’t going well and move on to the next (most likely) equally promising, project.

I have a lot more to say about Shape Up! But, I like putting shorter, punchier bits out, so here we are. Please let me know what you’d like to hear more about!

What We Do in the Shadows, final season + finale: they did a fantastic job on the finale. The last season had a few stand-out episodes; it doesn’t feel like the show went one season too long. Favorites: “Sleep Hypnosis”, “The Railroad”, “Lazlo’s Father”.

Sticky: I wanted to like this because Margo Martindale is a delight. And, it was only six (short) episodes, so I thought it was going to be an easy, one-and-done watch. The finale left me thinking they intend to bring more material. But the world is flat and clearly wants to be Fargo, but a bit further north.

I would have found it “just okay” if they’d managed to get in and out with three hours of material. As it is, it seems like another season is intended, which leaves me feeling meh and not sure if Amazon will even pick this up to close out the narrative. On the upside for the creators and cast, at least Amazon seems most willing to let shows run long than other streaming studios.

Skeleton Crew: the adventure is good, the cast of kids is fun, the surrounding world is great. I wouldn’t have thought Goonies or Pirates of the Caribbean, but Star Wars, would work, but it’s hitting the mark.

For All Mankind: we’re rewatching parts of this ahead of the forthcoming season. I’m reminded that the first season in particular is a real dinger. And half of the dramatic tension in the show is generated by the foolish actions of one particularly space-faring family.

There are many ways to feel like you’re living out the same workday over and over. Weekly, if you’re unlucky. Let’s talk about two in particular: failure to write it down, and failure to decide (on how to decide).

Write down the ways you didn’t choose, for God’s sake. Because otherwise you’re gonna run into… every approach has a problem and as soon as somebody runs into the problem they’re gonna say “oh, why didn’t we do it the other way?”

If you write down why you didn’t do it the other way they’ll look at it and be like “oh, right, right. Yeah, it sounded worse the other way” and they can move on. Otherwise the same conversation happens again.

— Kevin Ball and Kristján Pétursson, Creating Clarity From Ambiguity

Besides the general-purpose wisdom of “write it down”, this specific scenario hits home. Having to re-litigate a team’s decision every time a curveball comes along is both exhausting and a morale killer. Been there, would like to avoid that.

The alternatives-not-taken don’t need detailed write-ups. It works well enough to enumerate them, briefly describe the idea, and highlight the shortcomings or reasons that decision wasn’t taken.

Storytime: the last team I worked on that used MySQL had the “why didn’t we do it the other way?” problem every time a new developer was onboarded.

This was in the mid-2010s, when PostgreSQL and MySQL were reaching feature parity as single-host databases. PostgreSQL replication was just good enough to use in production. Further, it was several years into Heroku running PostgreSQL as a default, so many Rails developers had either not used MySQL or were unsure why one would choose MySQL.

Sometime in their first week, countless developers would ask or suggest some variation on “why don’t we use/why aren’t we moving to PostgreSQL?”. And every time, a bespoke reason was given, usually by a somewhat overworked/cranky person from the ops team. It typically rhymed with “this was the Rails default when we first built the app” or “migrating a database is an enormous effort with many second-order consequences and next-to-zero customer benefit, so here we are”.

If we had instead taken the time to document this in the onboarding material? Priceless, and one fewer interactions with cranky ops folks!

More talking. More translating. Action items are assigned, which gives everyone the illusion that progress was made. And we all return to our respective regional offices and wait until we have the same meeting again, where we attempt to communicate intelligently with each other. But all we really do is schedule meetings… when what we need to do is figure out who makes decisions.

— Rands in Repose, Bits, Features, and Truth

Same story, different tune. If a group (of leaders) can’t decide how to operate, collaboratively think, and make decisions, they’re doomed to repeat the same conversations and action items.

In my experience in this kind of ongoing and repetitive meeting, the root problem is failing to decide. Deciding how to decide is an important decision to make! If you come into a meeting not knowing how you’re going to get out of the meeting with closure, the meetings will just compound. It’s like interest-only payments at the beginning of your mortgage, slightly demoralizing but absolutely required per the (very) long-term contract you’ve signed.

My kingdom for software that makes it easier to collaborate, think, and decide than it is to schedule ​one more meeting​. 🙄

It was a good year of reading, for me. I read some big books. I got more insight out of the books I read. Furthermore, I read things I don’t normally read, like philosophy and books about octopuses that help some troubled folks find their way in life.

A few things worked well for me, so here I am sharing them.

Bring a (computer) assistant

I used ChatGPT and Claude to ask questions about tricky passages in non-fiction and philosophy books. This kept me “in the text” more. I was less distracted by wondering what some term meant or the context of a historical reference. LLMs are great for asking questions about or summarizing passages, expanding upon interesting ideas, and getting historical context.

The “world knowledge” trained into these contemporary LLMs is sufficient to answer most questions without the need to provide extra context. I haven’t found the need to fiddle with trying to load the text of books I’m reading into an LLM to get it to answer coherently.

As ever, trust but verify anything a computer masquerading as a human tells you.

Read actively

Laid back on the couch, propped up on a comfy pillow, bathed in natural light (not-too-bright, not-too-gloomy), and just the right temperature. This sounds like the portrait of an ideal reading situation.

But, I’ve found that reading challenging books, and getting more out of them, requires a more upright and active posture. Holding the book open on at a desk with one hand with a pen or highlighter at the ready in another is the ideal for challenging books. Hands-on, it’s important.

Highlighting, summarizing, annotating, and commenting on interesting passages keeps my mind in the game for longer. I’m more likely to return to the ideas and get something out of them. I often combine this with my 🤖assistant to summarize dense passages, ask questions about something I think I’m missing, or to expand on words/ideas I don’t already know.

Always Be Choosing (Good Books)

It does no good to read better if I’m reading things that I don’t enjoy or learn from.

I regularly parallelize my reading across a few genres, at least fiction and non-fiction. At times, comics, philosophy, or technical books. At other times, I’ve tried to cluster a few books in the same topical area and enjoyed it. Fiction is the least parallelizable genre, in my experience. It’s tricky to keep multiple fictional storylines/characters in my head, in the same way that holding the button mappings for multiple games in my head is tricky.

I have enjoyed doing Commonplace Philosophy read-alongs. I’m getting a lot of out of the Arendt read-along (a very challenging text, for me), the Aristotle Ethics one was insightful, and I’m really looking forward to the one on The Dispossessed. So, “philosophical sci-fi” will probably figure highly in my 2025 reading choices.

Clustering around a topic, another idea I picked up from Tyler Cowen, is fun when I find a few books stacked up around a topic. That said, given I choose to read tome-like non-fiction in particular, having three non-fiction books in progress at one time is not often workable.

The flip-side of selecting good material is changing my mind. I’m still learning to stop when the material isn’t meeting my expectations. Not only should I throw more books, I should consider aggressively skimming/summarizing-via-assistant/copilot when books turn out to be too thin or simply not the right thing.

You (still) can’t beat a dumb-old Kindle

Reading on a Kindle is more pleasant than an iPad.

Despite better functionality on iPad for active reading, it’s way easier to read on a Kindle device. It’s partly down to size and partly down to lack of functionality, as ever.

You can’t underestimate the benefit of reading speed and the difficulty of distracting yourself when reading on a Kindle. 🤷‍♂️

That said, the Kindle app on tablets does have a few things going for it, and I hope someday these things will come to a reasonably distraction-free Kindle device, someday:

• “Read it to me”, not audiobooks, just plain old text-to-speech voices, makes some kinds of reading easier to sustain because there’s a voice to focus on and keep up with.
• Adding notes and connecting dots to highlights becomes a “secondary session” activity when reading on Kindle alone. Ideally, that kind of entry is easier on a Kindle device. I didn’t realize there was magic in the iOS keyboard implementation until I tried to type quickly on a simplistic Kindle. Whatever Apple has implemented there, Amazon should pick up on it.

A wishlist for 2025

My kingdom for short, dense non-fiction instead of short non-fiction that is merely a longer magazine article restated several times.

Comic-style “primers” on deep topics like Sartre and chaos theory are my favorite way to start on big ideas. I hope more complicated topics and wicked problems will get this treatment in 2025, and that I’ll discover said primers.

I’d definitely kick the tires on an interesting, slightly better integrated way to read long-form, i.e., books with an LLM-powered assistant at-hand. The bar is low here; I’m copying and pasting between apps to make this work right now.

Maybe Amazon, Remarkable, Boox, or even Apple will make the reader/hardware situation more exciting in 2025!

I wanted to tinker with llm and “AI engineer” up a humble tool for working with my notes, writings, highlights, etc. Emphasis on humble: if I could tinker with any one of those datasets quickly and iteratively, I would mark it as a win. (Previously, Scaling down native dev.) Medium story short, I exported some of my reading highlights, loaded it into a database, and wrapped a quick UI around it to navigate my highlights via embeddings rather than keyword search. A few short sessions later, maybe a few hours total, I had something interesting working. 💪🏻

1. Data

For several years, I’ve used Readwise to capture highlights and search/review them later. Handily, Readwise has CSV (and tree-of-Markdown files) exports of all one’s highlights. As data formats go, CSV is nearly perfect for this exercise. It’s structured, so parsing is not required to shoehorn it into a low-ceremony data pipeline. That said, Readwise’s export isn’t perfect: notably it lacks URLs the highlights started with. But for experiments, it’s a start.

2. Pipeline

Thanks to sqlite-utils, I can generate a SQLite database from the export CSV. This all happens by convention with the sqlite-utils command line.

db:
    sqlite-utils insert \
      highlights.db \
      highlights \
      data/readwise-data-2.csv \
      --csv \
      --pk id

No bespoke (Python) code is required in this whole pipeline process. I ended up encapsulating the steps in a Justfile, but anything that can run shell commands would have done the trick.

Step two is to generate embeddings. With the right install, this is another one-liner, this time with llm. We query the database generated in the previous step to give us content to pass through to a text embedding model. The generated vectors are stored into the same SQLite database.

embed:
    llm embed-multi \
      docs \
      --database highlights.db \
      --store \
      --sql 'select id, highlights."Book Title" as title, highlights."Highlight" as content from highlights' \
      --model mpnet

There is no step three! The data is ready to query for “semantic”, not keyword, similarity search. To prove to myself I had an end-to-end working proof of concept, I used this snippet to query the data:

# $ just query "now is not the time for notes"
query q:
    llm similar \
      docs \
      --database highlights.db \
      --content '{{q}}'

3. Prototype

Next, I put it all together in a FastHTML app. This was fun! FastHTML is great for this kind of bespoke, informal hacking. Caveat, some of this may not be idiomatic Python. I’m just coming back to Python after not having written it in seriousness for twenty years.

• Using the dataclass decorator on a class and a method for converting an object to a “FastTag”, love this for low-ceremony but typed data modeling.
• I finally got the grasp of Python’s generator syntax. I want to like itertools, but it’s a pain to use. (🌶️ Ruby’s Enumerable remains undefeated.)
• JSX-like syntax to structure UI in code is great. This approach falls down every time I put a designer in front of an editor, but I’m going to call it: this is the mark-up/UI-construction ergonomics developers crave.
• There’s no need for a layered web-app approach here. There’s a similar function that turns query text into similar highlight “model” objects. That’s a nice affordance for working quickly and loosely.

Conclusions

Python’s has pleasant things going on lately. Even a career Ruby developer like myself can find kind things to say. 😉

The trickiest part to building with LLMs and generative AI is source data. Prompting a model as-is is not much more interesting than using ChatGPT or Claude. Ergo: look to one’s notes, posts, highlights, etc. to find compelling data to build upon.

Variations on RAG (this is probably a bit short of calling itself RAG, but it’s very close) produce more appealing results than keyword indexing, but not by much. I don’t think it’s the center of a product yet; more of a sidebar or enhancement.

All of this took less than five hours to build. I’ll probably end up spending a couple of hours total writing it up. This is the kind of “working with the garage door up” kind of thing I want to do. 💯📈