Adam Keys is Thinking

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. 💯📈

Can’t live with ‘em, can’t live without ‘em🤷‍♂️

A product team (at least the ones that have been working for more than three weeks) has a backlog of work they’d love to tackle, but now’s not the right time. Maybe it’s not the most important, a practical solution isn’t in-hand, the technology isn’t ready yet, or a dependency hasn’t started work yet. Either way: a growing, somewhat discouraging list of things they want to do but can’t yet.

Over time, a backlog evolves to many forms. None of them are ideal. We have to look at backlogs for what they are: an artifact of time’s finite-ness and our finite ability to do work in the present.

A “big pile of sadness backlog” doesn’t acknowledge limitations in time and capacity. It imagines a future where we can do everything we’ve ever wanted. The backlog actually gets shorter. All those problems we once wanted to solve, we can. We are also a bit taller, more attractive, and feel a bit younger while we’re at it.

But that day never comes, and we’re left with a sad backlog of things. Almost (and this is the nefarious part) all of them less important than what we’re currently doing, but still, we think, important. So it stares at us from the shadows, a bit sad and discouraging us that we are failing at our job by having this large backlog of ideas and promising projects. At least we think they’re promising! More likely, in my experience, attempting to triage the pile of sadness backlog yield two more meta-projects around organizing the sadness to highlight the truly sad from the merely unfortunate. 😮‍💨

It’s more helpful to look at a backlog as numerous maybe-good ideas sent to our future-selves. By definition, a backlog is speculation. We thought executing on these projects and tasks would improve things, but we won’t know until we do. Schrödinger’s cat and all that. Storing all that speculation away in a pile is healthy. If it turns out one of these ideas is the right starting point for the next most important problem we face, we’ll pull it out of the backlog and give it a think. Otherwise, it stays there, putting no current work at risk.

The contents of a backlog are frozen in time. The tasks, projects, docs, designs, screenshots, diagrams, etc. all reflect a point in time. Some call this rot, implying “hey, we should have been better about keeping this campsite clean and used our (infinite 😜) time to tend it”. IMO that’s not the best approach; better to regard aging tasks as issues and solutions from a point of time. They may no longer reflect the circumstances the product and team currently face. Items in a backlog necessarily need updating by a PM or developer to figure out if they still make sense, would solve the problem, or are a direct solution to that problem.

I have quite the extended personal backlog of items to read and project ideas. When I regard them as missed opportunities, as evidence that I could have been at least a little more diligent in managing my time, it’s stressful and discouraging. When I instead regard it as a pile of ideas in reserve for mornings I wake up and none of my current hobby projects are enticing or what I’m reading isn’t doing it for me, then those backlogs are useful. Granted, said lists aren’t getting much shorter.

Perhaps, a backlog is a defense mechanism. They are, at times, a way to deliver a soft no, to ourselves or collaborators. “Not a bad idea, but not something we can get to right away. It’s in the backlog. Maybe someday we’ll come upon it.”

Or, you may have an impeccable backlog! All killer, no filler; like a “no-skips” album, but in product backlog form. If you’re out there, please let us know how you got here and how much effort it takes. 😆 (Really, if you’re out there, I’m intrigued!)

The flip side is no backlog at all. The project work is a river and if something interesting floats past, you seize upon it. Otherwise, you let it float downstream and don’t worry about it too much. Or, there’s no team backlog, but the team members keep a list of ideas/task/projects that might be interesting in the future and bring them up at opportune moments. That works too!

🌶️ Hot-take: if you’re a manager and find you¹ miss building…then build²!

• On your time: mornings, weekends, national holidays.
• Whatever you want: tools for yourself, something frivolous, something practical.
• However you want: in an esoteric technology, in a boring technology, in a domain you’ve always wanted to explore, with LLM copilots, building every piece from scratch, without using conditionals, whatever!

Avoid:

• Swooping into your team’s current projects³.
• Imposing your discoveries/ideas on unrelated code reviews.
• Inventing projects and putting yourself on the critical path.
• Building and handing off a proof-of-concept to an unsuspecting teammate to finish.
• Thinking the grass is greener on the hands-on/IC side.

Don’t react to the bad parts of your previous role. It’s increasingly tricky to ride the pendulum between IC and leadership roles. You may only get to pull that lever once. Maybe building something for yourself will temper the temptation to go back to an IC role.

Instead, see if you can scratch whatever hands-on building/coding/designing itch you have in your time. You’ll necessarily have to scale it down. Honestly, that’s a great constraint! If you tried to build something big, you’d have to lead and manage it and, if you recall, that’s what we’re taking time away from in the first place here.

Follow your curiosity. The very best part about building on your time as a manager is you don’t have to make great decisions. Whatever is of interest, go with it.

Want to build a compiler, but you work in web apps? Go for it. Want to build a game, but you work in compilers? Go for it. Want to build an asset tracking web app in a really particular way, but you work in games? Go for it. Want to write in Haskell, but you work in Ruby? Go for it.⁴

Go for it.

A couple of lessons on leadership in ​Herbert’s Dune​:

“Give as few orders as possible,” his father had told him…once…long ago. “Once you’ve given orders on a subject, you must always give orders on that subject.”

Avoid, whenever possible, making decisions for people and teams. It may end up discouraging or preventing them from making any decisions for themselves in the future.

Frequent top-down decisions are the autonomy-killer, they might say. 🤓

Hawat arose, glancing around the room as though seeking support. He turned away, led the procession out of the room. The others moved hurriedly, scraping their chairs on the floor, balling up in little knots of confusion. It ended up in confusion, Paul thought, staring at the backs of the last men to leave. Always before, Staff had ended on an incisive air. This meeting had just seemed to trickle out, worn down by its own inadequacies, and with an argument to top it off.

This is what bad meetings feel like; they deflate like a balloon. Worse than indecision, they bring confusion about how to proceed, where efforts really stand, or if the current approach is the right approach. Not necessarily because of debate or disagreement. But, the lack of consensus or direction certainly doesn’t help.

Reader, I want to (once again) talk to you about the life-changing power of making a list and putting it in order.

Ambiguity of like, “what are we gonna build?” or “how are we supposed to build this?” Or was it supposed to be A or B or why did we make this decision? So having the checklist of “this is the thing,” it is a very, very cheap way to eliminate most of the ambiguity.

– Kristján Pétursson, Human Skills 018 — Creating Clarity From Ambiguity

Tasks lists are great for capturing and organizing what you want/need to do. They are sometimes good for thinking through how to execute on those tasks and projects.

Ordinarily, I’m too focused on all those incomplete items The empty check boxes, the lines that aren’t crossed through. So much potential. It’s exciting and overwhelming!

I rarely use my task list to reflect upon what I’ve done. To retrospect on how much I accomplished any given day or capture a post-hoc note or two on follow-ups, what worked, or to merely pat myself on the back for a day of honest work.

So I’m trying this right now! But, applications could stand to add more affordances for looking back in time too. This goes for applications like Things as much as it goes for Jira, etc. It’s probably our work and hustle culture. 🤷‍♂️ Always looking forward and rarely slowing down to say “hey, I did this, let’s get excited about that!”

One of the nice things about Kanban boards is you eventually end up with a giant pile of things that were done, and that’s a nice way to feel the momentum building that a bunch of stuff got done. Let’s get more of that.

“Dunbar’s number is a suggested cognitive limit to the number of people with whom one can maintain stable social relationships—relationships in which an individual knows who each person is and how each person relates to every other person”.

Corollary: any group size approaching 150 people (Dunbar’s number) includes at least one person who knows about Dunbar’s number.

To paraphrase a classic joke, “How do you know if someone knows about Dunbar’s number? They’ll tell you!” I’m telling you, right now, I know about Dunbar’s number. 🙃

Practically, I think this implies:

• If you’re designing an organization close to but not exceeding Dunbar’s number, you can hand-wave the details of when it grows to exceed Dunbar’s number. Someone will enthusiastically let you know that the organization has exceeded Dunbar’s number and might need reconsideration. 🥸
• For organizations as small as 10% of Dunbar’s number (15), there’s a pretty dang good chance that someone knows about Dunbar’s number. For organizations any multiple of that size, you don’t need to go around telling everyone about Dunbar’s number. Chance are, someone is telling everyone about Dunbar’s number. 😆

My experience in (software) teams is there are breakpoints far smaller than Dunbar’s number that matter even more.

FWIW, these are all folk rules. I haven’t seen rigorous work that backs any of this up!