What if the product development operating system lived in git?
I ended my evening at Demo Nights by How to Web with a chat with Petre Dragoș Constantinescu and Mara Hutart about something I’ve written about before: bringing product requirements into git.
The conversation went into the broader idea of a product development operating system living in a GitHub repository. Decisions reviewed as pull requests, the reasoning kept alongside the implementation, and a trail you can follow six months later when you are writing the postmortem and trying to understand why you made those choices.
As engineers, they immediately connected with the idea of having that history available. Their reaction gave me some encouragement to do more with it. I’ve been thinking about this for a while, and talking it through with people outside my usual work context helped.
Let the agent deal with git
Product people and nontechnical colleagues should be able to use this without learning git. I want to explain a change, read what it does to the document, and ask the right people to review it. Learning how to untangle branches should not be the price of admission.
Git is already familiar territory for coding agents. Claude Code, for example, can create branches, commit changes and open pull requests. Preparing an edit to a requirements document uses those same mechanics; the product judgement still belongs to us.
The experience I have in mind is closer to: “Move SMS to a later release, keep email for launch, and ask support what we’re missing.” The agent prepares the proposal with the reasoning we supplied, then brings back the changed document for people to review. We should be reviewing the decision, without having to operate git ourselves.
What actually changes in the document?
Take an order-tracking feature for an online shop. This is a made-up example, but the trade-off should look familiar: reduce the scope or move the launch date.
A requirement changes. Here is exactly how.
One order-tracking feature, from the original product requirements document (PRD) to a revised proposal. Click the coloured button to follow each step.
Step 1 of 4 · No proposal yet
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
The document contains the plan. Comments and approvals live in the collaboration panel beside it.
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
Alex’s comment is attached to the highlighted requirement. The original text has not changed.
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
A diff shows exactly what changed: − means removed, + means added. Unchanged text stays visible.
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
This is the revised proposal, not the agreed plan yet. The next widget picks up this same document.
Product decisions as pull requests
The part I find enticing is reviewing decisions in the same way engineers already review code: someone proposes a change, others question specific parts, and the discussion stays attached to the proposal. Git keeps the document versions; a platform such as GitHub or GitLab keeps the comments and approvals around them.
Review the same proposal together
Proposal #42 is ready for feedback. First act as the author, then as Sam, the reviewer. The coloured button tells you what to do next.
Step 1 of 4 · Changes requested
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
Sam has suggested a requirement. It is still a comment until the author applies it to the document.
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
Approval refers to this specific revision. Here the diff only adds a requirement, so there is no red deletion.
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
The approval stays beside the reviewed text. In this example, one reviewer must approve before the author can merge.
Help signed-in customers find out where their order is.
Fewer support requests asking where an order is.
Merge saves the agreed document and its history. The product still needs to be built and released.
A postmortem with the reasoning still attached
Six months later, customers report missing delivery updates, and I ask an agent to investigate why SMS was left out of the launch. It can search the codebase, find the relevant line in the PRD, and follow its history back to the PR, the people who contributed and the reasoning in their inline comments.
From a code search to a better postmortem
Six months later, customers report missed delivery updates. You ask an agent: “Find why SMS was deferred and bring the decision context into our postmortem.” Follow its investigation.
Step 1 of 4 · Agent searches
git grep -n "SMS" -- src docs// SMS deferred: docs/prd/order-tracking.mdThe agent uses git grep to find matching text. This example deliberately keeps the PRD in the code repository and includes a reference from the code.
How the agent traces this sentence
git log -p -S "Schedule SMS for a later release." -- docs/prd/order-tracking.mdSearch revisions where this sentence was added or removed, then inspect the diff.
docs: defer SMS at launch (#42)
Author: Jamie ChenThe agent checks the introducing diff, then follows the PR reference kept in the commit message. That reference is a convention in this example, not something git invents.
Prepared the revised requirements and merged the approved version with the agent’s help.
The SMS supplier integration would delay launch by two weeks. Could we test email first?
What if a customer mistypes their delivery email? Add order-page tracking in their account.
Sam approved after the fallback was added. The discussion and approval remain attached to PR #42.
The agent reads the PR and its inline comments from the repository’s hosting platform. Git supplies file history; the PR supplies the conversation.
The team deferred SMS to avoid a two-week integration delay, and included account-page tracking as a fallback.
Email and the account page would provide enough coverage at launch. The postmortem needs to check that assumption against the affected customers’ experience.
This thread does not show whether emails arrived or customers checked their accounts. The incident’s cause remains open.
The output is a sourced draft for a blameless postmortem. This decision trail needs the repository and its PR discussions, without a Jira or Confluence integration.
That gives me something useful for the postmortem: the constraint we were working around, the assumption we made, and the fallback someone thought to add. The names help recover context; they are not a list of people to blame. Knowing why we chose a scope still leaves the incident’s cause to investigate.
For this trail, I don’t need to wire an agent into Jira, Confluence and three other places where a decision might have ended up. The PRD lives beside the code, git keeps its history, and the PR keeps the discussion. The agent needs access to that repository and its PR comments, plus a habit from us of writing down the rationale and preserving the PR reference. A grep is a starting point. The useful output is a few evidence-backed paragraphs and better questions for the team.
GitLab already does this beyond engineering
GitLab’s handbook is a useful example: changing a company process means proposing a change to the handbook through a merge request, their name for a pull request. Each department is responsible for keeping its part current. That is a fairly concrete way to make “this is how we work” something people can question and update.
This extends into nontechnical work. The finance handbook directs people to a finance issue tracker, including confidential issues, and marketing operations works from issues and issue boards. Even product budget requests go through issues, with leadership bringing them into planning with Finance.
Those issues live in GitLab’s collaboration platform; the document history lives in git. What interests me is the shared habit: write down the proposal, involve the people responsible, and leave a record others can follow.
GitLab’s example shows the organisational practice. The part I want to explore is using agents to make that practice accessible without asking everyone to learn the tools underneath. A colleague in finance should be able to question a cost assumption in plain English and see that feedback reflected in the next revision. I would quite like that for my own work, too.
Thanks to Dragoș and Mara for the conversation. Their interest was a useful nudge to come back to this idea and see what I can make of it.