4DDR Patterns & Best Practices

This guide provides proven patterns for implementing 4D Decision Records effectively across different project types, team sizes, and organizational contexts.

Common 4DDR Patterns

Pattern 1: Decision Chain Pattern

Used when decisions build upon each other across phases:

Example Implementation:

# 4DDR-001 (Discover Phase)
decision: "Conduct user interviews with 12 small business owners"
context: "Need to understand accounting workflows for fintech app"

# 4DDR-005 (Discover Phase)
decision: "Target freelancers and small businesses with <10 employees"
context: "User interviews revealed this segment has specific pain points"
related-decisions: ["4DDR-001"]

# 4DDR-012 (Design Phase)
decision: "Implement OAuth 2.0 with social login options"
context: "Target users prefer not to create new accounts, based on 4DDR-005 findings"
related-decisions: ["4DDR-001", "4DDR-005"]

Pattern 2: Technology Stack Pattern

Coordinated decisions about technology choices:

# Core Stack Decision
---
id: 4DDR-010
phase: design
decision: "Use TypeScript/Node.js full-stack architecture"
context: "Team has JavaScript expertise, need type safety for complex business logic"
consequences: "Unified language across stack, build complexity, learning curve"
---

# Frontend Framework Decision
---
id: 4DDR-011
phase: design
decision: "Use Next.js for frontend framework"
context: "Need SSR for SEO, integrates well with 4DDR-010 TypeScript choice"
depends-on: ["4DDR-010"]
---

# Backend Framework Decision
---
id: 4DDR-013
phase: design
decision: "Use NestJS for backend API framework"
context: "Provides structure for TypeScript backend, matches 4DDR-010 decision"
depends-on: ["4DDR-010"]
---

Pattern 3: Superseding Pattern

Managing decision evolution over time:

# Original Decision
---
id: 4DDR-020
status: superseded
phase: design
decision: "Use MySQL for primary database"
context: "Team familiarity, simple relational needs"
superseded-by: "4DDR-035"
superseded-date: "2025-08-15"
superseded-reason: "Requirements changed to include complex JSON queries"
---

# Superseding Decision
---
id: 4DDR-035
status: accepted
phase: design
decision: "Use PostgreSQL with JSONB support"
context: "Need complex JSON queries for user preference data, based on new requirements"
supersedes: "4DDR-020"
migration-plan: "Database migration scheduled for Sprint 8"
---

Phase-Specific Patterns

Discover Phase Patterns

Research Method Selection Pattern

template_type: "research-decision"
common_fields:
  - research-budget: "$X,XXX"
  - participant-count: "N participants"
  - timeline: "X weeks"
  - deliverables: ["personas", "journey-maps", "requirements"]

Example:

---
id: 4DDR-003
phase: discover
decision: "Use mixed-method approach: interviews + analytics review"
context: "Need qualitative insights and quantitative validation for B2B SaaS"
research-budget: "$15,000"
participant-count: "8 interviews + 6 months analytics data"
timeline: "4 weeks"
deliverables: ["user-personas", "feature-priority-matrix", "usage-patterns"]
---

Stakeholder Alignment Pattern

template_type: "stakeholder-decision"
common_fields:
  - stakeholder-groups: ["business", "technical", "users"]
  - engagement-method: "workshops/interviews/surveys"
  - conflict-resolution: "how conflicts will be resolved"

Design Phase Patterns

Architecture Decision Pattern

template_type: "architecture-decision"
common_fields:
  - architectural-style: "monolith/microservices/modular-monolith"
  - scalability-target: "users/requests per second"
  - performance-requirements: "response time targets"
  - compliance-needs: ["GDPR", "SOC2", "HIPAA"]

API Design Pattern

template_type: "api-decision"
common_fields:
  - api-style: "REST/GraphQL/gRPC"
  - versioning-strategy: "header/URL/content-type"
  - authentication: "JWT/OAuth/API-key"
  - rate-limiting: "requests per minute/hour"

Develop Phase Patterns

Development Practice Pattern

template_type: "dev-practice-decision"
common_fields:
  - automation-level: "manual/semi-automated/fully-automated"
  - team-training-required: "hours of training needed"
  - productivity-impact: "expected velocity change"
  - quality-improvement: "metrics expected to improve"

Testing Strategy Pattern

template_type: "testing-decision" 
common_fields:
  - test-types: ["unit", "integration", "e2e", "performance"]
  - coverage-targets: "percentage targets by test type"
  - automation-tools: ["Jest", "Playwright", "k6"]
  - ci-integration: "how tests integrate with CI/CD"

Deploy Phase Patterns

Infrastructure Decision Pattern

template_type: "infrastructure-decision"
common_fields:
  - hosting-provider: "AWS/Azure/GCP/self-hosted"
  - cost-projection: "$X,XXX monthly"
  - scalability-limits: "maximum capacity"
  - sla-targets: "uptime/response time commitments"

Deployment Strategy Pattern

template_type: "deployment-decision"
common_fields:
  - deployment-method: "blue-green/canary/rolling/recreate"
  - rollback-capability: "time to rollback"
  - monitoring-requirements: "alerts and dashboards needed"
  - disaster-recovery: "backup and recovery procedures"

Organizational Patterns

Small Team Pattern (2-5 developers)

Characteristics:

• Informal decision-making process
• Direct communication
• Focus on essential decisions only

4DDR Approach:

# Simplified template for small teams
recommended_fields:
  - id, status, phase, decision, context, consequences, date
optional_fields:
  - alternatives (keep brief)
  - author (often unnecessary in small teams)
review_process: "informal peer review"
storage: "git-only approach"

Medium Team Pattern (6-20 developers)

Characteristics:

• Multiple feature teams
• Some specialization (frontend/backend)
• Need for coordination

4DDR Approach:

# Enhanced template for medium teams
required_fields:
  - id, status, phase, decision, context, consequences, alternatives, stakeholders, date
review_process: "tech lead approval required"
storage: "git with periodic database export"
governance: "monthly 4DDR review meetings"

Large Organization Pattern (20+ developers)

Characteristics:

• Multiple products/services
• Complex stakeholder landscape
• Formal governance requirements

4DDR Approach:

# Comprehensive template for large orgs
required_fields:
  - all standard fields plus compliance tags
approval_workflow: "architect review → stakeholder sign-off → implementation"
storage: "hybrid git + database with analytics"
governance: "architecture review board oversight"
compliance: "audit trail requirements"

Implementation Patterns

Bootstrap Pattern

For teams starting with 4DDRs:

Week 1-2: Foundation

1. Create 4DDR templates and basic tooling
2. Identify 3-5 recent decisions to retroactively document
3. Train team on 4DDR format and process

Week 3-4: Integration

1. Add 4DDR requirements to PR templates
2. Create first "live" 4DDRs for current decisions
3. Establish review and approval process

Week 5-8: Optimization

1. Gather team feedback on process friction
2. Optimize templates and tooling
3. Establish governance and maintenance routines

Migration Pattern

For teams with existing ADRs:

Migration Script Example:

#!/bin/bash
# migrate-adr-to-4ddr.sh
for adr in docs/adr/*.md; do
  # Extract ADR content
  title=$(grep "# ADR" "$adr" | head -1)
  
  # Create 4DDR frontmatter
  cat > "4ddr/$(basename $adr)" << EOF
---
id: 4DDR-$(printf "%03d" $counter)
status: accepted
phase: design  # Most ADRs are design decisions
decision: "$title"
context: "Migrated from $adr"
date: $(stat -c %y "$adr" | cut -d' ' -f1)
migrated-from: "$adr"
---
EOF
  
  # Append original content
  tail -n +2 "$adr" >> "4ddr/$(basename $adr)"
  counter=$((counter + 1))
done

Quality Patterns

Review Process Pattern

Review Checklist Pattern:

self_review:
  - [ ] Decision statement is clear and actionable
  - [ ] Context explains why decision is needed
  - [ ] Consequences are honest and comprehensive
  - [ ] Alternatives were genuinely considered

peer_review:
  - [ ] Technical feasibility validated
  - [ ] Integration with existing decisions checked
  - [ ] Implementation approach is sound
  - [ ] No major alternatives overlooked

stakeholder_review:
  - [ ] Business alignment confirmed
  - [ ] Resource requirements acceptable
  - [ ] Timeline is realistic
  - [ ] Risks are acceptable

Maintenance Pattern

Regular Maintenance Schedule:

weekly:
  - Review new/proposed 4DDRs
  - Update status of decisions under implementation

monthly:
  - Review accepted 4DDRs for staleness
  - Check for superseded decisions that need updating
  - Update related-decisions links

quarterly:
  - Comprehensive 4DDR database review
  - Archive deprecated decisions
  - Generate decision analytics reports

annually:
  - Full audit of decision outcomes
  - Process improvement based on lessons learned
  - Template updates and optimization

Anti-Patterns to Avoid

❌ Over-Documentation

Problem: Creating 4DDRs for every minor decision Solution: Focus on decisions that affect multiple people or have long-term impact

❌ Template Rigidity

Problem: Forcing every decision into the same template Solution: Adapt templates to decision types and organizational context

❌ Status Neglect

Problem: Never updating 4DDR status as decisions evolve Solution: Build status updates into regular team processes

❌ Isolation

Problem: Creating 4DDRs in isolation without stakeholder input Solution: Involve relevant stakeholders in decision documentation

❌ Implementation Disconnect

Problem: 4DDRs that don't match actual implementation Solution: Review 4DDRs during code review and retrospectives

Success Metrics

Track 4DDR effectiveness with these metrics:

Process Metrics

• 4DDR Creation Rate: Decisions documented vs. total decisions made
• Review Cycle Time: Time from draft to approval
• Update Frequency: How often 4DDRs are revisited and updated

Quality Metrics

• Decision Reversal Rate: Frequency of superseded decisions
• Implementation Alignment: How often implementation matches 4DDR
• Stakeholder Satisfaction: Team feedback on 4DDR usefulness

Business Metrics

• Onboarding Speed: Time for new team members to become productive
• Decision Confidence: Team confidence in technical decisions
• Technical Debt: Reduction in unplanned technical debt

Use these patterns as starting points and adapt them to your specific context, team size, and organizational needs. The key is consistency and continuous improvement based on what works for your team.