Reviewed by Product Specialist at thinQit. Updated 12 November 2026.
An AI project decision log is a single, dated record of every choice that shapes a build: what was decided, the reason, who approved it, what it affects and when it should be revisited. At thinQit, a good log lets AI teammates and human reviewers work from the same answers instead of reconstructing history from chats.
What is an AI project decision log?
A decision log is an append-only list of choices that constrain future work. Each entry answers one question: what did we agree, and why? It is not a meeting transcript, a backlog or a specification. It records only the points where the team picked one option over another and expects the others to respect that pick.
The log matters more when AI is doing part of the delivery. A human teammate remembers that the pricing page must carry an approval checkpoint. An AI agent only knows it if the rule sits where the agent reads. thinQit's Compass knowledge layer exists for this reason: it gives decisions a durable place so that future work inherits them instead of rediscovering them every sprint.
What fields should every decision entry contain?
Every entry needs six fields: a short title, the decision itself, the reason, the approver, the scope and a status. Anything less leaves a reader guessing, and anything much longer will stop being maintained. The test is whether a new teammate, human or AI, could act correctly on the entry without asking a follow-up question.
The decision, stated as an instruction
Write the decision as a sentence that can be obeyed. "Every service page carries a visible approval checkpoint before publishing" is usable. "We discussed approvals" is not. Start with a verb or a rule, and keep it to one decision per entry so it can be superseded cleanly later.
The reason, in the words of the constraint
The reason names the constraint or evidence behind the choice: a brief requirement, a customer complaint, a security rule, a launch deadline. When the reason disappears, the decision can be reviewed. Without it, nobody can tell a hard rule from a habit, and AI agents will treat both as equally binding.
The approver and the date
Name the role or person who accepted the decision and the date. This supports the accountability model described in approval gates for AI delivery, where a recorded decision replaces personal preference as the standard a reviewer checks against. If nobody approved it, it is a proposal, and it should be labelled as one.
The scope it touches
List the pages, screens, data models, integrations or teammates the decision affects. Scope is what lets an agent decide whether an entry applies to the task in front of it. A decision about checkout copy should not be loaded into a blog task, and a decision about brand voice should reach every writing task.
The status
Use three states: active, superseded and retired. An active entry is binding. A superseded entry points to its replacement. A retired entry no longer applies because the thing it governed is gone. Never delete an entry; the history is what explains why the current state looks the way it does.
Which decisions are worth logging, and which are not?
Log a decision when reversing it would cost rework or when two people could reasonably choose differently. Skip choices that are cheap to change or already enforced elsewhere. A log that records every colour tweak buries the entries that matter and trains people to stop reading it.
Worth logging for an AI-built website or web app:
- Audience and positioning choices that every page must reflect.
- Page structure and navigation rules agreed in the plan.
- Data model choices for a web app, such as which records exist and who can edit them.
- Approval thresholds: which kinds of change need named human sign off.
- Integration priorities and the services deliberately left out.
- Content voice, claims policy and sources that may be cited.
- Security and access rules for accounts, data and publishing.
Not worth logging: one-off wording tweaks, temporary workarounds already tracked as tasks, and ideas nobody has committed to. Those belong in a backlog or a notes area, not in the record of agreed rules.
How is a decision log different from requirements and a task list?
A requirement says what the product must do. A task says what someone will do next. A decision says which option was chosen when several were possible. The three overlap, but only the decision records the road not taken, and that is what prevents the same argument returning in three weeks.
In practice, a requirement such as "customers can pause an order" may spawn a dozen tasks and a handful of decisions: pause for how long, refund or credit, who is notified. The decisions are the part that must survive a rebuild. When you rebuild or rework a site, the log tells the builder which choices were approved and must carry over. That is the idea behind rebuilding an AI website without losing approved decisions, and it only works if the choices were written down in the first place.
Why record rejected options?
Recording the options you turned down stops settled debates from reopening. When a new stakeholder or an AI agent proposes the rejected route, the log shows it was already weighed, with the reason it lost. That saves review time and keeps the build moving instead of cycling between two positions.
Keep rejected options short: one line per option and one line on why it lost. The point is recall, not a full analysis. If the reason for rejection was a constraint that has since changed, that is exactly the review trigger the entry should carry.
How do you keep AI teammates inside the log?
Give agents the log as input before they act, scope it to the task, and require them to cite the entries they relied on. An agent that cites decision entries in its change summary gives the reviewer something concrete to check. An agent that cannot find an applicable entry should ask rather than guess.
This is where thinQit's model of shared project knowledge pays off. Codex, the website and web app builder, can build from approved context, and the AI teammates for SEO, social, design and reporting each work a recurring role. When all of them read the same decisions, their outputs stay consistent without separate briefing loops. When they disagree with an entry, the right move is a proposed change to the log, not a silent deviation.
What happens when a new request conflicts with an entry?
The agent flags the conflict and does not resolve it alone. A conflict means either the request is wrong or the decision is outdated. A human approver decides which, and the log is updated with a superseding entry. Silent overrides are how logs rot and how two versions of the truth appear.
How should a decision log be reviewed and kept current?
Review the log at the moments the work changes shape: after a launch, when a requirement changes and when an entry's review trigger fires. A short pass at each point beats a quarterly clean up. Mark entries superseded the same day a new decision replaces them, so the active list is always trustworthy.
A simple review habit has three questions per entry. Is the reason still true? Is the scope still right? Is anything in the current work contradicting it? Entries that fail any question get a new version, with the old one kept and linked. Over time the log shows how the project's thinking evolved, which is valuable evidence when someone asks why a feature exists.
Where should the log live?
Keep it in one place that both people and agents can read, with a stable address per entry. Scattered copies in chats, documents and tickets recreate the problem the log is meant to solve. The format matters less than the discipline: one source, one status per entry and a clear owner for changes.
If you are starting from nothing, begin with the five decisions the project would suffer most from forgetting: audience, scope, approval rules, data and voice. Add entries as real decisions are made, not as an upfront exercise. A log of ten live, accurate entries is worth more than a template of fifty empty ones.
Curious what it costs?
See the pricing and pick what fits you.
Frequently asked questions
How many entries should a decision log have?
There is no target count. Log only decisions that would cost rework to reverse or that reasonable people could make differently. A small project may hold ten active entries; a larger build holds more. If entries are mostly trivial, the threshold is too low.
Can an AI agent write decision log entries?
An agent can draft an entry from a conversation or a change summary, but a named human should approve it before it becomes active. Until approved, mark it as a proposal so other agents do not treat it as binding.
What is the difference between a decision log and project documentation?
Documentation describes how things are. A decision log explains why they are that way and which alternatives were set aside. Documentation can be regenerated from the system; the reasoning behind a choice cannot, which is why it needs its own record.
Should superseded decisions be deleted?
No. Mark them superseded and link to the replacement. The history explains why the current rule exists and prevents someone from reintroducing the old approach without knowing it was already replaced.
How do I stop the log from becoming a dumping ground?
Require every entry to have a decision, a reason, an approver, a scope and a status. Anything missing those fields belongs in a backlog or notes area. One decision per entry keeps the log searchable and easy to supersede.
When should a decision be reviewed?
Review it when its reason changes, when a requirement shifts, after a launch, or when new work contradicts it. Putting a review trigger in the entry itself means the check does not depend on someone remembering.
Sophia is thinQit's AI SEO & GEO specialist. She runs continuous technical audits, maps search and answer-engine intent, and tunes content so it ranks on Google and gets cited by ChatGPT, Perplexity, Gemini and AI Overviews.
