Decision Log: [Project Name]

This template defines the format for decision log documents used in design and planning sessions. See Complex Project Planning for the workflow that produces this document.

A decision log captures open questions, design alternatives, and their resolutions during iterative planning sessions. It serves as a structured dialog between the engineer proposing a design and the reviewers, ensuring all ambiguities are surfaced, evaluated, and recorded before implementation begins.

When to Create a Decision Log

Create a decision log whenever:

A design or planning session surfaces 3+ open questions with multiple viable options.
A project spans multiple repositories or components and requires coordination decisions.
You are following the Complex Project Planning workflow — a decision log is mandatory in that case.

For simpler projects with 0-2 straightforward choices, the lightweight Open Questions and Decisions table in specification.md (per the Project Planning Workflow) is sufficient.

Template

---
author: <!-- REPLACE: your name -->
title: "Decision Log: <!-- REPLACE: project name -->"
created: <!-- REPLACE: YYYY-MM-DD -->
---

# Decision Log: <!-- REPLACE: Project Name -->

## Purpose

<!-- REPLACE: 1-2 sentences explaining the scope of decisions being tracked. -->
<!-- Example: "Tracks design decisions for the Inventory Component Endpoint,
covering the API contract, data model, and error handling strategy." -->

## Decision Table

| #      | Question                         | Status | Decision | Round |
| ------ | -------------------------------- | ------ | -------- | ----- |
| DQ-001 | <!-- REPLACE: short question --> | Open   |          | R1    |
| DQ-002 |                                  |        |          |       |

---

## Round 1: <!-- REPLACE: Round Title, e.g., "Initial Design Questions" -->

### DQ-001: <!-- REPLACE: Question Title -->

**Context**: <!-- REPLACE: Why this question matters and what it affects. -->

| Option | Description                                                  | Trade-offs                      |
| ------ | ------------------------------------------------------------ | ------------------------------- |
| A      | <!-- REPLACE: description -->                                | <!-- REPLACE: pros and cons --> |
| B      | <!-- REPLACE: description -->                                | <!-- REPLACE: pros and cons --> |
| C      | <!-- REPLACE: description (add or remove rows as needed) --> |                                 |

**Recommendation**: Option <!-- REPLACE: X --> — <!-- REPLACE: rationale in 1-2 sentences -->

**Decision**: <!-- REPLACE: Filled by reviewer — chosen option + any modifications -->

**Applied to**: <!-- REPLACE: List of documents and sections updated when this decision is applied -->

---

### DQ-002: <!-- REPLACE: Question Title -->

<!-- (Repeat DQ structure for each question in the round.) -->

---

## Round 2: <!-- REPLACE: Round Title, e.g., "Follow-up Questions from Round 1" -->

<!-- New questions surfaced after applying Round 1 decisions. -->

### DQ-00N: <!-- REPLACE: Question Title -->

<!-- (Continue global DQ numbering across all rounds.) -->

---

__________
Copyright: (c) Arda Systems 2025-2026, All rights reserved

Conventions

Numbering

Questions use a global sequence: DQ-001, DQ-002, etc., across all rounds. Do not restart numbering in each round.
Rounds are numbered sequentially: Round 1, Round 2, etc.
New questions added in later rounds continue the global DQ sequence.

Status Values

Status	Meaning
Open	Awaiting reviewer decision
Decided	Reviewer has chosen an option
Deferred	Consciously postponed to a later phase
Superseded	Replaced by a later decision (reference the replacing DQ number)

Options Table

Each question must present at least two options (A and B). Each option must include:

A concise description of the approach.
Trade-offs covering: complexity, maintainability, backward compatibility, testing implications, and any cross-repo impacts.

Recommendation

Every question must include a recommendation with rationale. The reviewer may override the recommendation — this is expected. The recommendation exists to frame the trade-off and give reviewers a starting point, not to prejudge the outcome.

Traceability

When a decision is applied, list every document and section that was updated in the Applied to field. Use workspace-root path references:

**Applied to**:
- [Design Document](./design.md) § Class Diagram, § Sequence Diagram
- [Project Plan](./project-plan.md) § Phase 2, Task T-05

This traceability is what makes the decision log useful months later when engineers need to understand why the design looks the way it does.

Round Transitions

After all decisions in a round are applied to the design and plan documents:

Update the Decision Table at the top (set Status to Decided, fill the Decision column).
Review the updated documents for new ambiguities.
If new questions arise, add a new round section with the new DQ entries.
If no new questions arise, the decision log is complete.

Integration with Other Documents

Document	Relationship
`design.md`	Design choices reference DQ numbers inline (e.g., “Per DQ-003, we use…”) and in the Decision Summary table
`project-plan.md`	Task dependencies and phase ordering may be influenced by decisions; reference DQ numbers in tasks affected by decisions
`specification.md`	For simpler projects, the Open Questions and Decisions table in the specification is a lightweight alternative to a full decision log