Building a team consensus tool, mostly alone
At some point in the last 10 years building a product stopped feeling like a technical challenge and started feeling a lot more like a communication problem. I belive the way organizations and teams communicate has been the biggest indicator of the quality of their work. Because of that I’ve read a lot about topics that mix my background (information systems and software architecture) and company organizational structures. I have also had the opportunity to work with some incredible people who know way more than I do about this who have taught me different ways the communication can happen. As a bonus those same folks were all open to experimenting on different approaches as we worked together. That hasn’t made me an expert, but I think it was a unique experience. It was valuable enough that I think I can build something that could help most teams.
Before I build anything I want to write down my focused ideas and try and give a model for it. That’s what I’m trying to do here. I hope the journey is interesting. But if not the act of writing will help me regardless, so I’ll get to it.
Focusing on the problem
I’ll focus on how teams form and maintain agreements. Agreements could be about your team’s norms, an approach to a problem, hours of work, types of team rituals, etc. I’ll focus on the process of agreement so that it can work on many different contexts.
If I’m going to build something, I’ll want to define a few of my terms as well as point out my assumptions.
What’s an agreement
Here’s how I think about an agreement—it falls into one of two categories:
- mutual approach to collaboration
- a shared understanding
These sound pretty related, but I believe they’re arrived at and maintained differently. Mutual approaches to collaboration are tactile. They’re things teams practice and perform. Shared understandings are about communication and alignment. Basically, a shared understanding is something that’s needed for communication but there are no additional actions to take with it.
What’s a decision
A decision is a conscious choice, after an evaluation of options, pros, and cons.
When you break it down, a decision really starts with realizing there’s a question that needs answering or a choice that needs making. Maybe the team needs to pick a new tool, figure out how to handle on-call, or decide on a code review process. Without at least two real options, you’re not really making a decision—you’re just doing what you’re told.
Once you have options on the table, the interesting part begins. You start weighing what each option gives you against what it costs you. One might be faster to ship but harder to maintain later. Another might feel safer but take longer to get started. These trade-offs are where the real thinking happens, and they’re also where teams tend to either come together or drift apart.
After you’ve thought through the trade-offs, you pick one and commit to it. But here’s the thing—a decision isn’t really a decision until you act on it. Saying you’ll do something and actually doing it are different things.
Teams make decisions about all sorts of things. Sometimes it’s concrete and technical, like which database to use or whether to adopt a new testing framework. Other times it’s about how you work together—maybe deciding to have daily short meetings instead of weekly syncs, or figuring out how code reviews should work. And then there are the people decisions, like what criteria matter for hiring or how to structure an on-call rotation.
What’s consensus
Consensus is harder to pin down than it sounds. At its core, consensus means everyone can live with the decision—not that everyone loves it, not that it’s anyone’s first choice, but that the group can move forward together without someone actively blocking progress.
This is different from majority rule, where the minority loses. In a majority system, half plus one wins and the rest deal with it. That works for some contexts, but it can leave a trail of disengaged team members who feel unheard.
It’s also different from unanimity, where everyone must agree completely. Unanimity sounds fair but it’s impractical. Someone’s on vacation. Someone really doesn’t care about this particular topic. Waiting for everyone to love everything is a fast path to doing nothing.
The sweet spot most teams actually want is something like “disagreement and commit”—you might not fully agree, but you understand the decision, you can explain it to others, and you’ll support it. That’s consensus in practice.
Starting at a high level
What’s a data flow diagram
A data flow diagram (DFD) is just a way to picture how information moves through a system—what comes in, what gets stored, what goes out, and how the pieces connect. Think of it like a flowchart but focused on data instead of steps. The circles are processes (things that transform data), the open boxes are data stores (where data sits), the arrows are flows (how data moves), and the square things at the edges are external actors (users or other systems).
I’m going to keep this diagram intentionally basic. It’s a starting point, not a finished design. The goal is to get something on paper that we can react to and iterate on.
About that Repository box
You might notice a “Repository” box in the diagram. That’s where things get interesting. I’m not talking about just storing agreements in a database—the Repository is about integration. We could interact with platforms like GitHub, GitLab, SourceHut, or ForgeJo to track agreements as issues, pull requests, or comments. Maybe the agreement system reads existing issues to understand team context, or writes new items when an agreement needs review. The details of how we’ll integrate with these platforms is something we’ll discover as we build the agreement system itself, which is what we’ll focus on going forward.
coming soon, a break down of use cases and starting problem frames of the system.