By now, developing Tolaria is a big chunk of my working time (about 40%, to be precise). I like this balance and I am happy I can regularly write articles about AI coding coming from my own experience, as opposed to pure research.

I also don’t want to end up writing only about that, and so far I have kept a schedule of about once a month. This feels like is a good cadence: it’s feel overwhelming for readers, and gives me time to produce actual updates to the workflow, as opposed to posting always the same things.

So, today I am covering a few workflow updates, but most of all I am introducing a new set of partnerships I am very proud of.

So let’s dive in!

💧 The State of Tolaria

First of all you may wonder: how is Tolaria doing? Pretty well, if you ask me.

From a growth perspective, it has now almost 18K stars on Github, 100K+ downloads, and thousands of daily active users.

From a product perspective, this month we delivered a ton of updates, including some massive ones, like the support for native spreadsheets.

You can now create and edit spreadsheets inside Tolaria with Excel-compatible formulas in a completely open and portable format, which is basically CSV with a frontmatter on top.

We also improved a lot of the editor experience, adding collapsible headings, block navigation, better spacing and typography, all while making everything faster than ever. If you haven’t tried it in a while, you definitely should!

I really enjoy developing (and using!) Tolaria, so the question recently has rather become: how do I make this work sustainable, while keeping everything free and open?

Enter our tech alliance!

🦸‍♂️ Creating our own Tech Alliance

The tools I use to develop Tolaria are no secret — you can figure out most of them by looking at the repo, the AGENTS file, hooks, and my own articles.

So, over the last month I reached out to the ones I use the most to figure out if we could work together to make the development of Tolaria more sustainable on my end via open source sponsorships, in return for me spreading the word about how I use such tools, and providing good feedback on how to improve them.

The result is an alliance that as of today includes four tools: CodeScene, CircleCI, Codacy, and Unblocked.

These partnerships allow Tolaria to stay free and open forever, and even give us the opportunity to accelerate by hiring a great product engineer (if you think you are a great fit, please reach out and say hi!).

So today I will tell you more about my workflow, which includes these tools — but first an ethical statement: I will only ally (and stay allied) with tools I personally use and believe are the best way to do what they do. As you will see these are non overlapping: each has its own job, so they really make for my tech stack. Over time we will also expand on this and create exclusive deals for Refactoring subscribers!

Before we talk about the tools, it’s worth refreshing how I think about controls for code written by AI. I have written about it in this recent piece 👇

In a nutshell, I steer AI output in three main ways:

• ↪️ Guides — instructions in the AGENTS file and skills. Not 100% reliable: the AI may or may not follow them.

• 🔄 Gates — deterministic checks that don’t let bad code move forward if some conditions are not met.

• ↩️ Guards — fallback procedures that typically run once a day to fix what goes through the cracks.

Out of these, the most important part is the gates, because they have the (deterministic) power to stop bad code, so the more I can express this way, the better. Most of the tools below are integrated this way.

So let’s go 👇

🩺 Code Health — with CodeScene

CodeScene probably needs no introduction because I have written about it many times here. I am a big fan of Adam Tornhill‘s work, which to me is about two big things:

• A proprietary algorithm to calculate code health, that considers 20+ factors.

• The “hotspot” approach, which looks at git history and suggests refactoring targets prioritizing files that are changed the most often.

I integrate CodeScene as a hard gate in local hooks: new code can’t be committed if it’s not a 10/10. For modifying old code, the AI needs to follow the boy scout rule: leave the code better than it found it. So it measures the code health before touching the file, and after, and the score needs to be the same or higher.

After any commit that improves the overall codebase health, the AI also increases the thresholds, to create a positive flywheel.

After four months working like this, now the code has perfect health, and the current threshold is literally 10/10!

🔒 Security and Quality — with Codacy

Codacy works on code quality too, but from a different angle: rather than scoring files, it surfaces individual issues.

Issues come with severity levels and belong to various categories, like security, performance, compatibility, code being error prone, and more.

Codacy has an MCP that I use to steer my Codex locally, and to implement an actual blocking gate before it pushes any code. All new code has to be issue-free, and when touching old code, the AI also needs to fix existing problems, other than making the business changes.

I am also working with the Codacy team on their new product Verity (you can join the beta for free here), that aims to steer agents’ work by creating a knowledge base of past decisions.

This is interesting to me because I do that with ADRs, and would love to create more reliable controls against code that violates them. Verity is promising about that, and should also track token efficiency and a bunch of process metrics that I am interested in improving over time.

✅ Validation — with CircleCI

A few months ago I made a change in how I run our test suite, creating local hooks with Husky so that AI agents can immediately see if controls fail, instead of waiting for the remote CI.

This was very effective at improving the agents’ work, at the expense of completely hogging my machine every time. Some parts of the test suite are particularly heavy (e.g. playwright), and running them in local means the whole thing takes time — about 15 mins — and parallelizing things is out of question, because resources are not enough. It’s tricky to run even just 2 worktrees at the same time: things sometimes literally crash.

I talked with Rob Zuber from CircleCI about this, and they implemented a great solution: local hooks that are run remotely, in what they call Chunk Sidecars.

Sidecars are preconfigured environments that run alongside your local workflow, and validate changes as they happen.

This allows to 1) free up your machine resources, and 2) make things faster by introducing real concurrency.

This way I have been able to reduce the suite run time from 15 to 4 mins, while also being able to spawn more worktrees safely. A massive win!

📖 Fetching knowledge — with Unblocked

Unblocked is a context engine: it takes information from several sources (e.g. Github, Notion, Slack, Datadog, ...) so you can ask questions about it.

I have known Dennis, Claire, and the team at Unblocked for a long time, but didn’t think of using it for Tolaria until just recently, because I thought that Unblocked would shine when you have many information sources, and we legitimately don’t have many.

I was wrong.

I plugged it about one month ago, connecting it to Github and Sentry. Sentry is useful to triangulate issues, but the Github connection would basically be worth by itself, because it indexes the code, the ADRs, and all the history of changes.

I have been asking questions about how we do this and that and checking side by side with Codex (which instead just greps and fetches things on the go) and the difference in speed and accuracy is just obvious.

Even more importantly, Codex itself uses Unblocked via the MCP to understand past decisions and fetch relevant ADRs.

Big props to the Unblocked guys because this was an easy win and largely plug-and-play!

🔭 What’s next

Now that Tolaria has sustainable funding, I am going to invest even more on it. Again, I am exploring hiring a strong product engineer, so if you think you can be a good fit, feel free to reach out and say hi!

As for future work, the most important thing ahead is the mobile version.

I already have a working prototype for iPad, but there are still a lot of rough edges. Also, the iPad version is the easy part: for smartphones we need to completely reinvent the UI — I have been working on it 💪

And that’s it for today! I wish you a great week

Sincerely 👋
Luca

1) 🧭 Organize information based on action

Most knowledge bases slowly become piles of uninteresting information. After a while everything starts looking the same: meeting notes, ideas, projects, living side by side and you don’t know exactly how and why.

I believe when you store a new piece of information, there are two questions you need to ask yourself:

• What is this?

• What is this useful for?

The second question is often overlooked, and it’s a core idea behind Portent, which I published last month.

Portent includes default types — which answer the question “what is this” — but also a set of default relationships (belongs to, related to, etc) to help you figure out how to connect notes together, based on what they should help you with.

So, a meeting may belong to a project, a procedure may belong to a responsibility, a resource may be related to a topic, and so on.

Connecting notes together is hard work, but it’s paramount work! Otherwise you easily get stuck: you optimize too much for memory, and not enough for motion.

The goal is to know what to do next, rather than remember more stuff.

You can find the full article below:

Refactoring

Introducing Portent ☘️

Today it’s almost one month since I released Tolaria, and during this time I have spoken with many people and teams that are trying to use it to create and manage internal knowledge bases…

Read more

a month ago · 63 likes · 7 comments · Luca Rossi

2) 📊 Treat code health as a data product

Code quality conversations are often extremely vague.

Everyone wants cleaner code, fewer bugs, easier changes, but unless these things become visible and measurable, they remain mostly opinions.

One thing that I liked in my conversation with Stuart Caborn is that Loveholidays treated code health like a data product.

They collected signals, put them on dashboards, trended them over time, compared teams, and checked whether the numbers matched how engineers felt in sentiment surveys.

The AI angle makes this even more important. If code health data is available through tools and MCP servers, humans and agents can ask questions directly:

• How is my team doing compared with yesterday?

• Are there any areas that got worse this week?

• Where should an agent be more careful?

At that point code health becomes a feedback system that informs your dev process, and it’s exactly the kind of feedback AI needs. The better the codebase, the easier for agents to understand it, change it, and spend fewer tokens doing so.

You can find the full interview with Stuart here 👇

3) 📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 Earn Your Scepticism

10 min • by James Stanier

James makes a distinction I like a lot: scepticism as a conclusion vs scepticism as an identity. The useful version comes from actually using the tools, staying specific about what fails, and keeping your mind open as the evidence changes. This applies just as much to AI enthusiasts as to sceptics.

🥈 Expertise in the Age of AI

5 min • by Brian Kihoon Lee

Brian uses calculators as the analogy for coding agents: the tool removes a lot of mechanical work, but makes the underlying intuition even more valuable. I do not agree with every prediction in here, but the core point is sharp: skipping the struggle may leave you unable to judge the output.

🥉 Find a New Role - Worksheet

4 min • by Lara Hogan

Lara turns career decisions into four simple lists: must-haves, nice-to-haves, don’t-cares, and what you are optimizing for. This is practical and useful, especially when titles, prestige, and compensation make a role look more appealing than it really is.

Quick heads up! Joel and Melinda, coaches in residence at Refactoring, are part of a group offering full coaching scholarships to 29 engineering leaders from underrepresented groups in tech. Applications are open until the end of the day on 30th June.

Learn more and apply here

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Today’s episode is brought to you by:

Unblocked is the context layer for modern engineering teams. Get a free three-week trial at getunblocked.com/refactoring

Today’s guest is Michael Lopp, better known as Rands, who is writer of several popular books about engineering management, including “Managing Humans”, which is a personal favorite of mine.

Live at LDX3, we discussed his lifelong writing habit, the importance of giving feedback through stories and the leverage of leadership experience in the AI era.

Quick heads up! Joel and Melinda, coaches in residence at Refactoring, are part of a group offering full coaching scholarships to 29 engineering leaders from underrepresented groups in tech. Applications are open until the end of the day on 30th June.

Learn more and apply here

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

1. ✍️ Writing as a lifelong habit

2. 🏷️ The power of naming things

3. 💬 Stories as a feedback tool

4. 🤖 AI and the return of the coding manager

5. 📖 Managing Humans, Managing Robots

Let’s dive in 👇

Read more

To figure out what’s really happening in software engineering, I usually do three things:

1. I try things myself — recently by working on Tolaria.

2. I speak with people who know better — on the podcast and in the community.

3. I go through relevant research — to go big picture and get a grasp of the state of the industry.

Good research is hard to find, but a few weeks ago I was sent a copy of this report by the guys at Faros (thank you for that 🙏), which was very interesting for two reasons:

• Quantitatively — it’s one of the largest reports I have ever seen about AI coding: it surveyed 22K+ developers across 4K+ teams.

• Qualitatively — it’s very thorough. It doesn’t stop at measuring activity, but tries to understand the downstream impact of AI on all the stages of the SDLC.

It also paints an interesting trajectory when compared with other similar works from the past months, like the State of Software Delivery, which we covered just recently, and DORA’s State of AI Assisted Development from the end of last year.

So today I will report and comment on the main findings, trying to interpret them and connect the dots with the other things I have been observing lately.

Here is the agenda, with my main takeaways:

1. 🏁 Finishing work is hard — starting is now easy, and shipping is hard.

2. 🔍 Reviews are utterly broken — it’s now obvious that we need to do something about them.

3. 🔥 Poor quality is reaching prod (anyway) — production is suffering, big time.

4. 🪴 The way forward — some words of hope to close this on a high note!

Let’s dive in!

I want to thank the guys at Faros for giving me preview access to these results and partnering on this. If you want to download the full report, you can find it below 👇

Check out the full report

🏁 Finishing work is hard

Before we get to the first idea, there is an important preamble to be made.

We have said many times that AI is an amplifier, and that the *average* numbers of these reports don’t say a lot because they mix up the good teams that are getting a lot out of AI, with the average/bad ones that are not getting anything, or sometimes even negative results.

Now, Faros literally opens the report by saying that no — this is not the case anymore:

Across every downstream stage, the signal is the same: volume is up, quality is down, and the gap between the two is widening as adoption deepens. High-performing teams are experiencing the same downstream degradation as the median and average ones.

Words of hope! But what does it mean that volume is up and quality is down?

If we look at software dev as a pipeline, this means three things:

1. More work gets started, but

2. The amount of work that gets shipped is pretty much the same, and

3. The quality of such work is noticeably lower

Let’s go through all of this, starting with the most important point to me: starting work is now easier, but finishing it is harder than ever.

In particular, developers do more work indeed, by virtue of working on more things at the same time:

• +67% PRs touched / day

• +18% separate tasks

• +33% tasks completed, as measured by opening a final PR about them.

The problem is that such work doesn’t get to production just as fast. In fact, teams are noticeably slower at the last mile — shipping:

• +26% in-progress tasks stalled for 7+ days

• +14% work restarts per developer (tasks returning in progress after moving to another stage)

• -12% deployments per week

Qualitatively this is the same trend that both the State of Software Delivery and the latest DORA report found, but quantitatively worse. In fact, the numbers about coding activity and those about deployment frequency are respectively better and worse than previous reports, pointing at even more polarization.

One of the most visible results of this trend is lead time skyrocketing to a +480%, fueled by an avg +80% waiting time between each of the pipeline steps.

This is not surprising if we remember that:

So if WIP grows and throughput stays the same, lead time is bound to grow. But why does the throughput stay the same? Where’s the bottleneck?

Enter the elephant in the room: code reviews 👇

🔍 Reviews are completely broken

Read more

🎟️ Discover 8 levels of context maturity in AI engineering

This edition is brought to you by our friends at Unblocked!

AI shows up in 60% of engineering work. But only about 20% of it can be handed off without someone babysitting the output. That’s because agents are missing context.

This 8-stage context maturity model gives a real answer on why you haven’t seen meaningful productivity gains for all the tokens burned.

Join live June 24 (FREE) to learn:

• Why more MCPs provides agents access but not understanding

• What it takes to deploy agents you can trust without supervision

• How a context layer solves for quality, efficiency and cost

Learn more and register

1) 🔍 Is validation really the new bottleneck?!

So are the pundits (like myself) right? Is validation the new bottleneck? I think it depends, but for Tolaria I surely spend a lot of time on it.

Every task that gets completed by the AI is shipped in a new alpha version and moved to the “in review” section, where I review it against my production vault.

Here, a few things may happen:

• It’s good — I move the task to “to release”

• It’s ~90% good — I do the final tweaks from my MacBook’s Codex

• Needs work, but it’s still good progress — this is the trickiest to decide. If it’s incomplete but still useful, I have a bias towards progress and I release it anyway, creating a separate task for the improvements.

• Wrong or not usable — this is where the task is sent “to rework”, with a QA comment about what needs to be fixed.

I do a big batch of reviews first thing in the morning, for tasks that were done overnight, and then usually again after lunch, and before dinner, where I also try to make sure the AI has enough to do for the night.

So today validation feels like the biggest bottleneck indeed, also because I believe the right course of action most of the time is to keep specs light and let the AI figure out stuff by itself.

For most features, even when the first pass is not exactly how I wanted it, there is an argument to be made that if it’s good progress it should be released anyway, and have users chip in and give feedback. This has worked well many times, and evolved the product in the right direction faster than if I had waited for a perfect first version.

Of course nothing of this is exactly new thinking (MVPs, etc), but I think what’s changing here is the magnitude. I find that the right course of action is constantly to release a bit more control than what I am comfortable with, and this boundary keeps moving.

I wrote more about this in the full piece on how I run Tolaria as a open source project 👇

Refactoring

How I Run the Tolaria Project

Hey, Luca here! As you probably know by now, two weeks ago I launched Tolaria, a desktop app for Mac, Linux, and Windows, to manage markdown knowledge bases — for humans and AI…

Read more

2 months ago · 50 likes · 2 comments · Luca Rossi

2) 🌍 Async vs sync comms at Todoist

Remote work debates often get stuck in a binary: async good, meetings bad, or the reverse.

What I liked in my conversation with Gonçalo Silva, CTO of Doist, is that their view is much more practical. Doist has been remote-first for more than a decade, long before the COVID era, and they have learned that async-first does not mean async-only.

Async is fantastic when people need focus, when the topic is well-bounded, and when a thoughtful written update is enough. Doist replaced a lot of status rituals with async threads: people write updates when it works best for them, and others consume them on their own schedule.

But some conversations are simply bad async candidates. Gonçalo’s heuristic is to look at the number of iterations you expect:

“If you’re disagreeing with somebody and you feel like you’re not quickly advancing towards convergence, that is probably a great prompt to just hop into a meeting. We settled a conversation that had been going on for multiple days in a call in 14 minutes.”

If the topic starts from a blank canvas, involves disagreement, needs multiple rounds of back-and-forth, synchronous chats are the faster tool, and should not be seen as a failure of async culture.

You can find the full interview with Gonçalo here 👇

3) 📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 AI Demands More Engineering Discipline. Not Less

12 min • by Charity Majors

When Charity writes, we listen. The real product of a software team is shared understanding, and AI-generated code makes that easier to destroy at scale. For this reason, discipline now matters more, not less.

🥈 Revised Rules of Engineering Leadership

8 min • by Will Larson

Will’s piece is a great attempt at updating classic engineering leadership rules and ideas for the agent era. A lot of great takes about migrations, domain expertise, harnesses, and more. Including practical examples!

🥉 Humans and Agents in Software Engineering Loops

7 min • by Kief Morris

This connects nicely with the loop-engineering conversation: humans should not micromanage every generated line of code, but design and improve the loop that lets agents build, test, and learn. Great article hosted on Martin Fowler’s blog.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Last week, Claude Code’s Boris Cherny got trending on X for saying this at the annual Anthropic conference:

I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops. And this is transition we’re going to see for the rest of the year

So, “my job is to write loops.”

Peter Steinberger (creator of OpenClaw) and several others picked up on it and agreed 👇

But before you roll your eyes and think here it goes another fad, new buzzwords, loop engineering, and so on, I’ll go out and say that I like this direction.

Loop engineering looks strictly better than prompt engineering because it forces you into systems thinking, as opposed to just focusing on what’s needed to deliver the current task. A loop is supposed to run indefinitely, so the focus shifts to reliability, sustainability, and how to make sure things stay good — vs diverge and go to shit.

But how do you ensure that?

I wrote about this several times lately, including last week, where I covered how I steer AI work with the 3Gs: guides, gates, and guards. These are not super new concepts: they build on what other smart people are doing, and they are my attempt to contribute to this global conversation.

But a problem I find in this conversation (which I am guilty of) is that it largely focuses on the tech side of things, while treating other disciplines as second-class citizens.

Namely, product.

When you hear people saying that software dev is now a factory, and the bottleneck is your product taste, review, validation, etc, what they are implying is that they have no idea about how to scale those things. In the AI race, product is behind engineering — big time!

The last time we discussed this on Refactoring has been when we published The State of Product Development, where we saw that only 9% of teams used AI to help product with specs (yay), vs 90%+ for coding. Since then I released Tolaria, started doing a lot of product dev myself, and tried a lot of different solutions and workflows to scale myself properly, both in tech and product.

So today I want to focus on product, taking pages from what works for coding, and exploring how we can make the same progress there.

To discuss this, I am also bringing in again Doug Peete from Atono, who has a privileged vantage point by working with thousands of product teams, and is working actively to fix this. We also talked a lot about AI & product in our recent podcast interview.

So here is the agenda:

• ⚔️ Product is harder than coding — an uncomfortable take we need to come to terms with.

• 📋 Towards Product ADRs — building on a successful tech practice.

• 📖 Glossary — a possible missing abstraction in how we develop product.

• 🔄 Product process — how to put everything together and work better with AI.

Let’s dive in!

Disclaimer: I am a fan of what Atono is building and I am grateful to have it as a partner on this piece. You should check it out!

Learn more about Atono

However, I will only write my unbiased opinion about the practices and tools covered, Atono included.

⚔️ Why product is harder than coding

Product is harder than coding, at least conceptually. I know this take will get many engineers angry, but think about it. For a product choice to be good, there is a lot to be taken into account:

• 🔭 Strategy — do customers want this? Do the right customers want this? How is this discoverable? Is this making things unnecessarily complex? How does it fit our business strategy?

• 🔬 Tactics — where do we put this? what’s the right UX? does it need a shortcut? should this live in the right-click menu? ...

A lot of these choices depend on aspects that we are not good at codifying into hard rules. It’s what we call judgment and taste.

Software engineering, on the other hand, is structurally easier, for two reasons:

• It’s downstream of product direction, so it has a narrower design space.

• Its deterministic nature allows it to be tested for correctness and non-functional qualities (performance, cohesion/coupling, complexity) in a more reliable way than product.

As a result, gates for coding agents are effective at enforcing good code, even when they have relatively little context about product. Static analysis, TDD, code health tooling, are all devices that help AI agents write good enough code—granted, not the code that the most talented engineer on earth would write—but still passable for many situations.

So how do we make product a bit more like coding? To answer this question, I will take a page from the least deterministic part of my coding harness: ADRs.

🏗️ ADRs

As I have written many times, I instruct the AI to create ADRs to store meaningful tech decisions. Each ADR has to include why that decision was made, what options were considered (and eventually discarded), and take care of superseding old ADRs about the same thing.

ADRs have been, so far, surprisingly successful. As I am writing this, Tolaria has 137 ADRs, and I see the AI using them all the time. It refers to them in specs, makes decisions that stay true to what exists, and reliably supersedes what’s not relevant anymore.

So, as of today, for most features I am comfortable not giving a lot of (tech) design input, because I know AI will pick it up from past decisions. I still review new ADRs, but they are 95% good — I do it more for my personal curiosity than because it’s a good use of my time.

The ADR workflow is, interestingly, completely non-deterministic. It’s a way to inject good judgment into the AI not by creating rules, but by repeatedly showing how we have done things in the past.

This is why I am hopeful about doing something similar to product 👇

📋 Towards Product ADRs

If ADRs are for tech work, what’s the equivalent for product? Mimicking ADRs, a Product Decision Record might record:

• 👁️ Intent — what the user needs to accomplish.

• 🎨 Design — how we decided to do it.

• ⚖️ Tradeoffs — alternatives that have been discarded and why.

If we roughly agree on this, the next question would be: what does actually deserve a PDR? To me, it’s any product decision we want to remember in case we meet a similar problem in the future. Anything genuinely new that we changed/added to the product, as opposed to reusing a proven pattern that we already understand well.

E.g. In Tolaria, I wouldn’t want to write a PDR to remember that we added “copy file link” as a right-click action to the current note — because there isn’t any novelty or interesting decision being made there.

Do PDRs map squarely to well-known product artifacts, like PRDs, Epics, or Stories? I don’t know about that either. Those other devices primarily exist to communicate what needs to be done. It’s great when they include more about the why, but it’s not clear to me whether e.g. a full PRD or user story should be stored as-is and work well as a PDR. Maybe!

The other reason why I tend to believe PDRs deserve a life on their own is that relevant decisions are largely independent of the size of the work. There might be a large Epic (e.g. integrating a new AI agent assistant into Tolaria) that doesn’t bring meaningful new product direction, and a small story that instead introduces new a interesting pattern.

Doug is experimenting with PDRs at Atono, calling them design decisions and attaching them directly to the stories they relate to — not as a separate doc for now. This doesn’t resolve the question of where a PDR lives when the decision is bigger than any single story, but looks good on the smaller end of the spectrum: when the decision is scoped to one piece of work, attaching it directly might hold up well in practice.

So, in general, even if there is a lot that we don’t know about their shape, we can agree that it’s valuable to record product decisions, in a similar way to what we do with architecture ones. And if we do, we should also agree that this is not enough 👇

📖 Product Glossary

Other than ADRs, I maintain other tech docs in the Tolaria repo, which are called ARCHITECTURE.md and ABSTRACTIONS.md. Without getting into too much detail, these are recap docs, that summarize the current state of our tech.

These are necessary, like views in a database, to avoid the AI to navigate eventually hundreds of ADRs (between those active and superseded) every time, just to reconstruct what exists. The recap docs give the AI the 10,000ft view, while individual ADRs are used to zoom into specific aspects.

What should this look like for product? Doug believes the right concept here is that of a Glossary.

The Glossary should list your main product abstractions: why they exist, what they are for, and how they are used. It maps your domain language, which in turn is shaped by your product surface.

An example from Tolaria may include concepts like:

• The Sidebar — which gives users ways to filter notes in their workspace

• The Note List — to make users navigate the current selection of notes

• The Breadcrumb Bar — to display the most important actions a user can do over the current note.

But also concepts that don’t map 1:1 to single interface elements, like the Git integration, or the Note organization workflow (capture / organize / archive).

It’s obvious these are not PDR candidates: they are long-lived abstractions that morph over time, and need a description that evolves with them. So, if anything, they are derived from a sum of product decisions.

Doug believes a shared glossary is the cornerstone that enables good AI-assisted stories and PRDs — because now the AI can ground them in your vocabulary, your past choices, and what exists. And he has data to back this up.

By talking with some of the teams we surveyed, which report abysmal low AI adoption for product specs (9%), it turns out a major cause is the amount of rework needed by generic AI specs. Making them good is just too much work, so most PMs keep writing specs manually. Doug and Atono have been testing glossary-backed AI stories internally and with customers, and they are seeing rework dropping from 60% to 20%.

(worth noting that 60% rework, as a baseline, is a ton. What if coding agents got things wrong 6 times out of 10? We would probably give up on them, which is what many PMs do with AI right now)

So the overall goal is to build foundational product knowledge: a map of what things mean in this specific product, which is not the same thing as a list of features.

So let’s say we have all of this in place, what does a new product process look like?

🔄 Product process

Any product work starts with capturing some intent — what the user needs to accomplish, how it maps to the product strategy, how we know this is successful, and so on.

This is 100% human (for now!) and is more about the why than the what.

Our input on the what can progressively shrink the more we help the AI figure out good (draft?) specs that respect the current product surface (glossary + PDRs).

Then, based on the feature, the maturity level of your process, and how greedy vs safe you want it to be, you may either:

• Have the AI do a first pass, so that your judgement is informed by an actual prototype, or

• Stop and tweak the draft spec before the AI goes forward.

Then you review and iterate on implementation as long as needed, and finally ship, possibly including new PDRs and Glossary updates.

Over the next weeks I will try to incorporate some of this into the Tolaria workflow, possibly retrofitting some PDRs and glossary concepts from the past. Will let you know how it works!

And that’s it for today! I wish you a great week

Sincerely 👋
Luca

📊 Engineering leaders don’t have a way to measure AI results

This newsletter is brought to you by our friends at DX!

DX has spent the last year studying what this measurement gap means in practice.

On June 18th at 09:30 PT, Distinguished Scientist Brian Houck and Deputy CTO Justin Reock are presenting their research on agent experience, AI readiness, and what the data says about productivity in an agentic world.

You can register for free below 👇

Register here for free!

1) 🧱 Keep deterministic plumbing outside AI

A lot of AI workflow demos make it look like the agent should own the whole process: understand the goal, decide the steps, call tools, and maybe even schedule the next run.

This is quick (and exciting!) when you are prototyping, but it is arguably a bad default for recurring work.

The boring parts of a workflow—routing, retries, scheduling, validation, etc.—need to be dependable, rather than “smart”. For things that I run regularly (e.g. all Tolaria procedures) I want to know which steps failed, what inputs they saw, whether they retried, and what state was left behind.

So the architecture I like more and more is hybrid:

• Orchestration owns the skeleton — when the workflow runs, what each step consumes and produces, how failures recover, and what humans can inspect.

• AI owns the messy parts — classification, summarization, judgment calls, and human-readable updates.

This does not make AI less important. If anything, it makes it more useful, because it stops wasting tokens and attention on plumbing that traditional software is a better fit for.

So, agents are a fantastic way to discover/prototype a workflow. But once the shape is known, the right move is to extract the stable pieces into code and keep AI where ambiguity actually exists.

I wrote more about this in the full piece on orchestrating AI workflows 👇

Refactoring

How to Orchestrate AI Workflows

Hey, Luca here! Welcome to a weekly essay from Refactoring…

Read more

2 months ago · 55 likes · 1 comment · Luca Rossi

2) 🌐 Open source in the age of AI

Last week Ladybird announced they are stopping accepting public PRs — the latest of a series of projects doing the same.

This made me think of my chat with Chris Lattner, where we discussed the impact of AI on open source.

Chris has spent a huge part of his career building massively successful open source projects — LLVM, Swift, MLIR, Mojo — and is concerned about the current state of things. As it’s now obvious, AI makes it much cheaper to produce contributions, but it does not make reviewing them equally cheaper.

“With AI tools, what’s happening is that a lot of maintainers are getting overrun. The contributor doesn’t have to do nearly as much work, but the reviewer has to do the same — at a bigger scale. I think it’s going to lead to new contributors not getting the attention they deserve.”

This is important because, in open source, patches have always been about mentoring and trust-building. Maintainers invest time in people, people learn the project, and some of them eventually become future stewards.

Chris also connects this to intellectual property. If agents can rewrite proprietary tools, translate GPL code into MIT-looking projects, then copyright and licensing become much harder to reason about. As it’s often the case, legal systems lag behind reality.

But the optimistic version is that this also pushes companies toward openness. If secrecy and proprietary headers become weaker moats, the better strategy is to build strong communities, move fast, and compete on innovation rather than control.

We should decide whether to see the glass half empty or half full!

You can find the full interview with Chris here 👇

3) 📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 Domain Expertise Has Always Been the Real Moat

3 min • by Aaron Brethorst

Short, sharp, and very true: AI makes writing software cheaper, but it does not make knowing what “correct” means any cheaper. The best engineers were always the ones building a model of the domain in their head, as opposed to simply translating tickets into code. That part is still a moat!

🥈 What Happens When the Coding Becomes the Least Interesting Part of the Work

8 min • by Obie Fernandez

I liked this because it frames AI coding less as “the machine writes code” and more as “the machine forces you to make senior thinking explicit.” If you care mostly about typing code, agents are annoying. If you care about judgment, tradeoffs, and intent, they free up the interesting part.

🥉 Changing How We Develop Ladybird

3 min • by Andreas Kling

Ladybird is stopping public pull requests and moving to maintainer-only code changes. The rationale is that, in the AI era, patch size is no longer a good proxy for effort or good faith. Open source maintainers are going to rethink trust, review, and responsibility a lot more than we admit. Thinking about this myself with Tolaria.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Today’s episode is brought to you by:

Unblocked is the context layer for modern engineering teams. Get a free three-week trial at getunblocked.com/refactoring

Today's guest is Lara Hogan, an author, public speaker and coach for managers and leaders across the whole tech industry. And she's had a long career as VP of Engineering at FLY, Kickstarter, Director at Etsy, and more.

With Lara we talked about her journey in tech, which started with a philosophy degree. Then, taking from her work as a coach, we talked more about how successful teams are adopting AI and what you can do to make engineers feel safe about it. And finally, we explored the BICEPS framework and how you can better understand people's needs at work.

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

1. 🎓 From philosophy to engineering leadership

2. 🤖 How the best teams are adopting AI

3. 💡 The AHA meetings: learning together

4. 🧠 The BICEPS framework and feeling safe at work

5. 🧱 Practical steps for managers and engineers

⠀Let’s dive in 👇

Read more

TRM is AI intelligence for public safety — and it’s hiring! 📣

This newsletter is brought to you by our friends at TRM!

TRM models turn petabytes of data into actionable intelligence across the threat landscape: ransomware groups, human trafficking networks, darknet markets, terrorist financing, and more!

Threats don't wait. And neither does the TRM team.

Engineers at TRM work at a scale most never touch: real-time graph traversal, petabyte-scale pipelines, and models that power investigations with real-world impact. If you want your code to catch criminals, this is where you build it 👇

Check open roles

🧮 Map and score devex problems

Most teams have structured ways to work on customer problems — which we call “product” — but do not apply the same rigor to developer experience issues.

Earlier this year I advocated to do a listening tour with your engineers to uncover devex problems. An important part of the tour is not to stop at the uncovering stage: you should map, score, and prioritize issues so you work on the right things.

Mapping means taking stories — situations where bad things happened — group them together into friction points, and map them to steps of your dev process.

You can reuse the story map format for displaying this, but you don’t have to necessarily do it that way. You can use a spreadsheet or anything else.

The outcome might be something that looks like a three-level investigation that includes steps, problems, and stories 👇

After you collect problems, it’s time to score them. To do that, the most useful coordinates I have found are reach and impact:

• Reach — how many engineers are impacted by this

• Impact — how much disruption it causes

If this makes you think of RICE, we are not including:

• Confidence — because it’s often tricky to figure out and I haven’t found it that useful in real life, nor

• Effort — because we are only talking about problems here, not solutions.

Also, I am a fan of using simple scores, like low-medium-high, or 1-5.

After that, you should focus on the one true bottleneck™ — I wrote more about that in the full article 👇

Refactoring

The Listening Tour 📞

For the last month I have been running a program for CTOs and VPs of small to mid-size companies to help them make their engineering teams ship faster…

Read more

5 months ago · 36 likes · 3 comments · Luca Rossi

🪜 Career direction starts with what you want

Career planning starts getting useful when you stop asking only what the ladder says and start asking what you actually want.

Many engineers sleepwalk through their careers by following the next obvious step: promotion, bigger scope, manager track, staff track, better company, higher comp. Those may be good goals, but they are not a substitute for knowing what kind of work makes you thrive.

Last month I interviewed Jean and Cate, two professional career coaches, and they told me they are a fan of asking two simple questions:

• What was a peak moment in your career?

• What does it look like for you to thrive?

They asked them to me and I had to think for a minute or so. These questions are designed to pull attention away from abstract “prestige“ and toward real-world evidence. When did work feel energizing? What kind of contribution mattered? What environment made you stronger?

Also, the answer does not need to become a ten-year plan. In uncertain times, an horizon of a few months may be more useful: try something, observe how it feels, adjust, repeat.

Career direction is built every day from good reflection and experiments.

You can find the full interview with Jean and Cate below 👇

Also on Spotify and Youtube

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 Why Japanese Companies Do So Many Different Things

20 min • by David Oks

This is such an awesome article that goes deep into explaining how (and why) Japanese companies are wildly different from US (and Western in general) ones. So much food for thought from looking at things like lifetime employment, horizontal coordination, diversification, and more. A must read.

🥈 The Slide

5 min • by Rands

Putting this appropriately here after I interviewed Rands at LDX3 just last week, and asked him about stories and this article in particular. When someone keeps ignoring your feedback, don’t lecture harder — slide up next to them with a personal story about the time you struggled with the same thing.

🥉 Making a New Plan

2 min • by Cate Huston

An ever-underrated leadership skill is admitting you’re wrong and making a new plan when new information is available. Also, it’s easy to judge others for not doing that, until you realize we all do it from time to time. Short and sharp, as always in Cate’s style.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Refactoring is read every week by 170,000+ engineers and managers from all over the world!

Hey! When I launched Tolaria I promised I would publish ~monthly updates to my AI coding workflow. The last one was in April, so I am late!

In May I also published how I run Tolaria as a project, but this was more about general orchestration, so I wanted to post an update that is more specific to coding.

I will start by saying that things are going... well.

Tolaria by now has a few thousands daily users, most whom are engineers. These are quite eager to report bugs, submit PRs, and suggest improvements on social media, Github discussions, email, and more — so keeping up with everything is quite a lot of work.

Still, I am happy with where we stand. As I write these, we got:

• 6 open issues — vs 417 closed.

• 14 open PRs — vs 306 closed.

• 1 day — average bug fix time.

• 99.1% crash-free rate — as measured by Sentry.

• ~28 commits / day — on average.

• 2 hours a day — I work on Tolaria, give or take.

I released Tolaria on April 22nd, so all of this happened in little more than a month, which is crazy when you think about it. From the day of the release, I added about ~1000 commits, and the codebase has grown a bit, but not massively: right now it’s 150K LOC, plus ~100K LOC of tests.

Most importantly, I don’t feel my velocity has decreased.

If anything, I am probably producing more output per unit of input than two months ago, so the effectiveness feels higher. Code quality also is higher, we are not drowning in regressions, and the rate at which bugs are reported feels stable.

So today I will cover the tweaks I made to my AI coding over the last ~2 months. To catch up with the full process, you can also go back to the previous articles here:

Here is the agenda for today:

1. 🚥 Guides, Gates, and Guards — my mental model for the various types of AI instructions. The core of the article.

2. 🤖 From Claude to Codex — I moved to Codex and (for now) I am not going back.

3. 💸 How much I am spending — monthly cost is now down >90%

4. 🔭 What’s next / missing — what I am trying to improve right now

Let’s dive in!

🚥 Guides, Gates and Guards

When it comes to the dev process, I think about the types of inputs that I can give to AI in three steps:

1. ↪️ Guides — rules and explainers of how to do things.

2. 🔄 Gates — deterministic checks that block bad things and force the AI to steer its output.

3. ↩️ Guards — fallback procedures to improve what falls through the cracks.

These steps are also somewhat sequential:

• Guides are the basic context that the AI uses to start the work

• Gates get into play to steer the work while it’s in progress

• Guards are the last line of defense against enshittification.

Let’s look at all of them:

1) Guides ↪️

We can as well call them rules, but then we’d lose the 3G’s memorability!

These days you write guides for AI agents in two main ways:

• AGENTS.md / CLAUDE.md — the core instructions that the agent always loads.

• Skills — specific instructions to do particular tasks. A skill gets used only when the task requires it.

It’s worth noting that the boundaries between the two surfaces are not very clear. It’s often dubious whether you should create a separate skill or just slam everything into the AGENTS.md, and even benchmarks are inconclusive about the effectiveness of the various strategies.

I believe that’s because, at their core, they are the same thing: instructions to the agent.

My dev process is simple enough that I can afford to keep everything into the AGENTS.md, and not use any specific skill. I have tried a few and never felt things got noticeably better, so I opted for keeping things simple.

You can inspect the actual file — it’s not perfect, mind you, but gives you a more precise idea.

In my AGENTS.md, the most important instructions are about:

• TDD — the agents has to write tests first and do the classic red → green → refactor.

• Boy scout rule — leave the code in a better shape than you found it. It should also measure the before/after quantitatively with CodeScene and Codacy.

• UI — always use shadcn/ui components when possible, and inspect our design language before implementing new UI (we got basic tokens for colors, typography, spacing, etc).

• Localization — extract and translate all the new strings in the supported languages. I use the Lara CLI for this.

Read more

📋 Unblocked is the context layer for modern teams

This newsletter is brought to you by our friends at Unblocked!

Agents can generate code, but getting it right for your system, team conventions, and past decisions is the hard part. MCPs give agents access to information but not understanding – so you end up wasting time and tokens in correction loops.

For this reason, the teams pulling ahead use a context layer to give agents exactly what they need.

Unblocked is the context layer that turns code, docs, tickets, and conversations into actionable context, so engineers move faster and agents stay on track 👇

Learn more about Unblocked

1) 📈 Measure AI effectiveness by leverage

There are a lot of *bad* ways to measure how well your team uses AI, including counting lines of code, tokens spent, and more!

To me, we should measure effectiveness, which is a function of leverage: how much useful output you get per unit of human input.

This is different from measuring AI usage. E.g. a team can maximize AI-generated code by writing incredibly detailed specs that are basically pseudo-code. The AI may write the final syntax, but the human still did most of the hard work.

That is not real leverage!

So a better question is: how much context does a human need to provide before the AI can do the job well? Some of the prompt will always be task-specific. If you ask for a new button, the AI needs to know where the button goes and what it should do. But a lot of the prompt should not have to be repeated every time: design rules, product conventions, architecture patterns, testing style, existing components, release constraints.

So you can think at a scale that goes like this:

1. 🏜️ Negative leverage — people spend more time fighting the AI than doing the work themselves.

2. 🌱 Low leverage — the AI writes code, but only after humans write exhaustive instructions.

3. 🪴 High leverage — the AI can reuse enough context from the system that prompts become short and results stay good.

4. 🌳 Maximum leverage — the AI one-shots meaningful work from tiny prompts because the factory already knows how good work should be done.

I wrote more about this in the recent article series about the new software factory 👇

Refactoring

How to Grow your Software Factory

Last month I published The Era of the Software Factory, where I commented on the latest State of Software Delivery together with Rob Zuber, a good friend and CTO of CircleCI…

Read more

3 months ago · 34 likes · 2 comments · Luca Rossi

2) ⬆️ Bottom line up front

One of the most popular articles we published on Refactoring last year is from Anna Shipman, CTO at Kooth and one of my favorite authors.

She described the translation layer that is needed to make engineering understood by executives, and the article is packed with great examples and mental models.

One of the pieces of advice that stuck with me is to always lead your communication (spoken or written) with an executive summary that includes the most important information: what action you are looking for.

Or, as Anna calls it: bottom line up front.

An exec summary tells the reader in a few short sentences what this document is going to cover. If this is a presentation rather than a document, include an executive summary slide. If this is a conversation, set it up right by explaining first what the purpose of the conversation is. If you are asking for a decision, make sure you’ve included what the decision is.

Here are some example exec summaries.

For a document:

This proposal recommends consolidating our infrastructure onto a single cloud provider to reduce operating costs by 20% over three years, improve reliability, and accelerate feature delivery. The alternative is to retain our split between AWS and Azure. The work will reduce capacity of the platform team by 50% for six months, delaying completion of the work on pipelines until Q4 2026.

We request an additional budget of £50k for the engineering team to have access to an AI coding assistance tool. We have demonstrated in our trial that use of Cursor increases throughput of work by 25% meaning over a year we would deliver extra features equivalent to the salary of four additional engineers, therefore this would pay for itself by end Q1 next year.

In a conversation you might say:

“I want to propose we start upgrading our data handling now rather than in Q3 as planned because our latest planning session raised a flag that we may not hit the deadline. We’d have to pause the work on the new dashboards to do that.”

“There’s a strong business case for investing more in developer experience in next year’s budget. I can show you the ROI calculation we’ve done, but I would like your take before we move forward with the budget preparation.”

You can find the full article by Anna here:

Refactoring

The Engineer → Executive Translation Layer 🔀

Hey, Luca here! Today we are hosting a fantastic new article by Anna Shipman, CTO at Kooth…

Read more

8 months ago · 29 likes · Luca Rossi and Anna Shipman

3) 📣 What makes for a great talk

By the time you read this newsletter I’ll probably be in London to attend LDX3. This year I will interview the one and only Rands on stage, for a live episode of the Refactoring podcast.

So, while preparing for this, I thought about my interview with Meri Williams last year. Meri is the long-time host of LeadDev conferences, and every year they have to run through hundreds of talk submissions to select only a handful of truly great ones.

I asked them what makes for an amazing talk, and they said it’s three things:

1. 📖 Personal story — or a case study. Anyway, a real experience that grounds the content.

2. 🧠 Framework — the author abstracted their experience into a theory that can be applied broadly.

3. ⚡ Practical application — the story + framework combination has clear takeaways that the audience can implement.

You can find the full interview with Meri here:

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Today’s episode is brought to you by:

Unblocked is the context layer for modern engineering teams. Get a free three-week trial at getunblocked.com/refactoring

Today's guest is James Stanier, CTO at Nordhealth, former director at Shopify, an author of several books about engineering management, remote work, and more.

With James, we talked about what senior engineers will look like in the future, taking from a great article he wrote just recently, and then regarding how engineering management is changing, what's expected of managers today, and what you need to thrive.
We also talked about AI adoption in his team, in our personal lives, and discussed the state of remote work in 2026.

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

1. 🔮 The senior engineer of 2035

2. 🧑‍💼 How engineering management is changing

3. 🤖 AI adoption: from chaos to creativity

4. 🏠 The state of remote work in 2026

⠀Let’s dive in 👇

Read more

Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Refactoring is read every week by 170,000+ engineers and managers from all over the world!

Two weeks ago we came together in the Refactoring Community for our very first monthly AI Club session!

More than 30 people joined, and 5 volunteered to share recent learnings about using AI at work. Then everyone got the opportunity to ask questions and build on their ideas.

In this edition I will post a recap of the awesome ideas that were shared!

1. 🚜 The “combine harvester” pattern for long AI tasks

2. 🌙 Overnight procedures that catch what rules can’t enforce

3. 📓 A daily rhythm for noticing what we’re learning

4. 🎫 Using AI to make sense of messy stakeholder tickets

5. 🔀 Staged automation of a complex upstream merge

Let’s dive in!

The AI Club is run monthly and facilitated by professional coaches. It is exclusive for paid members of Refactoring, who get access to our private community.

Get the full version of Refactoring to join the next AI Club, on Jun 5th!

Subscribe now

1) 🚜 The combine harvester pattern for long AI tasks

Matej Vitasek, CTO, shared how he has been successful at having agents run through long, multi-hour tasks, by having them maintain their state in a markdown file that gets updated as the task goes on.

The markdown file holds:

• The instructions

• The progress so far

• What should happen next

As the task evolves, the file evolves too. You can also make the agent stop after a batch of work, reflect on what could have been done better, and update the process before continuing.

The benefit, as Matej described it, is that the work doesn’t have to happen in one sitting.

Anyone can pick the task back up at a later time and the agent can resume from the markdown file rather than starting over or losing context. For tasks that are too big to fit in a single session — or that you want to step away from and come back to — the markdown becomes a simple working memory.

It’s a small, low-tech pattern, but it works and it’s portable across multiple models and agents.

2) 🌙 Overnight procedures to catch what rules can’t enforce

I personally shared something that is working well for me and I don’t see talked about often: running daily, often overnight, procedures that look back at what happened during the day and try to catch judgment-based things that wouldn’t have been picked up by rules in the moment.

I call these guards.

My starting point is—I believe—the same as everyone: I write rules in the AGENTS.md / CLAUDE.md file, and try to enforce some things via CI and hooks: test coverage, static analysis, code health, and so on.

But there are things that are hard to gate:

• Did this change need an architecture decision record?

• Has an opportunity to refactor been missed?

• Is performance drifting over time?

These are judgment calls, and agents will sometimes ignore rules about them, or simply make mistakes.

So I have set up various procedures that run once a day, each focused on a specific concern. Like, in the cases above:

Read more

🔀 Open-source workflow orchestration

This newsletter is brought to you by our friends at Kestra!

Last week I published this primer about workflow orchestration, together with the team at Kestra, which builds a great open source platform to scale AI agents into more deterministic and observable workflows.

I have been playing with it to replace some of my OpenClaw chaos cron jobs, and I am pretty happy with the result so far! Will probably write more about it in the future.

You can learn more about Kestra below 👇

Learn more about Kestra

💡 ADRs are the reviewable artifacts of AI coding

Last month I wrote that the most recent and most valuable addition to my AI coding workflow have been ADRs.

Since then, I realized they are especially valuable because they help turn design judgment into reviewable artifacts. What does it mean?!

I don’t want to inspect every line of code an agent writes, but I can definitely review a short decision record that explains the chosen approach, alternatives, consequences, and what would trigger reconsideration. This gives me a way better control point than reviewing code details in isolation.

ADRs also improve future agent work. Before making a structural choice, the agent can read past decisions, reuse the system’s current principles, and avoid debates that were already settled.

I especially like that ADRs are immutable. When a decision changes, the agent creates a new record that supersedes the old one, instead of rewriting history.

As of today, Tolaria has 120+ ADRs. Are they perfect? Not at all — but they don’t have to be. They are good enough to 1) make me understand key design choices, and 2) steer agent behavior to make it compliant with what exists.

You can find the full article below:

Refactoring

Updates to my AI Coding Workflow

About a month ago I wrote an article about my AI coding workflow, and it instantly became the most popular Refactoring article of all time…

Read more

3 months ago · 55 likes · 6 comments · Luca Rossi

🎙️ Use AI by default to learn its failure modes

Speaking of AI coding, last month I interviewed Stuart Caborn, Distinguished Engineer at loveholidays, and one of the few tech leaders I know that is really doing it at scale, documenting the process.

One of the things he told me is that teams do not learn how AI works by waiting for perfect use cases.

They learn by using it by default, even in moments where typing the code directly would be faster. This sounds inefficient locally, but the point is building the feedback loop, rather than optimizing the single task.

Stuart explains that every failed AI attempt teaches the team something: which instructions are missing, which docs are unclear, which conventions are invisible, where the agent needs guardrails, and so on.

Stuart cares about making failures public, instead of private, and for this, he creates pressure for the failures to surface. The team runs showcases, shares patterns, and even forces engineers to go through AI before asking for human support 👇

“At one of the platform showcases, the core engineering team said: we’re not going to support you if you have a problem with your Terraform, if you haven’t asked Claude to do it first. That was bold — but the reasoning was: we need the feedback now.”

You can find the full interview here:

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 Sensors for Coding Agents

15 min • by Birgitta Böckeler

Great primer on using sensors — like ESLint rules and static analysis — as feedback loops for coding agents. The idea is that agents need guardrails to maintain code quality, and these automated checks act as their “senses” on the path to production.

🥈 Apple Silicon Costs more than OpenRouter

5 min • by William Angel

Yet another reminder that, for 99% of us, running LLMs locally makes absolutely zero sense. This time backed by numbers.

🥉 Not So Locked In

2 min • by Simon Willison

Programming languages used to be lock-in — they’re increasingly not. LLMs are making it feasible to port entire codebases across languages and frameworks, which changes how you think about tech choices, risks you can take, and more.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

During these chats, the most recurring questions I receive are not about the tool itself, but about how to organize information.

People understand the tool: types, relationships, views, etc — but are not sure about what types to create, how to connect them together, and what the regular maintenance of all of this looks like.

To help with this, today I am introducing Portent — an open spec for organizing knowledge bases, for work and life.

Portent provides strong defaults for the three key aspects of a knowledge base:

• Structures — how information is organized into different buckets, whether it’s types, folders, or else.

• Relationships — how such structures are connected and related to one another.

• Lifecycle — how information flows and is operated.

Portent was built with a few goals in mind:

• Convention over configuration — Portent is like the Rails of knowledge bases. Gives you sane defaults, but keeps you free to extend / change whatever you like.

• Usable with any tool — while Portent concepts are first-class citizens in Tolaria, they can be easily implemented in any knowledge mgmt tool.

• Combine life and work — create knowledge bases that blend personal and work data, over the same underlying type system.

• Flexible and extensible — Portent is easy to change and extend, and does not corner users into rigid schemas.

So let’s dive into this. Here is the agenda:

• 📖 Backstory — or why you should trust me on this

• 🍱 Types — the eight main types

• 🔀 Relationships — for knowledge, think graph instead of relational

• 🔄 Lifecycle — capture → organize → archive

• 🔌 Extending Portent — how to add more things, and what you may add.

• 🔨 Tolaria implementation — how to do this in Tolaria. Spoiler: there is a template.

Quick heads up! On June 2nd and 3rd I will be at LDX3 in London, where I will interview the one and only Rands, live on stage.

I love LeadDev conferences and I go every year. If you are thinking of coming, you can use the code LUCA15 to get 15% off the tickets! No affiliation — I don’t get any money from this.

Hope to see many friends there and say hi!

📹 Walkthrough

If you prefer watching instead of reading, here is my walkthrough of the Portent template 👇

📖 Backstory

Portent is the result of many years of work, and, just like with Tolaria, it feels that a lot of what I have done in my life has led to this:

• 2011: PhD — in 2011 I started a PhD to study non-relational databases and how their data models could be mapped one onto another. That started my obsession with organizing information. I later dropped out of my PhD to start a startup 👇

• 2017: Startup — we had one of the very first Notion workspaces in Italy, back in 2017. As CTO I created templates about how to organize work that were later adopted by many others, and personally coached several startups about how to organize work.

• 2020: Building a Second Brain — in 2020 I got in touch with the ideas from Tiago Forte, Sonke Ahrens, all the personal knowledge management literature, and started trying to take the best of it and applying to actual work knowledge.

• 2021: Refactoring — my creator work stressed these ideas to the limit and led to a substantial revision to allow 1) more productivity (write 3 newsletters / week), and 2) blend of personal and work data.

• 2025: AI & Tolaria — as I started working on Tolaria, I further revised how these concepts could be mapped cleanly into Types and Relationships, and optimized for AI collaboration.

So I am very opinionated about all of this, but I am also wary that this is a very personal topic, so any system should be:

• Small — only include what I am 100% sure it’s good, and not more.

• Flexible — to accommodate for personal tweaks and preferences.

The best analogy I can find is that Portent is like Rails for knowledge bases: turnkey if you want to, but infinitely customizable if you want to get your hands dirty.

🍱 Types

Portent recommends organizing data into eight main types:

1. Projects

2. Operations

3. Responsibilities

4. Tasks

5. Events

6. Notes

7. Topics

8. People

The name Portent itself is an acronym for the first seven types. Plus there’s people at the end, so it’s technically PORTENTP — but bear with me!

These types are grouped into two clean categories:

• PORT — the actionable types: Projects, Operations, Responsibilities, Tasks.

• ENT(P) — the non-actionable types: Events, Notes, Topics, People.

PORT organizes things to do, while ENTP organizes inert, non-actionable things.

🔥 PORT

PORT is by far the most important part of Portent. I believe the best way to organize a piece of information is downstream of asking: what should I do with it?

You are going to ask yourself this question all the time, so in order to give good answers, you need a good way to organize things to do. And when I say “things to do” it’s not necessarily work — it’s also personal life. The mental model is the same.

The most useful way I have found to categorize work is to do so along two axes:

• 📏 Size — whether work can be completed in one sitting or not.

• 🔄 Recurrence — whether work is one-and-done, or recurring.

Based on this, we can have four types of work:

Responsibilities

Responsibilities are recurring work that can’t be completed in one sitting.

They are good for modeling long-running areas for which you need to keep a standard.

Responsibilities don’t usually have fixed goals, because they are long-running — they rather have metrics or KPIs that tell you you are going in the right direction.

Examples: “stay in good shape”, or “ensure good product retention”.

Projects

Projects are one-and-done work that can’t be completed in one sitting. They have a beginning and an end, and a clear definition of done.

They can belong to a responsibility. E.g. if your “ensure good product retention” responsibility measures the NPS of your product, a quarter project might be about a beloved feature that people have been asking since forever, that is expected to improve that.

Or if you measure “stay in good shape” with your VO2 max, a quarter project might be to start playing Padel twice a week, and get your VO2 max from X to Y.

Operations

Operations are recurring work that can be completed in one sitting. They are procedures that are repeated always the same way, for which there is ideally a set of instructions.

Operations can belong to Responsibilities and Projects. E.g. in your “stay in good shape” responsibility, you might have an operation that describes your weight-lifting routine.

Or for a Project that is about a new product feature, you might have an Operation for the “Weekly Review” of how the development is going.

Operations are also, as of today, the biggest surface of collaboration with AI agents. Agents deliver a ton of value by owning procedures, that is, performing the same set of actions on a recurring basis.

Tasks

Tasks are one-and-done work that can be completed in one sitting. These are important to be defined this way and to be included in the general framework, but I actually do not encourage storing them in the knowledge base.

I am not completely against it either, but I generally believe tasks are better suited to being managed by a dedicated separate tool. For two reasons:

• Ephemeral — once a task is done, there is no big value in keeping it in the base. Any learning coming from the task should be stored in a separate note anyway.

• Specialized — tasks often require specialized interaction: due dates, status, kanban boards — all things that are better served by dedicated tools.

So yeah, it’s not bad to store tasks in a Portent base per se, but you are probably not going to get a lot out of it either.

🌱 ENTP

ENTP types are for information that doesn’t need action. Litmus test is: if it needs a status, it’s probably a PORT, otherwise, it’s an ENTP.

Let’s look at them one by one:

Topics

Topics are categories that have no expectations of action. They are simply topics of interest, that may or may not be useful in the future.

E.g. I like sim racing, and I often save links with gear or tutorials, but I have no projects or responsibilities about it, so it’s just a topic for me.

Or, at work, I may want to save useful resources about databases, but it’s not like I have a responsibility about that. Could just be useful in the future, so I create notes and set them as related to the databases topic.

Events

Events are things that happen. They are useful for mapping meetings, achievements, and calendar things.

People

People are pretty self-explanatory. You can attach people to pretty much any of the types above, and when done well, it’s like building a CRM.

Notes

Finally, Note is simply the default type. When you create a new item, it’s a Note first — and it stays so in absence of a better type for it.

Now, once you have the types in place, how do you connect them together?

🔀 Relationships

I believe the best way to model information relationships in a knowledge base is via a very small set of graph-style connections.

Portent encourages two in particular:

• Belongs to — strong relationship: owner, composition, usually in a one-to-many fashion.

• Related to — weak relationship: many-to-many, does not demand action.

Based on how you implement these, you can also compute the inverted versions, whose default names in Portent are:

• Belongs to → Has, or Children

• Related to → Referred By

The way you assign these relationships is up to you, but I have found that a good default mental model is:

• Use belongs to for relationships towards or between PORT items — e.g. an Operation belongs to a broader Responsibility, a meeting (Event) or a Note belongs to a Project.

• Use related to for relationships between ENTP items — e.g. an Event is related to a Person, a Note is related to a Topic, and so on.

An important upside of a relationships (and not only type) system, is that relationships stay the same across the whole knowledge base.

To understand why this matters, let’s look at alternative ways to model relationships, via the two most common ways: relational databases (tabular data), and folders (hierarchical data).

1) Relational DBs (tabular data)

In a relational model, like Postgres, or Notion databases, you need to define explicit relationships between each couple of tables you want to connect.

These relationships create a schema that is:

• Big — you end up recreating the same concepts across tables even if they semantically mean the same thing, and

• Rigid — enforced and hard to change once data is in place.

The upside is that data always stays strongly consistent and adherent to the schema.

2) Folders (hierarchical data)

With folders, every item (folder or note) can only belong to one folder. This massively limits the semantics that you can express via folder structures, which basically can only model strong, exclusive ownership relationships.

E.g. if you want meeting notes to sit in a “meeting notes” folder but also be included in the respective project folders, you can’t.

The upside of folders is that they make traversal extremely easy — as long as it’s done along the intended path.

3) Graph relationships

Portent’s take is that the upsides of relational and hierarchical models don’t matter nearly as much as in the past now that we have AI.

In fact:

1. Once most information can be organized by AI agents, consistency can be enforced easily even in the absence of a deterministic way to do it with software.

2. Folder traversal simply doesn’t matter in a world where agents can grep and fetch anything.

If we agree on this, simple default relationships work and scale better than anything else, because they create:

• Less semantic surface — easier to understand for both humans and AI, because it’s the same concepts everywhere.

• Cross-type meaning — easier to work across multiple types (e.g. find all “orphaned” notes == those that have no belongs_to and no related_to)

None of this is exactly new: graph DBs have been doing this since forever — I only argue this is the best way to build knowledge bases, especially now that we have AI.

Next, let’s talk of lifecycle 👇

🔄 Lifecycle

A common problem with knowledge bases is that it’s hard to keep them clean, understandable, and up to date. Portent encourages users to manage notes in three steps: Capture, Organize, and Archive.

These can be implemented as a status property for every note, and are meant to be enforced by your workflow somehow.

More on each:

1) Capture

The capture stage is only meant to make information available. Save that link for later, store those meetings notes, write down that thought in a random note.

Captured notes are not clean nor tidy: they are a mess, and intentionally so. The capture stage is optimized for speed: just capture everything, and then we’ll see.

2) Organize

Once a note is captured, you have to ask yourself two questions about it:

• What is this?

• What should I do with it?

The first question drives type selection, while the second drives what relationships to create for it.

If you can’t attach any Project, Responsibility, Operation, or Topic to a note, then it means you can probably trash it. It’s totally fine to capture things and then realize it was a mistake: capture things optimistically, and organize pessimistically.

I organize my captured notes once a week, and I implemented this workflow directly in Tolaria, where the default section is the “Inbox” (aka not organized) list of notes, and you can flag any note as “organized” with cmd+E.

3) Archive

An underrated part of what makes for a good knowledge base is separating current from obsolete information. The latter can still be useful — think past projects, old meeting notes, etc — but you don’t want them to show up in your regular usage.

You should have a clear way to mark notes as “archived”, so that humans and AI can ignore them by default.

🔌 Extending Portent

These are the basic concepts in Portent, but are not meant to be the only ones that live in your knowledge base.

Once you have understood the basics (organization based on actionability, simple relationships, capture vs organize, etc), it’s easy to extend them and add more concepts.

Common ones in my experience are:

• Calendar types — like years, quarters, and months. These are extremely clear concepts that will not pollute your base, and can be used to anchor and group things like projects, events, and more.

• Teams / areas — it’s useful sometimes to create larger groupings that represent domain or ownership areas, and attach PORT items to those.

• Note types — you may want to “split” the Note type into more ones: videos, resources, articles, etc. I am a fan of doing that with tag properties, instead of “root” Types, but you can do it either way.

• Specialized relationships — once you are sure about your model, it can be great to create a few specific relationships to disambiguate the use of the default ones.

And of course it’s useful to create types that map to the domain language of your use cases. E.g. I write a newsletter and I have types for the Essays I write, Evergreen notes, Podcast interviews, and more.

🔨 Tolaria implementation

Portent can be implemented in any note taking system, but has special support in Tolaria.

I created a Portent template vault here, that you can clone and use in Tolaria.

Tolaria is good for Portent because:

1) Lifecycle management

Capture → Organize → Archive is directly supported in Tolaria:

• The Inbox section shows all notes that haven’t been organized yet

• You can organize a note with cmd+E or the organize button in the editor bar

• You can archive a note with the archive button, and it will hide from the default sections.

2) Types & Relationships

Tolaria is natively organized into Types and Relationships, and it suggests default relationships that are exactly the Portent ones.

3) Multiple vaults

If you want to use the same type system (Portent) for both life and work, you can create separate vaults and mount them together inside Tolaria for you to see, while maintaining separate access control for e.g. your co-workers.

And that’s it for today! As always, let me know your thoughts on all of this!

I wish you a great week

Sincerely 👋
Luca

Every week I also write an article about how to ship good software fast, and interview a world-class tech leader on the podcast.

I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

📋 Unblocked is the context layer for modern teams

This newsletter is brought to you by Unblocked!

Agents can generate code, but getting it right for your system, team conventions, and past decisions is the hard part. MCPs give agents access to information but not understanding – so you end up wasting time and tokens in correction loops.

For this reason, the teams pulling ahead use a context layer to give agents exactly what they need.

Unblocked is the context layer that turns code, docs, tickets, and conversations into actionable context, so engineers move faster and agents stay on track 👇

Book a demo today

🔍 Rate your team on the pyramid of engineering

A couple of months ago I argued there is a new pyramid in software engineering, made up of the areas you should take care of to get your team to their best potential.

These areas are Developer Experience, AI, and Product Engineering, and need to be nurtured exactly in this order.

To understand how you are doing about each of these, here is a short self-assessment you can run on yourself. Rate how much you agree, from 1 to 5:

1) Developer Experience

• 1.1 — It is easy to do work as a developer on my team

• 1.2 — Engineers on my team get enough focus time

• 1.3 — My team ships fast and often

• 1.4 — I have a good strategy to improve the developer experience of my team

2) Artificial Intelligence

• 2.1 — Engineers on my team make good use of AI

• 2.2 — We have a shared understanding of how to use AI as a team

• 2.3 — I have a good strategy to improve the impact of AI on my team

3) Product Engineering

• 3.1 — I am happy with the level of autonomy the engineers on my team work with

• 3.2 — Engineers on my team know what our customers’ problems are

• 3.3 — Engineers on my team know if a feature is successful or not

• 3.4 — I have a good strategy to make the engineers on my team more autonomous over time

You can find the full article below:

Refactoring

The New Pyramid of Software Engineering 🏔️

There are a lot of opinions around these days about the future of software, including of course my own…

Read more

4 months ago · 50 likes · Luca Rossi

🎙️ The business impact of code quality

One of the interviews I keep coming back to is the one I did last year with Adam Tornhill.

Adam is the founder of CodeScene and one of the sharpest thinkers on software quality: he combines behavioral data analysis with code metrics to identify the parts of a codebase that actually hurt you.

The conversation centered on a question most engineering leaders struggle with: how do you make the business case for refactoring?

Adam’s team tackled it head-on with the Code Red study — a large-scale analysis of the correlation between code health and real development performance.

Their findings confirmed what many engineers know by heart:

• ⚡ Development Speed — healthy code enables teams to develop features more than 2x as fast as unhealthy code.

• 📉 Predictability — unhealthy code creates massive variance in task completion times, making estimation extremely hard.

• 💸 Hidden Costs — some tasks in unhealthy code can take up to 10 times longer than expected.

“Doing a task in unhealthy code can actually take up to an order of magnitude longer — 9 times, 10 times longer. And that translates into a bunch of undesirable side effects for the business.”

One finding that stuck with me is also that who makes the change matters enormously. Developers unfamiliar with the codebase take twice as long to work in unhealthy code. This is a hidden onboarding cost that nobody ever budgets for, but that compounds every time a team grows or rotates.

Here is the full interview with Adam 👇

You can also find it on Spotify and Substack

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 Software Engineering May No Longer Be a Lifetime Career

6 min • by Sean Goedecke

Using AI to code means you don’t learn as much about coding itself, but refusing to use it puts you at a disadvantage today. So, is software engineering becoming more like professional sports? That is, a career with a finite window rather than a lifetime of compounding skill accumulation.

🥈 GitLab Act 2

19 min • by Bill Staples

GitLab’s CEO lays out their vision and plan for a major restructuring of the company around agentic AI and the future of software delivery. Interesting both as a product vision and as a case study in leading a public company through a platform shift.

🥉 Thin Harness, Fat Skills

6 min • by Garry Tan

By now we know that AI agents become far more productive by using purpose-built skills. It’s still unclear how all of this scales, but Garry’s mental model about growing skills instead of the general harness is solid, and I agree with him.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

Today’s episode is brought to you by:

Unblocked is the context layer for modern engineering teams. Get a free three-week trial at getunblocked.com/refactoring

Today’s guest is Doug Peete, Chief Product Officer at Atono, with whom over the last few months we have developed a deep industry report about the state of product development.

In this chat we’ll go through the main findings of the report, match them to our respective experience and explore ideas about how teams can do better with product development and AI.

🥇 Interview Summary

If you are a 🔒 paid subscriber 🔒 you will find my own summary of the interview below.

It’s the 5-minute takeaways of what we talked about, with timestamps to the relevant video moments, for those who don’t have time to sit through the 1-hour chat.

Here is the agenda for today:

1. 📋 Why planning is so fragile

2. 📝 The requirements problem

3. 🧠 Knowledge sharing and tribal knowledge

4. 🤖 AI adoption: individual vs. team

5. ✏️ AI for product specs, the untapped opportunity

⠀Let’s dive in 👇

Read more

Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.

Refactoring is read every week by 170,000+ engineers and managers from all over the world 🙏🙇‍♂️

Hey there! Last week’s article about my workflows for Tolaria went incredibly well, and I got a ton of replies and questions via email.

One of the most recurring ones was: what’s next? How would you improve this?

Happy to answer. I have been building AI workflows for a while now, and, for the most part, I have done so in “100% AI mode” — that is, I tell an agent to do something recurringly, in natural language, and they do it.

These workflows are fast to ship and *mostly* work, but also have pretty obvious drawbacks, that I would love to discuss today.

I believe this is relevant because these days we are inundated by stories like: “n8n is dead!”, “it’s all agents calling agents!”, and so on, while reality is more complicated.

I also bounced a lot of ideas off with the team at Kestra, who runs an awesome open source platform for orchestrating workflows. Their help came at the perfect time, and we basically wrote this piece together.

So here is the agenda:

• 🧹 Cleaning up releases — starting from a real-world example.

• ⚖️ AI vs Orchestration — mapping pros and cons of how to run workflows.

• 🏗️ Agents as scaffolding — a useful mental model about going AI first, but gradually replacing it with code.

• 🗺️ Workflow engineering journey — a maturity model for developing your workflows.

Let’s dive in!

Disclaimer: I am thankful to Kestra for partnering on this piece and providing ideas and insights about the orchestration industry. I am a fan of what they build and you should check it out:

Learn more about Kestra

However, as always I will only write my unbiased opinion on the practices and tools covered, Kestra included.

🧹 Cleaning up releases

To stay grounded and make you understand what I mean when I say workflows, let’s take a practical example. Whenever I create a new stable release for Tolaria, I have an automation to take care of the release’s aftermath.

This includes fetching all the bug fixes and feature requests that were shipped in the release, and update/close them in the respective channels, notifying the relevant users.

This is not rocket science by any means, but it involves a number of steps:

1. Fetch Github commits shipped with release

2. Match commits to the associated tasks on Todoist

3. For each task, retrieve the original entry either on Github Issues, or the Canny product board

4. For each Github issue, leave a comment saying this is fixed in the latest release, and close the issue

5. For each Canny item, leave a comment explaining how this was implemented in the latest release, and close the item

6. Finally, create short descriptive release notes to be attached to the release page.

The first version of this was entirely run by AI. No scripts — just a few high-level skills about how to access Github Issues, Canny, and Todoist — and natural language instructions about what needed to happen.

This mostly works. Sure, it is slow and expensive, but that’s forgivable given that I need to run it at most once per day. The problems come when it doesn’t work for any reason.

Say Github issues are not available at that specific time (ofc fantasy example given Github’s immaculate availability lately), or the run times out, or your favorite AI provider rate limits you in that very moment.

At that point the workflow fails, and it typically does so in the worst possible way: 1) silently, 2) leaving things in a dirty state, and 3) without any retry or recovery.

Of course you may build all of these into the procedure somehow, but if you find yourself manually plumbing standard ideas about how we have been running workflows since... forever, you should probably stop and ask yourself if there is a better way.

So let’s take a step back and think through this from first principles.

⚖️ Pure AI vs Orchestration

The tradeoffs between pure AI workflows (e.g. cron jobs on OpenClaw) and orchestration platforms a-la Kestra, resemble a lot those between AI and deterministic software.

AI is incredibly smart, but also incredibly expensive and slow. A lot of work just doesn’t need those smarts. Routing, retries, conditionals, scheduling — there is just a lot of plumbing that can be done in a purely deterministic way, saving time & money.

Also, traditional orchestration doesn’t only win on time and money: it is often a better choice full stop when you account for:

• Observability — you can’t debug pure LLM reasoning, as you can instead with workflow steps that are explicit and isolated. Also you get execution history, stats, and much more.

• Reliability — scheduling, resiliency, recovery from failures. This should be all built-in.

• Scalability — this is probably not a factor on its own, but more the result of all of the above combined. Being able to scale requires reliability, observability, low latency, and so on.

So where do we go from here?

🏗️ Agents as scaffolding

A few weeks ago, Will Larson published an awesome piece about using agents as scaffolding for recurring tasks, which means: a useful first pass to discover what the workflow should be.

Then, once the pattern is known, you should extract and harden as much as you can into deterministic code. So agentic steps are largely used as ‌prototyping tools, not permanent infrastructure.

This doesn’t mean eventually replacing all of the AI, but rather only using AI for the right things. With some degree of simplification:

• Orchestration wins at all-things-infra — observability, reliability, human-in-the-loop approvals, structured output validation, and so on.

• AI wins at the messy stuff — classification, summarization, judgment calls, and all the things you can’t write code for.

I love this take, and I think we can expand it into an actual maturity journey 👇

🗺️ Workflow engineering journey

Based on this, a natural progression may look like this:

1. Agent-first — everything in a loop, fast to prototype, but opaque to debug.

2. Isolate the deterministic parts — pull out the boring steps (fetch, validate, store, etc) into explicit code. Keep AI for judgment calls.

3. Structured orchestration — proper DAG / event-driven layer with retries, lineage, observability. AI becomes one task type among many.

4. AI-driven composability — LLMs generate or modify the workflow definitions themselves. The orchestration layer is stable enough to be a target for code generation.

I am particularly bullish about #4 because, when you think about it, it is a way to get the best of both worlds: you prompt the AI in natural language as you would for normal agentic workflows, but the AI actually turns that into structured, semi-deterministic work.

A quick plug to Kestra on this, which I am a big fan of. Because if you agree with these steps, a natural question becomes: what should an orchestration platform look like to enable AI to operate it? Kestra checks a lot of my boxes:

• Code-first — the AI should be able to write workflows in a declarative fashion, with code, because that’s what it’s best at (as opposed to e.g. GUIs).

• API/CLI first — trigger executions and manage workflows through API

• Open source — these days, considering the speed tech is moving at, I put a lot of value on the tools I use being open source, so we can evolve them faster as a community, in the open, and there is less lock-in.

And that’s it for today! I wish you a great week

Sincerely 👋
Luca

Become an investor in AI infra startups! ✨

Today’s sponsor is Alumni Ventures!

If you ever thought about doing some angel investing in AI products you like, you can do so via our friends at Alumni Ventures, that give you access to high-growth startup opportunities, co-invested alongside top VC firms like Andreessen Horowitz (a16z), Bessemer, & YCombinator.

You can signup for free and get:

• A curated deal flow of high-potential AI infrastructure startups

• Deals in which AV is already investing alongside elite lead venture firms

• No cost to see deals, and no obligation to invest

Join Alumni Ventures AI Infrastructure Syndicate Today →

💡 Never start from a blank page

A lot of people ask me how I take notes and write articles — even more so recently, since I shipped Tolaria.

I have often talked about this in the newsletter. I am quite opinionated about it, and a lot of these opinions made it into Tolaria.

One of these is about the (in)famous blank page.

There is this romantic view of writers sitting in front of a blank page and crafting their work through sheer inspiration. In reality, if you’re starting from nil, you’re doing it wrong.

About this, I love a famous quote from an Italian singer-songwriter, who once was asked how long it takes to write a song. He said:

“It takes me about 10 minutes — but only if I spend the rest of my life making sure that eventually it takes me 10 minutes.”

This applies to all knowledge work. Good writing is about connecting and refining ideas you already captured, rather than creating from scratch. The prep work is the work.

To make prep work easier, I am a big believer in dividing it into multiple steps:

• Capture — store the thought on a durable support.

• Organize — refine it, place it where you’ll need it, and connect it to other thoughts.

• Express — use it to do something larger.

These are different tasks, and are best done at different times. Conflating them leads to predictable failure modes:

• Capture + Organize leads to exhaustion (every note becomes a chore).

• Organize + Express leads to chaos (missed insights, no scalability).

• All three at once leads to writer’s block.

Luhmann’s Zettelkasten and Tiago Forte’s CODE system are both built around this separation. You don’t need to follow either to the letter, but the principle matters.

I wrote a full piece about note taking a while back 👇

Refactoring

How To Take Notes 🌱

Hey there! Last week we had our book club review of How to Take Smart Notes, by Sönke Ahrens…

Read more

a year ago · 53 likes · 3 comments · Luca Rossi

🎙️ Principles for better decisions

One of the interviews I go back to the most often is the one I did last year with Annie Duke.

Annie is a former world-class poker player, author of Thinking in Bets, and one of the clearest thinkers on decision-making.

The conversation was packed with useful frameworks, and one that stuck with me was her four-principle checklist for high-quality decisions:

• Speed assessment — before anything else, decide how much time this decision deserves. Ask: how long-term is the impact, and how reversible is it? Spend time and effort accordingly.

• Make the implicit explicit — we often decide by “feel.” Annie’s view, instead, is to articulate what that gut feeling actually is. What are the real criteria? Making reasoning explicit helps you catch flawed logic before you commit, and makes it harder to rationalize a bad choice after the fact.

• Quantify qualitative opinions — instead of calling a market “great,” rate it. Even in a shallow way, e.g. on a scale from 1 to 10. This forces precision and, in teams, surfaces hidden disagreements otherwise masked by vague language.

• Collect opinions independently — never gather important input in a group setting. Anchoring bias and groupthink are real. Collect individual perspectives first, then compare differences without forcing consensus.

Here is the full interview with Annie:

📚 Weekly Readings

Finally, here are the best articles I have read this week:

🥇 Sometimes Your Job Is to Get in the Way

5 min • by Rands

Good leaders know when to stay out of the way — but great leaders also know when to step in and draw a hard line. Fantastic story by Rands, about how a major Slack outage led to a complete transformation of their development process, driven by strong leadership.

🥈 Why Can’t They Just…

5 min • by Lara Hogan

“Why can’t they just…” is a phrase we all use when frustrated with other teams or roles. Instead of dismissing it, Lara explains how to use it as a signal to dig into the complexities behind decisions you don’t understand, and turn frustration into collaborative problem-solving. Loved it.

🥉 Contributor Poker and AI

6 min • by Loris Cro

Open source maintainers don’t bet on PRs, they bet on contributors. This is a great take by Zig and the best articulated thesis I have heard about banning AI-generated contributions. Worth a read.

And that’s it for today! If you are finding this newsletter valuable, subscribe to the full version!

1700+ engineers and managers have joined already, and they receive our flagship weekly long-form articles about how to ship faster and work better together! Learn more about the benefits of the paid plan here.

Make your team ship faster!

See you next week!
Luca

I did that to solve my own problems and to get my hands dirty with AI coding. In other words, I wanted to walk the talk, and then write about it here on Refactoring.

Little did I know this would feel more like speedrunning the talk.

Tolaria has now several thousand daily users, 10K stars on Github, and last week it was the 10th fastest growing repo… in the world, as measured by Star History.

To put things in context, there are only about ~5K repos in the world with more than 10K stars, out of ~30M.

This is of course, incredibly flattering and energizing, but I also joked with friends that I have been glued to my chair non-stop for these two weeks, because all this interest also posed very real operational problems.

Users, in fact, who are mostly engineers, contributed hard — and I am glad they did! As of today, Tolaria has received:

• 200+ issues on Github

• 150+ PRs

• 150+ feature requests on Canny

So I had to create workflows to help handle all of this: to ensure issues would be fixed fast and people would get feedback about ideas and contributions.

Fast forward to today, I am pretty happy with how it is going, and as I write this, we are down to:

• 15 open issues

• 11 PRs

• 81 feature requests

Today’s newsletter covers all these workflows and how I “survived” these two weeks, while only working part-time on Tolaria, and the rest of the time on Refactoring — in the meantime I also had to publish 4 newsletter editions and 2 podcast episodes.

So here is the agenda:

• 📥 Inputs — mapping and normalizing sources and channels.

• 🗃️ Backlog — turning everything into a single prioritized list from which agents can take work.

• 🔍 Validation — is it the one true bottleneck, as everyone is fond of saying these days?

• 🚀 Release — making work available to everyone and updating all the input sources.

• 📊 Analytics — tracing what happens in production.

Let’s dive in!

📥 Inputs

I have never maintained a sizable open source project before, so you’ll forgive me if some of what I am about to say will sound trivial to you.

At any given time, there are several types of inputs Tolaria receives, that can spawn work to be done:

1. Bug reports from users

2. Feature requests from users

3. PRs from contributors

4. Crash reports from telemetry (Sentry)

5. My own ideas (hello 👋)

These are all separate channels but, with some degree of simplification, they spawn two types of work: bugs and features.

More specifically:

• #1 and #4 spawn bugs

• #2 and #5 spawn features.

• #3 (PRs) can spawn either, but mostly features.

#1, #2, and #3 originally all lived in Github Issues, but bugs and feature requests have different needs and deserve to live in separate places. In fact:

• Bugs — only need to be replicated and squashed as soon as possible. I am a strong believer in a zero-bugs policy: catching bugs as soon as they are reported, and fixing them all ASAP. All in all, there is very little to decide about bugs.

• Feature requests — are another story. They benefit from being voted on (you want to see how many people want something), are generally bigger, so you may want to flag things as planned or in progress so users are notified, need to be specced, and, of course, you don’t want to build those that don’t match your vision. That’s a lot more to decide.

From a workflow standpoint, bugs are easy, features are not — which is why today we are down to only 15 open bugs out of 200, but still 80+ open feature requests out of 150.

The way I manage this is by keeping bugs on Github Issues, and feature requests on a separate product board on Canny.

To make people understand this, I created a rich “contribute” panel inside Tolaria where you are routed to different places based on how you want to help:

Still a lot of things go wrong all the time:

Read more