04 Decision Records

Decision Records

Purpose

This document explains the decision record process used across the organization to document significant architectural and structural decisions.

What is a Decision Record?

A decision record is a document that captures an important architectural decision made along with its context and consequences.

Key Characteristics

• Immutable: Once approved, decisions are not edited (create new decision to supersede)
• Numbered: Sequential numbering (01, 02, etc.)
• Contextual: Includes the circumstances that led to the decision
• Traceable: Links to related decisions and documents

When to Create a Decision

Create a decision when making decisions about:

Technical Architecture

• Technology stack choices (languages, frameworks, platforms)
• System design patterns and approaches
• Integration strategies and protocols
• Data architecture and storage solutions
• Security architecture decisions

Organizational Structure

• Changes to guild or practice structure
• Modifications to governance models
• Value stream design decisions
• Process framework selections

Significant Standards

• Coding standards and conventions
• Documentation standards
• Tooling selections
• Workflow definitions

When NOT to Create a Decision

Don’t create decisions for:

• Routine implementation details
• Temporary or experimental choices
• Individual project decisions with no broader impact
• Decisions easily reversed without consequence

Decision Template

Use the template at content/_authoring/templater/TMP00 Create Decision.md:

---
page-status: active
created: YYYY-MM-DD
owner: [guild-slug]
type: decision
decision-number: "XX"
decision-status: [Proposed|Accepted|Deprecated|Superseded]
---
 
# Decision XX [Short Title]
 
## Status
 
[Proposed | Accepted | Deprecated | Superseded by Decision XX]
 
## Context
 
What is the issue that we're seeing that is motivating this decision or change?
 
## Decision
 
What is the change that we're proposing and/or doing?
 
## Consequences
 
What becomes easier or more difficult to do because of this change?
 
### Positive
 
- [Benefit 1]
- [Benefit 2]
 
### Negative
 
- [Trade-off 1]
- [Trade-off 2]
 
### Neutral
 
- [Implication 1]
 
## Alternatives Considered
 
What other options were considered?
 
### Alternative 1: [Name]
 
- **Description:** [What it is]
- **Pros:** [Benefits]
- **Cons:** [Drawbacks]
- **Why not chosen:** [Reason]
 
## Related Decisions
 
- [[XX Title]] - [Relationship]
- [[Relevant Process or Policy]] - [Relationship]
 
## Notes
 
Any additional information, references, or discussion points.
 
---
 
**Date:** YYYY-MM-DD  
**Decided By:** [Name/Role]  
**Approved By:** [Name/Role]

Decision Lifecycle

1. Proposed

• Decision is drafted and submitted for review
• Status: Proposed
• Open for discussion and feedback

2. Accepted

• Decision has been approved and is now in effect
• Status: Accepted
• Team must follow this decision

3. Deprecated

• Decision is no longer relevant or enforced
• Status: Deprecated
• Retained for historical reference

4. Superseded

• A new decision has replaced this one
• Status: Superseded by Decision XX
• Link to the superseding decision

Numbering Convention

Decisions are numbered sequentially:

Format: XX [Title].md

Examples:

• 01 Use TypeScript for Frontend.md
• 02 Adopt Microservices Architecture.md
• 03 Use PostgreSQL for Primary Database.md

Numbering Rules:

• Numbers are sequential: 01, 02, 03…
• Never reuse numbers (even if a decision is deprecated)
• Zero-pad numbers: 01 not 1

Where to Store Decisions

Decisions are stored in the Decisions/ folder at the guild level:

content/02 Guilds/
└── GL04 Technology Guild/
    └── Decisions/
        ├── 01 Use Kubernetes for Orchestration.md
        ├── 02 Adopt GitOps with ArgoCD.md
        └── 03 Use PostgreSQL for State Storage.md

Cross-Practice Decisions:

• If decision impacts multiple practices, create the decision in the owning guild’s Decisions/ folder
• Link from other affected practices’ Overview files or documentation

Company-Wide Decisions:

• Store in content/00 Governance/Decisions/
• These affect the entire organization

Review and Approval

Guild-Level Decisions

1. Draft: Author creates decision using template
2. Review: Guild Lead reviews with relevant stakeholders
3. Approval: Guild Lead approves (or escalates to Leadership Team)
4. Merge: Decision is merged and status set to Accepted

Company-Level Decisions

1. Draft: Author creates decision using template
2. Review: Leadership Team reviews
3. Approval: Leadership Team approves
4. Merge: Decision is merged and status set to Accepted

Superseding a Decision

When a decision changes:

1. Create new decision with updated decision
2. Link from old decision: Add “Superseded by XX Title” to status
3. Update old decision status: Change to Superseded by Decision XX
4. Don’t edit old decision: Keep original decision context intact

Example:

## Status
 
Superseded by [[05 Migrate to React from Vue]]
 
Date Superseded: 2026-01-15

Best Practices

Be Concise

• Keep decisions focused on one decision
• Use clear, direct language
• Avoid unnecessary jargon

Provide Context

• Explain why the decision was needed
• Document constraints and requirements
• Include relevant background

Document Alternatives

• Show what was considered
• Explain why alternatives weren’t chosen
• Helps future readers understand the decision

Update Status Promptly

• When superseding, update both decisions
• Mark deprecated decisions clearly
• Keep status section current

Link Related Content

• Reference related decisions
• Link to relevant processes or policies
• Connect to implementation documentation

Example Decision

See Decision 01 for an example of a well-formed decision.

Related Resources

• How to Contribute
• Knowledge Standards
• Decision Template

---

Version: 1.0
Last Updated: 2026-02-11
Maintained By: Leadership Team