At the end of this most recent January, I wrote Narrowing the Cone of Error, The Origin Story of a High Output AI Coding Workflow, a story about how I had built my AI development workflow. Things have evolved in the last month since I wrote that.

ADRs (Architectural Decision Records)

At the time when I wrote the article, I had seen previously seen people who had used ADRs in the course of building with AI to help it direct its action as it built to maintain design integrity. I knew NoteCove had a few places where Claude had been getting things wrong from time to time in the sync architecture that I’d have to fix. Given the information about ADRs I’d seen, it occurred to me that an ADR (or a set of ADRs) might be something to try as I had some upcoming work on NoteCove that would be adding things that needed sync support.

The Origin Story of /feature

I’ve been interested in personal organization tools for a long time, and never really been happy with them. I’ve worked on dead-tree paper a lot, and have used some online tools that I’ve liked, but never had the mix of “this actually solves everything”. I used to work at Dropbox on Dropbox Paper, and I miss it every day. But while it was good, is was only a point solution in what I really need.

This is a presentation I’ve done now about six times, starting back about 6 years ago. It stemmed from seeing people new to being a tech-lead on a team (either as manager or not) and what were the common pitfalls they fell into. So without further ado, the talk.

Hi and welcome to the non-technical guide to technical leadership!

One preface here before we start, I refer to the role of tech lead (or TL) often in this talk, but to be clear, the tech lead is a role, not a title. You may be an engineer, or a manager. Basically, any project which you are responsible for driving technical decisions on, you are the TL.

When I switched to management last year on April 5, one of the things I wanted to start with was to make sure that my teams understood what they could expect from me and hold me to. I had been at the company for over three years and interacted with many of them before, so I wasn’t a stranger, but one thing I’ve learned is that clarity rarely hurts in situations like these. And so I wrote up a “contract” of what they could expect from me. I later updated it to be what they could expect from the managers that report up to me as well, including things like PTO, sick time, not micromanaging, and so on.

I’ve only been weaving for about four months now, but have had a lot of fun doing four shaft patterns on my rigid heddle loom (a 16" Kromski Harp Forte). My current project is pretty complicated. So I’ve picked up a few techniques that I think have been useful.

Weaving has been around long enough, so I don’t assume this is a novel invention, but so far it has worked well in allowing me to be much more confident that I’ve got the threading right before plowing ahead.

I’ve done various forms of retros over the years, one of which I blogged about too. Following Cian Synnot’s example, I had done Four L’s. I also had done a quarterly “plate spinning” check to make sure I’m not spreading myself too thin, and also had a quarterly calendar audit (I’m in a lot of meetings) to make sure I was spending time in the right places. But as much as I had done, I realized that I wanted for something more regular (monthly, rather than quarterly or yearly) and more concrete, as for me, a retro like Four L’s is too nonspecific.

I did a talk for my org, Developer Experience (formerly part of EEE), based on my Influence Without Authority post I did back in 2021. It circulated a bit inside, and the Pup Culture Blog at Datadog decided to write a blog post about me based on it!

YAML, go templated YAML, HOCON, HCL(2), GCL, JSON. Just some of the common languages used for configuring the world we live in, because they need to be human readable, not just machine readable. At first, it’s all fine, but then to ensure consistency and reuse, they add templating features, and the templating languages become more complex to handle the emerging needs as projects require more.

Some evolve to be Turing complete, some specifically eschew Turing completeness, as they need to ensure that at runtime, nothing bad happens. As the templating advances, things get harder to understand and debug as the configuration language rarely provides sufficient tooling. It can be hard to understand what the result of all the templating actually is. Eventually the templates, and sometimes their consumers, become impenetrable. That’s before you get to some of the odd quirks of some of them, to ensure you get the quoting or indentation correct as you’re templating. Either way, as things scale up, configuration gets messy.

There’s a chunk of code I’ve been playing with the last two and a half-ish years (judging by its git history) that for me is just really cool. It’s something I’ve been aware of since reading SICP, and I wrote a version of it probably a decade ago, but it was in a very specific application, rather than the more simplified and generalized form I have it in here. I had been reading about Prolog when I was reminded of it, and that solving things in a normal programming language rather than Prolog would be simpler, if only there was something that dealt with it. After thinking about it more, it could be used to do formal verification, since what TLA+ does is search the state space of the system specified in TLA+ or PlusCal (because raw TLA+ is pretty terrible, though PlusCal isn’t great either). While I’ve not actually done formal verification with it yet, I do have code that uses it to solve mazes, sudoku and KenKen puzzles, figure out valid magic squares, generating power sets, counting in binary.

I’ve been working with people and talking about their organization systems to help their systems help them. There are a few different systems that people use, and I wanted to figure out this question: what really are the essentials to have something that works?

If your system isn’t quite working, it’s easy to feel overloaded. There’s too much to do, it’s hard to prioritize, it feels really hard to get a handle on what you should be doing. First, if you haven’t read Getting Things Done, start there. But the goal is to gain some sense that you have things under control; that you are confident you are working on the right things, and aware of what things need to be done, and have a good feel for the order they should be done in, at least given current conditions. If you take nothing else away from the book, it’s that you need to capture everything and put it into a system you can trust.