QUICK ANSWER
What should a decision log template include?
A decision log template should record a stable ID, status, context, considered options, linked evidence, selected option, decision and rationale, decision date, named owner, expected benefits, accepted costs, follow-up actions, a review trigger and date, and reciprocal links when a later decision supersedes an earlier one. It should also state what authority the log does not grant.
A useful decision log preserves why a bounded choice was made, not just its final wording. Each entry should connect the context, options, evidence, selected option, decision, date, owner, consequences, review trigger, and any later supersession so a teammate can reconstruct the reasoning without inventing authority the record does not have.
The downloadable pack includes an editable Markdown template, a completed fictional Markdown example, a matching JSON record, a closed JSON Schema, and a dependency-free validator with mutation and security tests. It is for concise operating and product decisions. Detailed architecture records, approval authority, roadmap prioritization, change authorization, and RAID ownership stay outside this article.
Build a decision record from context to later review
Keep each record small enough to maintain and complete enough to reconstruct. Begin with the bounded question and responsible owner, preserve the alternatives and evidence available at the time, then make consequences and future review visible.
Bound the decision and name its owner
Assign a stable decision ID, sequence, title, status, and decision owner. State the narrow choice being recorded and the organizational boundary it belongs to. A name in the log identifies accountability for the record; it does not grant approval or change authority.
Sources: [decision-log-pack], [microsoft-decision-log]
State the context without hiding the question
Describe the constraint, observation, or need that made a choice necessary. Keep architecture rationale depth in an architecture decision record, roadmap scoring in the roadmap process, and RAID items in their canonical register instead of turning one log entry into every project artifact.
Sources: [decision-log-pack], [microsoft-decision-log]
Preserve options and evidence available at the time
List at least two real options with their tradeoffs, then link the research, test result, constraint, or stakeholder input reviewed before the choice. Microsoft Engineering Fundamentals treats consideration of alternatives as part of design review. Keep evidence references minimum-purpose and outside the pack when they are sensitive.
Record the choice, rationale, consequences, and review
Name the selected option, decision, rationale, date, expected benefits, accepted costs, follow-up actions, and a concrete review trigger. The current pack uses a closed Draft 2020-12 schema so unknown fields fail instead of silently widening the record.
Sources: [decision-log-pack], [microsoft-decision-log], [json-schema-2020-12]
Preserve supersession instead of rewriting history
When new evidence changes an active choice, add a later decision and link both directions: the new entry names what it supersedes, and the older entry names what superseded it. Keep the original context, date, owner, evidence, and consequences intact so the change remains reviewable.
Sources: [decision-log-pack], [microsoft-decision-log], [microsoft-design-reviews]
What this decision log template owns
Use the pack for concise, dated records of bounded operating and product choices. It owns the reasoning trail and maintenance contract, not the authority or adjacent governance process that permits work to proceed.
Included
- Controlled log identity, status, version, dates, organization boundary, log owner, named decision owners and reviewers, review cadence, triggers, and version history
- Three fictional decisions with stable sequence and status, two options each, five linked evidence records, selected options, rationale, decision dates, and consequences expressed as expected benefits and accepted costs
- Three follow-up actions with owners, due dates, status, and evidence references plus review dates, triggers, reviewers, outcomes, and review evidence
- One complete reciprocal supersession in which DEC-003 supersedes DEC-001 without deleting or rewriting the earlier choice
- Editable Markdown, matching fictional JSON, closed Draft 2020-12 schema, strict dependency-free validator, seventy-three mutation and security tests, and deterministic ZIP build
Not included
- Detailed architecture decision record depth, system architecture rationale, architecture governance, or replacement of an ADR repository
- Approval workflow authority, delegation of authority, an authority matrix, sign-off, or permission to make or implement a real decision
- Roadmap scoring, sequencing, prioritization, capacity allocation, product strategy approval, or commitment of delivery dates
- Change request approval, implementation authorization, release approval, deployment, rollback execution, or proof that a change occurred
- Ownership of RAID risks, assumptions, issues, and dependencies; legal, security, privacy, or compliance decisions; certification; or any guarantee that a decision is correct or successful
DOWNLOADABLE RESOURCE
Download the decision log template pack
The ZIP packages the editable template with a completed fictional log, matching machine-readable record, closed schema, validator, tests, and deterministic build script. Rebuild it locally to verify the exact allowlist and archive bytes.
Decision log template pack
A concise, provider-neutral log for decision context, options, evidence, choice, date, owner, consequences, review, follow-up, and supersession.
Format: Markdown, JSON, JSON Schema, and dependency-free Node.js validator/tests in one ZIP
Locally reproduced August 1, 2026. SHA-256: b83d355f9cb262c6d29b297c2a4d4629bb32c49e5d4fab1d1d142c2c0477eeee
Included
- Editable Markdown template and completed fictional Cedar Vale Workshops example with four owner roles, five evidence records, three decisions, and two options per decision
- Matching JSON with three follow-up actions, three review records, one reciprocal supersession, maintenance history, and seven explicit false boundary flags
- Closed Draft 2020-12 JSON Schema, strict dependency-free validator, seventy-three mutation and security tests, README, package commands, and deterministic allowlisted ZIP builder
Verification boundary
The nine allowlisted source files were reproduced across four time zones, extracted, byte-compared, and validated locally with fixed UTC archive timestamps. This proves deterministic artifact structure and internal consistency, not public availability before deployment, source-evidence truth, decision authority, approval, implementation, prioritization, compliance, or outcome.
Three bounded decision-log entry shapes
Adapt the entry to the choice being preserved while keeping options, evidence, owner, consequences, review, and later status explicit. Split adjacent architecture, approval, prioritization, change, and RAID work into their separately owned records.
Product or operating choice with later supersession
Use when: A team needs to preserve a bounded workflow choice and expects later observations may justify a replacement.
The fictional pack first records one exact requested start time, then preserves new research, a time-zone test, and operations input before a later entry supersedes that choice with a preference range and explicit time zone.
Structure
- Original context, two options, selected option, evidence, decision date, owner, expected benefit, accepted cost, review trigger, and follow-up action
- Later decision with new evidence, its own options and consequences, plus reciprocal supersedes and superseded-by links
Watch for: A supersession link preserves history; it does not authorize implementation or prove the newer option performs better in a real environment.
Sources: [decision-log-pack], [microsoft-decision-log], [microsoft-design-reviews]
Service or process policy choice
Use when: A team chooses between two bounded operating behaviors and needs the reviewed constraint and accepted cost to remain visible.
Record the current service boundary, at least two policy options, evidence for the constraint, the selected behavior, its operational cost, one owner, and the condition that would reopen the choice.
Structure
- One concise policy question with options, tradeoffs, linked constraint or test evidence, selected option, date, and owner
- Expected benefit, accepted cost, follow-up action, review date, trigger, reviewer, and outcome status
Watch for: Do not use the entry as an authority matrix, approval workflow, change request, or container for access credentials and private operational evidence.
Sources: [decision-log-pack], [microsoft-decision-log], [json-schema-2020-12]
Temporary choice with an explicit review trigger
Use when: Incomplete evidence or a temporary constraint requires a reversible choice that must be revisited on a date or observable event.
State what is temporarily acceptable, which evidence is missing, what cost is knowingly accepted, who owns the follow-up, and the exact date or evidence event that starts a new review.
Structure
- Temporary context, available options, present evidence, selected option, rationale, owner, date, consequences, and open follow-up
- Specific review trigger, review date, named reviewer, pending outcome, and a later supersession path if the choice changes
Watch for: A future date alone does not cause review. Keep the named owner, evidence reference, and follow-up visible in the team system that actually manages the work.
Sources: [decision-log-pack], [microsoft-design-reviews], [json-schema-2020-12]
Decide whether an entry is ready for human review
Structural readiness means another reviewer can reconstruct the question, alternatives, evidence, choice, ownership, consequences, and next review. The validator cannot decide whether evidence is true or whether the owner has authority.
The entry states only a conclusion and omits the context, alternative options, evidence, selected option, rationale, date, or named owner.
Choose: Keep the entry in draft and reconstruct the minimum reasoning trail before treating it as a maintained decision record.
Tradeoff: The record takes longer to complete, but a future reader can distinguish a reviewed choice from an undocumented instruction.
An evidence reference is missing, sensitive, unowned, stale, or cannot be resolved in the authorized evidence system.
Choose: Preserve the gap and route it to the evidence and decision owners instead of copying protected material into the log.
Tradeoff: The entry remains visibly incomplete, but minimum-purpose references avoid turning the pack into a second evidence repository.
A later choice replaces an earlier one but only one side of the supersession relationship is recorded.
Choose: Link both directions, keep the earlier entry intact, and give the later entry a higher sequence and its own date, evidence, owner, and consequences.
Tradeoff: Maintenance requires one extra reciprocal update, but the active choice and historical reasoning remain unambiguous.
The work needs architecture depth, formal approval, roadmap priority, change authorization, or RAID management.
Choose: Keep the concise decision entry as a pointer and use the separate canonical record and accountable owner for the adjacent job.
Tradeoff: There are more explicit handoffs, but one lightweight log cannot silently become an authority system or every project-control artifact.
Make decisions reviewable
Turn the decision record into a bounded internal workflow
Describe the options, evidence references, ownership, review triggers, follow-up queue, and supersession history your team needs. Playcode can build the internal software around that process without becoming the approval, architecture, roadmap, change, or RAID authority.
Explore internal toolsThe downloadable template and this ordinary informational article do not grant AI signup credits.
Use the change request template when a decision requires controlled implementationThe decision record preserves reasoning; the separately authorized change record owns approval and execution control.
What this template cannot prove
The pack validates closed fictional records, cross-references, sequence, review fields, and supersession consistency. It cannot observe the real deliberation, evidence, organization, owner directory, implementation, or result.
- The Cedar Vale Workshops organization, scheduling workflow, roles, evidence, options, decisions, dates, consequences, reviews, and actions are fictional demonstration data.
- A valid evidence reference does not prove the referenced research, test result, constraint, or stakeholder input exists, is complete, is current, or supports the stated choice.
- A named owner does not establish delegated authority, approval, consent, sign-off, access, change authorization, legal review, security review, privacy review, or compliance review.
- The concise record does not replace a detailed architecture decision record, roadmap process, change request, implementation plan, release record, or RAID register.
- The validator cannot determine whether the selected option was reasonable, the consequences occurred, a review happened, a change was implemented, or a decision produced the intended outcome.
- This ordinary informational article and its download do not grant AI signup credits. Eligibility, if any, belongs to separately qualified commercial entry pages.
Sources and verification record
The same-release artifact is the direct source for its fictional records and tests. Current Microsoft Engineering Fundamentals guidance supports dated decision records, context, decisions, consequences, alternatives, and review traceability. JSON Schema defines the machine-readable validation vocabulary used by the pack.
[decision-log-pack] Playcode:Decision log fictional example
Checked August 1, 2026. Supports: The locally reviewed four owner roles, five evidence records, three decisions, six options, three follow-up actions, three review records, one reciprocal supersession, seventy-three tests, explicit false boundary flags, and exact artifact hash. Public availability remains unverified until deployment.
[microsoft-decision-log] Microsoft Engineering Fundamentals:Decision Log
Checked August 1, 2026. Supports: Current guidance for preserving decision context, the decision, consequences, date and ownership metadata, status, and superseded history. It distinguishes concise decision records from deeper architecture decision records and does not prescribe this exact pack.
[microsoft-design-reviews] Microsoft Engineering Fundamentals:Design Reviews
Checked August 1, 2026. Supports: Current guidance for examining alternatives, implications, feedback, and decision traceability during design review. It supports reviewable reasoning, not approval authority or this exact template structure.
[json-schema-2020-12] JSON Schema:JSON Schema Draft 2020-12
Checked August 1, 2026. Supports: The current Draft 2020-12 specification family and metaschema identifier used by the downloadable closed schema. Schema validation checks representation, not evidence truth or organizational authority.
Decision log template questions
What files are included in the decision log template?
The ZIP includes an editable Markdown template, completed fictional Markdown example, matching JSON decision log, closed Draft 2020-12 JSON Schema, dependency-free validator, seventy-three mutation and security tests, README, package commands, and deterministic allowlisted ZIP builder.
What is the difference between a decision log and an ADR?
This decision log keeps a concise cross-functional record of context, options, evidence, choice, owner, consequences, review, and supersession. An architecture decision record usually carries deeper system context, architecture alternatives, technical constraints, and architecture rationale. Link the records when both are needed rather than forcing one to replace the other.
Should a decision log include options that were not selected?
Yes. Record the real options considered and their tradeoffs so a future reviewer can understand the choice in context. The pack requires at least two options and links the selected option by stable ID. It does not require copying sensitive deliberations or protected evidence into the log.
How should a superseded decision be recorded?
Keep the earlier record, change its status to superseded, identify the later decision, and make the later entry point back to what it supersedes. Preserve both dates, owners, evidence, rationale, consequences, and the reason for replacement instead of rewriting the original choice.
Does a decision log approve work or authorize a change?
No. A log records what was decided and by whom according to the source record. It does not create delegated authority, approve implementation, authorize a change, prioritize a roadmap, replace an approval workflow, or prove that work occurred.
Does the template manage risks, compliance, or decision outcomes?
No. RAID risks, assumptions, issues, and dependencies stay in their canonical register. Legal, security, privacy, and compliance review stay with authorized owners. Passing validation does not grant compliance, certify correctness, guarantee an outcome, or grant AI signup credits.
Build the workflow around the log
Create the tool your team uses to review choices and supersession
Start with the fictional pack, replace it with approved minimum-purpose records and authorized evidence references, then describe the decision-review workflow you want Playcode to build and run.
Build an internal toolNamed humans still own architecture, approvals, roadmap priorities, change authorization, RAID records, evidence review, legal and compliance decisions, and every real outcome.