Blog
“Doesn’t this API response look different from the Figma design?”
It’s Friday, right before release. A single message in Slack stops the team cold.
The PM had been diligently updating Jira tickets. The designer had been polishing Figma files. The engineers had been shipping PRs at full speed. Everyone was doing their best work in their own domain — and yet, the moment everything came together, the misalignment was undeniable.
What follows is predictable: Friday-evening Slack archaeology. “Where was this spec even decided?” “This API doesn’t match the original ticket — who changed it?” Nobody has the answer, because the context behind the decision was never captured anywhere.
We fell into this “nobody’s fault, everything’s on fire” hell more times than we’d like to admit. Beaket was born from that experience.
Specs Are Designed to Lie
It’s not that specs are bad. It’s that the structure around them is broken.
Information naturally lives in different places — PMs live in Jira, designers in Figma, engineers in GitHub. That’s fine. Each tool is best at what it does, and you shouldn’t fight that.
The problem is the act of copying all of that into a single “source of truth.”
The moment you transcribe something into Notion or a wiki, there are now two copies. When one gets updated, the other becomes a lie. A spec that stops being maintained loses the reasoning behind past decisions and becomes a relic that drifts further from the actual implementation.
This isn’t a discipline problem. It’s a structural one. As long as copies exist, drift is inevitable.
Connect, Don’t Copy
So we abandoned the “centralize everything” approach. Building yet another wiki would just lead to the same outcome.
What Beaket does instead is draw relationships between information that already exists.
You don’t copy your Figma designs or GitHub discussions into Beaket. Each tool remains the source of truth for its domain. Beaket simply connects those sources through the context of why a decision was made.
Specifically, it structures project decisions around three types of nodes:
- Spec — The business requirement. What are we building, and why?
- Brief — The design decision record. What was decided from a design perspective, why, and what breaks without it.
- ADR — The technical decision record. Why this approach? What alternatives were considered and rejected?
These three connect to each other through edges, forming a decision graph. You don’t write detailed specifications in Beaket. You capture what was decided, why, and what it connects to — nothing more.
The “Write Less” Rule
Honestly, this was the most debated aspect of the product.
“Shouldn’t we let people write more detail?” Of course that came up. But the moment you allow detailed writing, you’ve built another wiki. And wikis always rot.
So we intentionally built a constraint into Beaket: write less.
The heuristic is simple — would your future self come looking for the reasoning six months from now? If yes, write it down. If not, don’t. Parameter lists and implementation steps belong in GitHub. Beaket holds only the minimum unit of why.
This is a deliberate tradeoff. Beaket will never be a comprehensive design document tool. That’s by design.
The Ready Flag: A Handshake, Not an Approval
There’s one more mechanism we’re glad we built.
After a Spec is written, both the designer and the engineer independently set a “Ready” flag. The designer signals “I understand the requirements from a UI perspective.” The engineer signals “I understand them from a technical perspective.” Only when both flags are set does the Spec become “Ready.”
This isn’t an approval workflow. It’s a handshake.
Not “I’ve read it,” but “from my perspective, we’re good to go.” It’s a structural safeguard against starting implementation on ambiguous requirements.
And if a Spec changes after it’s been marked Ready, the blast radius — every connected Brief and ADR — is automatically surfaced. No more digging through Slack history.
Following the Decision Trail
Beaket tracks change history beyond just who changed what, when. It also captures why.
Select any piece of text, and you can trace when it was changed, by whom, and for what reason. We call this the Decision Trail.
It’s not a flashy feature. But six months from now, when someone asks “why is this spec the way it is?” — the answer is right there. That alone changes how fast a team can make decisions.
What We Don’t Know Yet
We don’t think Beaket is the right fit for every team.
For a small team sitting in the same room, where context is naturally shared, it might be overkill. For organizations with hundreds of people, we haven’t validated enough yet.
What we are certain of is this: losing the context behind decisions always has a cost. And that cost grows exponentially as teams scale and time passes.
Beaket is a tool for keeping that cost in check — structurally. It’s not a silver bullet. It’s more like insurance.
If your team has ever been in a situation where nobody can explain why a design decision was made — start by connecting just one decision. See where it takes you.