Main idea

The current state of a repository says what the product does today, and nothing else. A Product Manager who reads there that an export limit is set at fifty rows gets the behavior, not its reason: the code keeps no trace of the fact that two hundred was tried, then dropped because of response times.

That trace exists all the same, one level down. Commits, pull requests and merge requests form a temporal layer of the same repository: they say how the current state was reached. A code review discussion holds a developer's objection, the technical constraint that forced a departure from the original request, the compromise accepted, the fix made three days after delivery because an edge case had appeared.

So the useful distinction isn't between the code and the documents, but between two readings of the same repository. The state answers behavior questions — which rule applies, where the limit sits. The history answers questions of reason — why this value, why this refusal, why this behavior changed between March and June. They are two distinct sources, consulted differently, and confusing them sends you looking in the state for what was never there.

Why it matters

This recovers part of what seemed lost when the code was designated as the source of truth. The usual objection — "code says what, never why" — holds for its state, not for its history; part of the product reasoning was written down, just not where you look for it.

It also changes what you expect from a code review. The comments on a merge request stop being a disposable conversation between two developers: they are the only place where the real trade-off was recorded at the moment it was made, without passing through a document written after the fact.

Nuances and limits

The history only talks if somebody made it talk. A repository whose commit messages say "fix" and whose merge requests are merged without a single comment carries no intent at all: the layer exists and it is empty.

Location is misleading too. The richest discussions live in the forge — GitHub, GitLab — and not in the cloned repository; rewriting history by squashing commits carries off what had been recorded there.

Finally, a recovered intent is dated. The reason for a choice made three years ago explains that choice; it doesn't justify the current rule, which may have been rewritten since for an entirely different reason, with nothing connecting the two moments.

Open questions

• How do you recognize that a merge request discussion deserves to be promoted into a written product decision, rather than left where it was recorded?