4DDR Template

This is the standard template for creating 4D Decision Records. Use this template for decisions across all four GISE phases: Discover, Design, Develop, and Deploy.

Template File

Copy and customize this template for your 4DDRs:

---
id: 4DDR-NNNN
status: proposed
phase: [discover|design|develop|deploy]
decision: "Brief, clear statement of the decision"
context: "Why this decision is needed, background situation"
consequences: "Known impacts, trade-offs, and implications"
alternatives: ["Option 1", "Option 2", "Option 3"]
author: "Your Name or Team"
date: "YYYY-MM-DD"
tags: ["tag1", "tag2", "tag3"]
---

# 4DDR-NNNN: [Decision Title]

## Background

Provide context about why this decision is necessary. What problem are we solving? What constraints or requirements led to this decision point?

## Decision

State the decision clearly and concisely. What exactly have we decided to do?

## Rationale

Explain why this decision was made. What factors were most important? How does this align with project goals?

## Alternatives Considered

List and briefly describe the main alternatives that were evaluated:

- **Option 1**: Brief description and why it was rejected
- **Option 2**: Brief description and why it was rejected  
- **Option 3**: Brief description and why it was rejected

## Implementation

How will this decision be implemented? What are the next steps?

- [ ] Step 1
- [ ] Step 2
- [ ] Step 3

## Success Criteria

How will we know this decision was successful? What metrics or outcomes will we track?

## Review Date

When should this decision be reviewed or validated?

**Next Review**: YYYY-MM-DD

## Related Decisions

Link to related 4DDRs or other relevant documentation:

- 4DDR-XXXX: [Related Decision Title](./4ddr-xxxx-title.md)
- [External Document Title](https://link-to-document.com)

Field Definitions

Required Fields

Field	Description	Example
id	Unique identifier following 4DDR-NNNN format	4DDR-0042
status	Current decision status	proposed, accepted, superseded, deprecated, archived
phase	GISE phase where decision applies	discover, design, develop, deploy
decision	Clear, one-sentence decision statement	"Use PostgreSQL for primary data storage"
context	Why this decision is needed	"Need ACID compliance for financial transactions"
consequences	Known impacts and trade-offs	"Requires PostgreSQL expertise on team, increases infrastructure complexity"
date	When decision was made	2025-07-22 (ISO 8601 format)

Optional Fields

Field	Description	Example
alternatives	Options considered but rejected	["MongoDB", "MySQL", "SQLite"]
author	Who made or proposed the decision	"Database Architecture Team"
tags	Keywords for categorization	["database", "architecture", "storage"]
approved-by	Who approved the decision	"CTO, Lead Architect"
approved-date	When decision was approved	2025-07-24
review-date	When to review this decision	2025-10-22

Status-Specific Fields

For Superseded Decisions

status: superseded
superseded-by: 4DDR-0055-new-decision.md
superseded-date: 2025-09-15
superseded-reason: "Requirements changed due to compliance needs"

For Deprecated Decisions

status: deprecated
deprecated-date: 2025-08-01
deprecated-reason: "Technology end-of-life announced"
migration-plan: "docs/migration-guide.md"
expected-retirement: 2025-12-31

Usage Guidelines

1. Keep It Concise

• Aim for one screen of content (including frontmatter)
• Use bullet points instead of long paragraphs
• Focus on essential information only

2. Use Clear Language

• Write for future developers who weren't involved in the decision
• Avoid jargon and abbreviations without context
• Be specific about constraints and requirements

3. Link Related Decisions

• Reference other 4DDRs that influenced this decision
• Link to 4DDRs that this decision supersedes
• Cross-reference with relevant documentation

4. Update Status Appropriately

• Start with proposed for new decisions
• Change to accepted after approval
• Use superseded when replaced by newer decision
• Use deprecated when phasing out gradually

Phase-Specific Considerations

Discover Phase

• Focus on research methods, user insights, requirements gathering
• Context often involves user needs or market research
• Consequences may include timeline and resource impacts

Design Phase

• Emphasize architectural choices, technical approaches
• Context includes technical constraints and requirements
• Consequences focus on implementation complexity and maintainability

Develop Phase

• Cover development practices, tools, testing approaches
• Context involves team capabilities and project constraints
• Consequences include code quality and delivery impacts

Deploy Phase

• Address infrastructure, deployment, and operational decisions
• Context includes performance, security, and scalability needs
• Consequences focus on operational overhead and reliability

Quality Checklist

Before finalizing a 4DDR, ensure:

• Clear decision statement - Can someone understand what was decided in one sentence?
• Sufficient context - Is it clear why this decision was necessary?
• Realistic consequences - Are the impacts and trade-offs honestly assessed?
• Appropriate alternatives - Were reasonable options considered?
• Actionable next steps - Is it clear how to implement this decision?
• Proper categorization - Are phase and tags accurate?
• Valid YAML - Does the frontmatter parse correctly?
• Consistent format - Does it follow the template structure?

Integration with Development Workflow

Pull Request Integration

Include 4DDR creation/updates in your PR process:

## Decision Records
This PR includes the following 4DDR changes:
- [x] 4DDR-0042: Use PostgreSQL for data storage (new)
- [x] 4DDR-0015: Database choice (superseded by 0042)

Code Review Checklist

• Decision aligns with implementation
• All affected stakeholders reviewed 4DDR
• Related 4DDRs updated appropriately
• Template format followed correctly

Examples by Phase

Discover Example

---
id: 4DDR-0001
status: accepted
phase: discover
decision: "Use qualitative interviews for user research"
context: "Limited budget, unknown user needs for MVP"
consequences: "Deeper insights but smaller sample size"
alternatives: ["Quantitative surveys", "A/B testing"]
author: "Product Research Team"
date: "2025-07-15"
tags: ["user-research", "mvp", "qualitative"]
---

Design Example

---
id: 4DDR-0012
status: accepted
phase: design
decision: "Implement Clean Architecture pattern"
context: "Need testable, maintainable codebase for long-term project"
consequences: "More upfront structure, easier testing and changes"
alternatives: ["MVC", "Layered Architecture", "Hexagonal Architecture"]
author: "Software Architecture Team"
date: "2025-07-18"
tags: ["architecture", "patterns", "maintainability"]
---

Develop Example

---
id: 4DDR-0025
status: accepted
phase: develop
decision: "Adopt TypeScript for all new JavaScript code"
context: "Reducing runtime errors, improving code maintainability"
consequences: "Learning curve, build complexity, better IDE support"
alternatives: ["JavaScript with JSDoc", "Flow", "Continue with vanilla JS"]
author: "Frontend Development Team"
date: "2025-07-20"
tags: ["typescript", "code-quality", "frontend"]
---

Deploy Example

---
id: 4DDR-0038
status: accepted
phase: deploy
decision: "Use blue-green deployment strategy"
context: "Need zero-downtime deployments for production system"
consequences: "Double infrastructure cost, complex traffic routing"
alternatives: ["Rolling deployment", "Canary deployment", "Recreate deployment"]
author: "DevOps Team"
date: "2025-07-25"
tags: ["deployment", "zero-downtime", "infrastructure"]
---

Automation and Tooling

Template Generation

Create a script to generate new 4DDRs from template:

#!/bin/bash
# generate-4ddr.sh
NEXT_ID=$(find .gise/4ddr -name "*.md" | wc -l | awk '{printf "%04d", $1+1}')
TEMPLATE_FILE=".gise/templates/4ddr-template.md"
NEW_FILE=".gise/4ddr/4ddr-${NEXT_ID}-${1}.md"

cp "$TEMPLATE_FILE" "$NEW_FILE"
sed -i "s/4DDR-NNNN/4DDR-${NEXT_ID}/g" "$NEW_FILE"
sed -i "s/YYYY-MM-DD/$(date +%Y-%m-%d)/g" "$NEW_FILE"

echo "Created: $NEW_FILE"

Validation Script

#!/bin/bash
# validate-4ddr.sh
for file in .gise/4ddr/*.md; do
  if ! yq eval '.id' "$file" > /dev/null 2>&1; then
    echo "❌ Invalid YAML in $file"
    exit 1
  fi
done
echo "✅ All 4DDRs validated"

This template provides a solid foundation for creating consistent, useful 4DDRs across all phases of your GISE projects.