What is a 4D Decision Record (4DDR)?
A 4D Decision Record (4DDR) is a lightweight document that captures the context, rationale, and consequences of decisions made during any phase of the GISE methodology.
Definition
Unlike traditional Architecture Decision Records (ADRs) that focus primarily on technical architecture, 4DDRs document decisions across all four phases:
- Discover: User research methods, requirements gathering approaches, stakeholder engagement strategies
- Design: Architecture choices, API design patterns, data models, security approaches
- Develop: Development practices, testing strategies, code quality standards, tooling decisions
- Deploy: Infrastructure choices, deployment strategies, monitoring approaches, operational procedures
Anatomy of a 4DDR
Each 4DDR contains structured information that makes it both human-readable and machine-parseable:
Status: Accepted
Phase: Design
Decision: Adopt Next.js 15 + React Server Components
Context: Need SSR for SEO, small team with React skills
Consequences: Locks us to Node ≥18, Turbopack for local dev
Alternatives: Angular 18, SvelteKit
Date: 2025-07-22
Required Fields
| Field | Description | Example |
|---|---|---|
| Status | Current state of the decision | Proposed, Accepted, Superseded, Deprecated |
| Phase | Which GISE phase this decision belongs to | Discover, Design, Develop, Deploy |
| Decision | Clear, concise statement of what was decided | "Use PostgreSQL for primary data storage" |
| Context | Why this decision was necessary | "Need ACID compliance for financial transactions" |
| Consequences | Known impacts and trade-offs | "Requires PostgreSQL expertise on team" |
| Date | When the decision was made | ISO 8601 format: 2025-07-22 |
Optional Fields
| Field | Description | Example |
|---|---|---|
| Alternatives | Options that were considered but rejected | "MongoDB, SQLite, MySQL" |
| Author | Who made or proposed the decision | "Jane Smith" |
| Stakeholders | Who was involved in the decision | "Frontend team, DevOps, Product Owner" |
| Links | Related documents, tickets, or PRs | "PR #123, ADR-0001" |
Decision Scope
4DDRs should capture decisions that:
- Change system constraints (performance, security, cost, scope)
- Affect multiple team members or future developers
- Have long-term implications beyond the current feature
- Involve trade-offs between competing options
- Impact compliance or regulatory requirements
Examples by Phase
Discover Phase
Status: Accepted
Phase: Discover
Decision: Use qualitative interviews over quantitative surveys
Context: Building MVP with unknown user needs, limited budget
Consequences: Deeper insights but smaller sample size
Date: 2025-07-15
Design Phase
Status: Accepted
Phase: Design
Decision: Implement Clean Architecture with hexagonal ports
Context: Need testability and future framework flexibility
Consequences: More upfront structure, easier to test and change
Alternatives: MVC, Layered Architecture
Date: 2025-07-18
Develop Phase
Status: Accepted
Phase: Develop
Decision: Adopt Conventional Commits with automated changelog
Context: Multiple developers, need clear release notes
Consequences: Commit message discipline required, automated releases
Date: 2025-07-20
Deploy Phase
Status: Accepted
Phase: Deploy
Decision: Blue-green deployment with 30-second rollback capability
Context: Cannot afford downtime, need fast recovery
Consequences: Double infrastructure cost, complex traffic routing
Date: 2025-07-25
When NOT to Create a 4DDR
Avoid creating 4DDRs for:
- Obvious technical choices with no reasonable alternatives
- Temporary decisions that will be revisited soon
- Individual preferences that don't affect the team
- Implementation details that can change without impact
- Standard practices that are already documented elsewhere
Integration with Development Workflow
4DDRs work best when integrated into your existing development process:
- During Planning: Identify decisions that need 4DDRs
- In Pull Requests: Include 4DDR creation/updates
- Code Review: Validate that 4DDRs match implementation
- Retrospectives: Review and update outdated 4DDRs
Relationship to Other Artifacts
4DDRs complement but don't replace other documentation:
- Technical Specifications: 4DDRs explain "why", specs explain "what"
- API Documentation: 4DDRs capture design rationale, APIs document usage
- User Stories: 4DDRs document solution decisions, stories capture requirements
- Code Comments: 4DDRs explain strategic decisions, comments explain tactical choices
The goal is to create a decision paper trail that helps future developers (including your future self) understand not just what the system does, but why it was built that way.