A project decision log: record the reason, not just the result
Record project decisions with their context, alternatives, consequences, owners and review conditions. Keep approval separate from evidence of execution.
Article language: English

In this article
“Why did we do it this way?” asks someone new to the team. After a pause, someone replies, “There must have been a reason.” A decision log preserves that reason, the alternatives considered and the conditions behind the choice. A short record of an important decision is enough; you do not need a transcript of the entire project. When circumstances change, the team can recover the context instead of inheriting a habit that has gradually hardened into an unquestioned rule.
There is no need to record every small action. Choose decisions that affect the cost of change, responsibility, access or later stages of work. At Aeneia this discipline connects design, AI review and work with sources. People and agents should be able to tell which decision is in force and who can change it.
Which decisions deserve a separate record?
Start with matters that keep returning to discussions: the publication model, integration scope, approval process and data source. If a new team member needs an oral explanation of why a solution looks the way it does, that context probably deserves a record.
For a website, it might be the choice of one domain and stable addresses. For AI, a restriction on access to a particular folder. For market research, the definition of a category. Each decision affects later work, even if it can be explained briefly.
Do not turn the log into a diary of every meeting. Meeting notes can serve as a source, but you need a clear record of what was actually approved. Draw a line between a proposal and the decision in force.
What belongs in a decision record?
Provide an identifier, title and status. Then describe the problem, important constraints and alternatives considered. Record the chosen direction, the reason for choosing it and the consequences. Add the approver, date and sources needed to understand the issue.
Technical projects use a similar device: an architectural decision record, or ADR. AWS describes the ADR process in terms of context, decision, consequences and a lifecycle of statuses. The template below extends the practice to other significant project decisions.
- Problem: what needs a decision and why now.
- Conditions: goals, constraints and sources.
- Alternatives: the options actually considered.
- Decision: the specific choice and its rationale.
- Consequences: work, costs and constraints arising from the choice.
- Change: what could justify reviewing it again.
- Responsibility: who approved it and who takes the next steps.
Leave room to record a rejected option and the reason for rejecting it. The next person will not have to repeat the same analysis from the beginning.
What might a practical example look like?
Consider a fictional company blog. The team wants to publish regularly but does not yet need editor accounts or an extensive administration interface. It considers a file-based system and an external panel. After checking the requirements, it chooses files and identifies how corrections and deployments will be handled.
The record says who publishes, how HTML is generated and what needs checking. A reason to revisit the choice might be a need for several editors to work without repository access. This illustrates the method; it does not claim that one model suits every company.
An AI pilot needs a different record: permitted data, the person accepting the work and the criteria for further use. It should link to the pilot record (in Polish) rather than copy every result into another document.
How do you preserve history when the decision changes?
Record the new decision and link it to the earlier one. Mark the earlier record as superseded, with a date and a link to its successor. The team can then reconstruct which decision applied when a particular version of the project was built. If AI extracts these connections, check the direction, timing and basis of relationships in a knowledge graph so the tool does not reverse the relationship between the current and superseded decisions. For more detail, see the guide to relationships in a knowledge graph (in Polish).
Do not rewrite the old rationale as though new information had been available from the start. The history helps explain changing conditions. A separate note can correct an editorial error while preserving a trace of the correction. In AWS's ADR process, accepted or rejected records are immutable; changing a decision requires a new ADR and review.
AWS guidance on storing ADRs emphasises ownership, history and a shared location. In practice, choose a repository or document store that works for the people making the decisions. The point is to find the right version when it is needed.
How can agents use the log?
Identify the current records as sources for the task. An agent should distinguish a proposal, an accepted decision and a superseded one. If sources conflict, record the discrepancy and name someone who can resolve it.
Finding a record does not authorise an agent to perform any action it chooses. The scope still comes from the current task and the access granted. Responsible AI agent workflows help separate reading, preparing a result and approving an operation. This is discussed in the article on responsible AI agent workflows (in Polish).

Who needs to know about the decision and confirm it was carried out?
Separate approval from execution. A record may choose a publication method, but someone still needs to own the deployment and check the result. Link to the task, code version or acceptance record that confirms implementation.
Establish whose work the change affects too. A different domain affects links in published materials; restricting an integration may change team instructions. Notifying the right people and updating documents deserve their own actions. The log then connects decisions to work instead of merely collecting approved sentences.
How do you compare options without simply defending the favourite?
List criteria before choosing. For a publication model, these might include who makes changes, how often corrections occur, access control and maintenance cost. Describe each option against the same questions. Do not compare a carefully costed solution with “the other options are difficult”; the next person will not be able to reconstruct that assessment.
Mark each premise as a fact, an assumption or a constraint imposed by the project. For example, a team may assume one editor but have no cover plan yet. A choice based on that number should identify its source and the condition for checking it again. The cost of building something is not the same as the cost of changing it later.
For a website, start with the goal agreed in the premium project brief (in Polish). If the choice concerns the number and arrangement of pages, the B2B information architecture guide can help. The log should explain why the chosen structure serves that goal, not merely list screens. For related guidance, see the guide to B2B information architecture (in Polish).
How do you record a conditional decision and a limited experiment?
Suppose, for an exercise, that a company wants to connect AI to a folder of approved materials. The decision may authorise only a small pilot, a defined set of data and no automatic sending. “We are deploying AI” would erase those limits. Say exactly what was approved and what a successful pilot would not yet authorise.
Add a review date, an owner and an end condition. If the pilot never takes place, the decision should not justify active access indefinitely. The AI data flow register (in Polish) describes the technical scope of the connection; success criteria stay in the pilot record. Links help keep one current description of each subject.
An experiment also needs a way back to its starting point. For a website change, that might be the previous deployed version and a list of URLs. For an integration, it might be a description of roles and active connections. Agree who will perform the rollback and how they will verify that the expected behaviour has actually returned.
What if the decision is still formally in force but practice has changed?
Compare the record with what happens. A card may still specify manual approval even though a new integration publishes automatically. That discrepancy needs a concrete response. Changing words in the document is not enough without establishing whether the new behaviour is allowed and who approved it.
In the log, identify evidence of implementation and the last date on which an important condition was checked. The evidence could be a setting visible in the system, the result of a controlled scenario or a verified publication URL. If evidence is missing, retain a “to be confirmed” status. The reader should be able to distinguish the choice of direction from its execution.
How do you review the log briefly at the end of a stage?
Choose the decisions related to the result being handed over and check four things: whether they still apply, whether implementation matches the record, whether a review condition has been met and whether it is easy to find the decision that superseded an earlier one. You do not have to reopen every historical note. Focus on decisions that affect current work and responsibility.
If you are changing website addresses, connect the record to a migration plan that preserves URLs (in Polish). Record the decision to change them separately from evidence that old links were checked. That distinction makes it possible to determine whether a problem lay in the choice, its execution or an assumption that later became outdated.
At handover, check that the underlying sources remain accessible. If the rationale points to a closed session or a former colleague's folder, a new team member cannot reconstruct the decision. Keep the relevant document in the agreed location and name an owner who can explain its scope.
If a choice is still awaiting approval, prepare a decision note for management (in Polish). Once the decision is made, keep the chosen option and the conditions under which it applies in the log. A document used to make a choice and a record of the choice serve different jobs.
How do you start without excessive documentation?
Choose a few important decisions from the current project. Describe them with one template and ask someone outside the conversation to read them. Check whether they understand the choice, its reason and the condition for changing it. Add missing context instead of lengthening the document for its own sake.
Knowing why a choice was made does not prove that someone can carry out the task independently. Test the company's dependence on one person in practice: can someone else use the decision and materials without reconstructing the context solely from an expert's memory? You can also consult the article on dependence on one person (in Polish).
Connect the log to the knowledge architecture and the project handover package (in Polish). The Aeneia Audit service covers how sources, tools and responsibilities are organised. Start with the decisions that actually affect your next steps. The topic is explored in the guide to structuring company knowledge (in Polish).









