Why Did We Choose This Tech?

Bridging the gap between technical documentation, and the actual implementation. Turn team conversations into shared decisions, then use AI to check GitHub pull requests against what you agreed to do.

Comment

Inspiration

This started with a problem one of us had at work: one architecture decision record (ADR) can span five microservices, and enforcing it across all of them is a nightmare.

In one case, an AI agent hallucinated a single bullet point about “audit logs.” That one line cost one of us hours of work across reviewers and maintainers. A small piece of invented scope became real engineering work.

A repository shows what we built, but the reasoning behind it is scattered across documents, tickets, and conversations. As AI speeds up implementation, we need a better way to preserve that reasoning and check whether the code follows it.

We built whydidwechoosethis.tech to keep the why with the work.

What it does

Start a project, connect your repositories, and talk with an AI assistant through text or voice about what you want to build. The assistant helps question assumptions, clarify tradeoffs, and turn the conversation into an architecture decision record.

Bring teammates into the same workspace to discuss the proposal while the assistant refines the document. When the team agrees, publish a version that captures the decision.

A GitHub review bot then checks pull requests against those published decisions and flags contradictions. It references the published agreement, even when the draft has continued to change.

Linear and Slack integrations connect the workspace to the tools teams already use. Controlled document access through the Model Context Protocol (MCP) also gives coding agents access to the decisions that should guide their work.

How we built it

We built the application with React, TypeScript, and vinext, running on Cloudflare Workers. PostgreSQL and Drizzle handle persistent data, and WorkOS handles authentication.

Gemini through OpenRouter powers planning and reasoning, while ElevenLabs powers voice interaction. We connected GitHub for decision-aware pull request reviews, added Linear and Slack integrations, and exposed controlled document access through MCP.

And a lot of Celsius energy drinks.

Challenges we faced

The hardest part was getting our heads around the data model.

What counts as a change? What makes it a revision? How do we link each one back to the conversation that produced it? And how do we preserve a published agreement while its draft keeps evolving?

Provenance is central to this project. Keeping the final document isn’t enough—we need to preserve where a decision came from and how it changed. Getting the relationships between conversations, changes, revisions, and published versions right was a doozy.

Accomplishments we’re proud of

We crushed our stretch goals: both Linear and Slack integrations made it into the project.

We also connected conversational planning, team discussion, traceable decisions, voice interaction, coding-agent access, and GitHub review into one workflow.

Receiving a real pull request review grounded in an ADR we had published was an awesome moment. We could see the full loop working: talk through a decision, agree on it, and check the implementation against it.

What we learned

We learned that the data model is the foundation of a tool like this. If you can’t trace a document change back to the conversation behind it, you’ve lost part of the reason the product exists.

We also learned how much care it takes to make text, voice, shared documents, and external integrations feel like one coherent workspace.

And we learned that sleep is important—even with Celsius on our side.

What’s next

We want to deepen our GitHub, Linear, and Slack integrations so decisions stay connected to discussions, tickets, and implementation as projects evolve.

We also want to improve review across multiple repositories. An ADR that spans five microservices should be useful across all five, without someone having to enforce it by hand.

Built With

Share this project:

Updates

Submission history