Why Record the Reasons Behind Design Decisions: Requirement Versioning and Decision Logs
Three weeks into a project, someone asks: "Why did we pick this battery?" Nobody remembers. The chat where it was decided is gone, the agent that suggested it is in another session, and the choice gets argued again from scratch.
Most projects keep what was decided. Far fewer keep why. The why is what lets you change a decision safely later. It is also what makes picking up a stalled hardware project fast.
What a requirement version is for
Requirements change: a size limit tightens, a budget appears, an accuracy target turns out to be unrealistic. If the requirement list is simply overwritten, you lose two things: what it said before, and which decisions were made against the old version.
A useful rule: a new requirement version only when a requirement actually changes. Saving the same content again, or adding a conversation note, should not create a "new version". That keeps the version number meaningful: if it went up, something you build against changed.
What belongs in a decision log
Each entry should answer five questions:
- What was decided, precisely: which option, against which plan.
- The decision itself: selected, sent back for revision, or rejected.
- The reason, in a sentence or two.
- Who said it: the person's own words, kept separate from an agent's suggestion or an assumption.
- What it depended on: the requirement version and the research sources at the time.
The last point is the one that pays off. When a requirement changes, you can find every decision that rested on the old version and check whether it still holds. It matters most before you contact a manufacturer, when changes start to cost money.
A short example (synthetic demo)
This is a synthetic demonstration written to show the format. It is not a real user project, and nothing was built or tested.
Desk temperature indicator. Requirement version 2 adds "readable from two metres". The decision log already contains: display option B selected, reason: lowest power at the original one-metre viewing distance. Because the decision records the requirement it was made against, the change flags it for review instead of silently carrying an outdated choice forward.
How ThingWeave records this
ThingWeave is a private project workspace you share with your AI agent over MCP. In a project:
- Structured requirements are versioned. The requirements version only increases when a requirement field actually changes.
- Context checkpoints let your agent save goals, answers, constraint changes, decisions and handoffs, marking what is the user's own words, a paraphrase, an agent suggestion or an assumption. A new session can page back through that history (see continuing an agent project across chats).
- Plan decisions are recorded against a specific plan and option as selected, revision requested or rejected, with the rationale and an excerpt of what the user said.
- Research and plans keep their own versions, with sources and open risks.
Recording a decision is only a record. It does not authorise purchasing, contacting suppliers or manufacturing, and ThingWeave does not provide engineering sign-off. Full list: ThingWeave's capabilities and limits.
We are in pilot, and you can sign up and try it. Start your first project →
FAQ
What is a design decision log?
A running record of each design choice, the options considered, the reason for the choice and what it depended on, so it can be checked later instead of re-argued.
How is requirement versioning different from saving a document?
A version marks a real change in what the project must do. Decisions made against an older version can then be found and reviewed when requirements move.
Do I need to log every small choice?
No. Log choices that are expensive to reverse or that other decisions depend on: architecture, key components, power, enclosure approach.
Can my AI agent keep the decision log for me?
An agent connected to ThingWeave can record decisions and checkpoints, but it should record what you actually chose. It cannot choose on your behalf.
Does a recorded decision mean the design is verified?
No. It records what was chosen and why. Verification still needs real tests and, where required, qualified engineering review.