The Illusion of Shared Understanding

And how to fix it with RFCs

Have you ever returned from vacation to find the project you entrusted to your team completely off track?

I have — and that experience taught me one of the most important lessons of my engineering career. In this article I’ll share why teams often believe they’re aligned when they’re not, and how a simple RFC process can prevent months of wasted work.

This happened years ago when I worked as a lead in a software engineering team.

I had started working on a big, complex feature that was supposed to be ready in two months. However, my vacation was approaching and I would be away for one month.

To stay on schedule I asked two engineers from my team to continue the development. I explained what the feature would be doing and how I planned to implement it. We had a couple of sessions where we went through the target architecture in detail, including drawing diagrams on the whiteboard. Developers said that everything was clear and they would be able to finish it when I was away.

One month later, when I returned from my summer break, the feature was almost ready.

Or so I thought until I looked at the code.

I was shocked to find that the feature was addressing only a small special case. Nothing else worked.

What followed was one of the most dramatic sprints in my career. I worked evenings and weekends, on the plane and on the bus. In the end I missed the deadline anyway, however not by much.

I felt very upset, but I didn’t have anyone else to blame but myself. I failed to recognize that we only had the illusion of shared understanding. We thought we were in agreement when in fact we had totally different mental models of what needed to be done.

Similar situations, maybe not that dramatic, happened many times throughout my career, so I started to see the pattern and look for a solution. I needed a way to make mental models visible — not just assumed. That’s when I stumbled on the idea of internal RFCs.

RFC stands for request for comments. It is a document describing a solution which is shared within a team, organization, or publicly in order to receive feedback.

I knew RFCs before from open-source projects, where they are widely used to facilitate decision-making within the OSS community. However, I never thought of using RFCs internally in an organization.

The RFC approach has several advantages over verbal alignment. First of all, it is more precise. The need to write forces the author to clearly structure their thoughts into a coherent logical narrative. While writing, the author has time to examine their proposed solution from different angles and clearly see pros and cons of it.

Another advantage of the document over verbal explanation is that a well-written RFC leaves little room for misinterpretation. It can include diagrams, examples, or calculations to illustrate and support the idea.

Finally, we can return and reread the RFC later. Human memory is unreliable; already after a day, details that were crystal clear in one’s mind start to get blurry. When these details are written down, it is easy to review them at any time.

Despite these advantages, introducing RFCs can still meet resistance. The most common objection is that writing proposals is “a waste of time” compared to writing code.

A good way to overcome this is to introduce RFCs as a timeboxed experiment.

Try it for a month, then debrief as a team and decide whether the practice is worth continuing. A short experiment lowers the psychological barrier to change.

During that first month, it helps if you write the first few RFCs yourself.

This models the behavior you want to see and keeps the initial bar low. Ask the team to comment — not write — which is a much easier first step for them.

It also helps to bring one or two formal or informal leaders on board early. If people who have influence participate in RFC discussions, others will follow naturally.

Cultural changes die when leaders propose them but don’t participate. If even the champions of the idea don’t write or review RFCs, the team will quickly abandon the practice.

To start RFC adoption you will need a template that your team can start using right away. There are a lot of options on the internet to choose from, or you can use my template, which has been working well for me and my team.

The template I use includes two main parts: header and body.

The header has the following information:

RFC name. It is simply the name of the document in Git or, for example, in Confluence.

Owner. Author of the RFC. If the team is small and the RFC is not shared outside of the team, this field can be skipped.

Date. Creation date. Good to have for bookkeeping and later reference.

Status. One of the following: Work in Progress, In Review, Approved, Obsolete.

Approvers’ names and their approval statuses. The status can be one of three: Not Approved, Approved, Declined.

Below the header is the body of the document. The body consists of two sections.

Background. Explains the business or technical context behind the change — why the proposal exists and what problem it solves.

Proposal. Describes the solution. It can include text, diagrams, examples, images, or any other media that helps convey the idea clearly.

You can find the full template here.

That is all there is to it. As you can see, the template is very simple. Now let’s discuss when and how to use it.

To make this more tangible, let’s look at a few concrete work situations where RFCs are useful.

Imagine a team member raises a technical issue during the daily standup. The problem is clearly too complex to solve in a quick discussion. Instead of trying to resolve it immediately or scheduling yet another meeting, you could ask the team to write their proposals as RFCs and review them asynchronously. This gives everyone time to think, compare solutions, and come back with clearer reasoning.

Another typical situation is when the team is about to start working on some complex new functionality. Instead of jumping directly into the coding, you could suggest that someone on the team take time to do research and write a detailed RFC describing the technical approach. Writing and reviewing the proposal within the team will help pick the right approach and at the same time ensure that everyone on the team has the same understanding of the work ahead.

When I look back at the time I left on vacation and handed the feature over to the team, I really wish I had written an RFC. I’m sure the engineers would have executed the work exactly as intended.

We learned the lesson, and now RFCs are an integral part of our engineering process. They help us create better technical solutions, stay aligned on the architectural vision, and spread knowledge across the team.

This is the first in a series on building clarity into how teams work. If you found it useful, consider subscribing to High-Impact Engineering for new essays weekly.