The Intent Ledger
← All articles

Stop Losing Context: Decision First Architecture Project Documentation

Stop Losing Context: Decision First Architecture Project Documentation

Architecture project documentation is a structured, source-backed decision record that links a decision to its original conversations and evidence. The single best practice is to capture one record per significant decision and attach it to the relevant stage deliverables, rather than burying choices inside general meeting minutes. Done this way, anyone on the team can trace why a decision was made months later, and far less context gets lost between stages.

TL;DR:

  • Each record should state the decision as an imperative, preserve its rationale, cite one to three evidence items, and link affected project deliverables.
  • Draft records during reviews, consultations, and client signoffs, name an owner, finalize within 48–72 hours, and link them to stage reports within five working days.
  • A one page template takes most teams under fifteen minutes once established and should include options, tradeoffs, consequences, status, and a changelog.
  • When a decision changes, create a new record, mark the old one superseded, link the records, and preserve an immutable snapshot of the original.
Theintentledger
theintentledger.com
Keep the Reason Behind Every Decision
The Intent Ledger turns project conversations, critique feedback, and client comments into source-backed records of decisions and design intent.
Explore project memory software

Table of Contents

What every decision record needs to capture

A decision record only works if a future reader, someone who was not in the room, can reconstruct what happened and why. That means every record needs the same core fields, whether it covers a material swap or a structural grid change.

  • Metadata: title, date, owner, project stage, and status (proposed, accepted, superseded).
  • Context and constraints: the problem being solved and the limits it had to work within.
  • Requirements or specs: the acceptance criteria the decision had to satisfy, stated as numbers or testable conditions where possible.
  • Options considered: the alternatives, with a short pros and cons note for each.
  • The decision itself: written as an imperative statement, “use X,” not “we discussed X.”
  • Evidence: the one to three strongest supporting items, following the feature, specification and evidence framework, which recommends limiting evidence per feature to keep records usable.
  • Affected deliverables: drawing references, BIM object IDs, or specification clauses touched by the decision.
  • Status lifecycle: a short changelog line each time the status changes.

Capturing the right fields matters more than the format you store them in. A record missing rationale or evidence is just a to-do item with extra steps.

Pro Tip: If you can only fill in three fields under deadline pressure, make them the decision, the rationale, and the evidence. Metadata and options can be backfilled; rationale rarely can.

When and where to capture decisions during a project

Decisions get lost when capture is left to memory or to whoever feels like writing it down. Build capture into moments that already happen on every project.

  1. Treat each RIBA-style stage gate as a mandatory checkpoint: no stage closes without a decision record for each major choice made during it.
  2. Capture during design reviews, specialist consultations, and client sign-offs, with one person assigned as recorder before the meeting starts.
  3. Draft the record live, in the meeting, even if it is rough.
  4. Have the decision owner finalize the draft within 48 to 72 hours, while memory is still fresh.
  5. Issue the finished record and link it to the stage report within 5 working days of the meeting.

This rhythm keeps records close to the conversation that produced them, which is where most of the useful detail lives and disappears fastest. RIBA stage reports are built to include the decisions made and their basis, so a record created on this schedule slots directly into the deliverable your client or consultants already expect to see.

A compact ADR and FSE template for architecture teams

Software teams have used architecture decision records for years to keep a short, consistent log of what was decided and why. The ADR community guidance lists context, options, decision, rationale, consequences, and status as the minimum fields, and that structure adapts cleanly to architecture practice when paired with the FSE framework’s focus on specification and evidence.

A one-page record keeps the following structure:

  • Header: ID, title, owner, date, project stage, status.
  • Context and problem: what triggered the decision.
  • Top requirements or specs: the two or three conditions the decision had to meet.
  • Decision: one imperative sentence.
  • Evidence: the top 1 to 3 supporting items, each linked.
  • Trade-offs and consequences: what you gave up and what you gained.
  • Affected deliverables and changelog: links forward to anything the decision touches or supersedes.
Field Example entry
ID ADR-14
Title Facade cladding material
Stage RIBA Stage 3
Decision Use zinc standing-seam panels on the north elevation
Evidence Supplier spec sheet, client review notes, cost plan line item
Status Accepted

This fits on one page and takes most teams under fifteen minutes to fill in once the habit sticks. Our design documentation template follows this same shape.

A workflow that makes records stick

A template alone will not keep records current; integrating construction document control workflows and automation can greatly enhance consistency and efficiency. You need roles and a repeatable path from raw notes to a published, linked record.

  1. Capture: a designated recorder drafts the record during or right after the meeting.
  2. Assign: the decision owner is named immediately, even if the record itself is finished later.
  3. Finalize: the owner completes missing fields within the 48 to 72 hour window.
  4. Publish: the record moves from draft to a status of accepted in the central log.
  5. Link: the owner attaches drawing references, BIM object IDs, specification sections, or cost plan items affected by the decision.
  6. Review: records are checked at a fixed cadence, not just when something goes wrong.

Automating the note-taking step removes the biggest point of friction in this chain, since manual transcription is where most teams quietly give up on documentation. Pair that automation with a clear approver role so records do not sit in draft indefinitely.

Pro Tip: Assign the information manager role to one person per project, even on small teams. Without a single owner for the record log, linking to deliverables becomes inconsistent within weeks.

Preserving history: versioning and governance rules

A decision record that gets edited after the fact stops being a record and becomes a guess about what was decided. Martin Fowler’s ADR guidance is explicit on this point: when a decision changes, you create a new record and mark the old one superseded with a link, rather than rewriting history.

  • Never overwrite an accepted record. Change its status and link forward instead.
  • Keep a changelog line on every status change, however small.
  • Store an immutable snapshot, markdown or PDF, alongside any live version so the original wording survives software changes.
  • Centralize records in one repository rather than scattering them across email and chat threads.
  • Define who can create and who can supersede a record, and set a review cadence so stale drafts get resolved.

AWS’s prescriptive guidance on ADRs recommends exactly this lifecycle: proposed, accepted, superseded, with clear ownership and a regular review meeting to keep the log trustworthy.

Copy-ready mini-templates for common decisions

Three short examples show how the format holds up across different kinds of decisions.

  • Material choice: context (budget cap on envelope), decision (specify fiber-cement panel over timber cladding), evidence (cost plan line, supplier lead time quote, sketch ID SK-22).
  • Facade system change: context (wind load exceeded initial assumption), decision (switch to a pressure-equalized rainscreen system), evidence (structural engineer’s email, revised calculation sheet, meeting timestamp 14:32).
  • Scope change: context (client requested an added floor), decision (revise structural grid and issue updated cost plan), evidence (client sign-off note, updated BIM object IDs, revised drawing set).

Reference evidence precisely: a meeting timestamp, a sketch ID, a BIM object ID, or a specification clause number, so anyone retrieving the record later can jump straight to the source. Scaling architecture conversationally makes the point that the conversation trail is often more valuable than the final drawing, which is exactly why these references matter.

A lightweight, central store beats a clever one. Keeping records in one searchable repository, linked consistently to deliverables, does more for retrieval than any filing taxonomy.

A practical note on small-first experiments

Teams that start documenting decisions usually notice fewer repeated arguments and less rework from forgotten constraints. The habit pays off fastest when you start small: one project, one recorder, one template, before rolling it out further.

At The Intent Ledger, we built our platform around this exact pattern, structured records traced back to the conversations that produced them. The goal was never more paperwork, just less lost context.

, Rajas

The Intent Ledger: decision-first project memory for your team

We turn project conversations, meeting notes, transcripts, critique feedback, and client comments into ILM Records: structured, source-backed records of decisions, design intent, risks, actions, commitments, and unresolved questions. Every record traces back to the conversation it came from, so nobody has to reconstruct a decision from memory six months later.

Theintentledger

  • Studio leads and project managers get a running log of decisions tied to the deliverables they affect.
  • Junior designers and freelancers get a clear record of rationale without having to chase down who decided what.
  • Everyone on the team gets fewer repeated conversations and a faster handover between stages.

If you want to see how the format works in practice, check our pricing plans, including the one-off Project Record pack or the monthly Working Memory plan, or visit The Intent Ledger to see the full product.

FAQ

What is the difference between a decision record and meeting minutes?

Meeting minutes summarize what was discussed; a decision record isolates one specific choice and captures its context, rationale, evidence, and consequences. The ADR community guidance recommends writing one record per significant decision rather than relying on general minutes to carry that weight.

How many pieces of evidence should a decision record include?

Limit evidence to the top 1 to 3 items per decision, following the FSE framework’s recommendation. More than that tends to make records harder to read and maintain, so link to a fuller file for anything beyond the strongest few items.

When during a project should we capture these records?

Capture at the end of each RIBA-style stage, plus during design reviews, specialist consultations, and client sign-offs. A practical timing rule is to draft the record in the meeting, have the owner finalize it within 48 to 72 hours, and issue it linked to the stage report within 5 working days.

What happens when a decision changes later in the project?

You never edit the original record. Instead, you create a new one and mark the earlier record as superseded with a link between the two, which preserves the full rationale trail as described in Martin Fowler’s ADR guidance.

Where should we store decision records so they’re easy to retrieve?

Keep records in one central repository rather than scattered across email and chat, and mirror the key fields into stage reports so the decision shows up in both places. Tools like our decision log template or a shared markdown repository both work, as long as the location stays consistent across the project.

Sources