4DDR Lifecycle Management

Effective 4DDR lifecycle management ensures that decision records remain current, accurate, and valuable throughout a project's evolution.

Status Lifecycle

4DDRs follow a defined lifecycle with clear status transitions:

Status Definitions

Status	Description	When to Use
Proposed	Decision is under consideration	Initial draft, awaiting review/approval
Accepted	Decision is approved and active	Current, implemented decisions
Rejected	Decision was considered but not approved	Alternative that was evaluated but dismissed
Superseded	Decision replaced by a newer decision	When requirements change, better solution found
Deprecated	Decision is outdated but not yet replaced	Gradual phase-out, migration in progress
Archived	Decision is no longer relevant	Historical record, no longer applicable

Lifecycle Stages

1. Creation (Proposed)

When creating a new 4DDR:

Status: Proposed
Phase: Design
Decision: Implement OAuth 2.0 with PKCE for mobile authentication
Context: Mobile app needs secure authentication, considering security best practices
Consequences: Added complexity, need OAuth provider setup
Alternatives: Basic auth, JWT with refresh tokens
Author: Security Team
Date: 2025-07-22

Actions Required:

• Technical review by relevant team members
• Security/compliance review if applicable
• Stakeholder approval
• Implementation planning

2. Approval (Accepted)

Once approved, update the status:

Status: Accepted
Phase: Design
Decision: Implement OAuth 2.0 with PKCE for mobile authentication
Context: Mobile app needs secure authentication, considering security best practices
Consequences: Added complexity, need OAuth provider setup
Alternatives: Basic auth, JWT with refresh tokens
Author: Security Team
Approved-By: Tech Lead, Security Officer
Date: 2025-07-22
Approved-Date: 2025-07-24

Actions Required:

• Begin implementation
• Update related documentation
• Communicate to affected teams
• Schedule review checkpoints

3. Evolution (Superseding/Deprecating)

When circumstances change:

Superseding Example

Status: Superseded
Phase: Design
Decision: Implement OAuth 2.0 with PKCE for mobile authentication
Context: Mobile app needs secure authentication, considering security best practices
Consequences: Added complexity, need OAuth provider setup
Superseded-By: 4DDR-0025-auth0-integration.md
Superseded-Date: 2025-08-15
Superseded-Reason: Decided to use Auth0 instead of custom OAuth implementation

Deprecating Example

Status: Deprecated
Phase: Deploy
Decision: Use Jenkins for CI/CD pipeline
Context: Need automated build and deployment process
Consequences: Jenkins maintenance overhead, plugin management complexity
Deprecated-Date: 2025-09-01
Deprecated-Reason: Migrating to GitHub Actions, Jenkins to be phased out by Q1 2026
Migration-Plan: "See migration guide: docs/jenkins-to-github-actions.md"

4. Archival

Eventually, decisions become historical:

Status: Archived
Phase: Design
Decision: Use AngularJS for frontend framework
Context: Need dynamic frontend framework for web application
Archived-Date: 2025-12-01
Archived-Reason: AngularJS reached end-of-life, completely replaced by React
Historical-Note: This decision was active from 2020-2024 during the legacy system era

Maintenance Processes

Regular Review Schedule

Establish periodic reviews to keep 4DDRs current:

Frequency	Scope	Actions
Weekly	New 4DDRs	Review proposed decisions, approve/reject
Monthly	Active 4DDRs	Check for outdated decisions, update context
Quarterly	All 4DDRs	Comprehensive review, archival of obsolete decisions
Annually	Archive	Clean up archived decisions, export to long-term storage

Automated Maintenance

Use automation to reduce manual overhead:

Git Hooks

#!/bin/bash
# Pre-commit hook to validate 4DDR format
for file in $(git diff --cached --name-only | grep '\.4ddr\.md$'); do
  if ! validate-4ddr-yaml "$file"; then
    echo "Error: Invalid 4DDR format in $file"
    exit 1
  fi
done

GitHub Actions

name: 4DDR Maintenance
on:
  schedule:
    - cron: '0 9 * * 1'  # Weekly on Monday

jobs:
  review-4ddrs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check for stale 4DDRs
        run: |
          find .gise/4ddr -name "*.md" -exec check-4ddr-freshness {} \;
      - name: Create review issue
        if: ${{ steps.check.outputs.stale_count > 0 }}
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: '4DDR Review Required',
              body: '${{ steps.check.outputs.stale_list }}'
            })

Best Practices

1. Clear Status Transitions

Always include transition metadata:

# When superseding
Superseded-By: 4DDR-0042-new-decision.md
Superseded-Date: 2025-07-30
Superseded-Reason: Requirements changed due to new compliance requirements

# When deprecating  
Deprecated-Date: 2025-07-30
Deprecated-Reason: Technology end-of-life announced
Migration-Plan: Link to migration documentation
Expected-Retirement: 2025-12-31

2. Maintain Decision Chains

Link related decisions to maintain context:

# New decision
Related-Decisions:
  - 4DDR-0015-database-choice.md (supersedes)
  - 4DDR-0023-security-model.md (depends on)
  - 4DDR-0031-deployment-strategy.md (influences)

3. Impact Assessment

Before changing status, assess impact:

Impact-Assessment:
  Code-Changes: "Requires refactoring authentication middleware"
  Team-Training: "Security team needs OAuth 2.0 training"
  Timeline: "2-week implementation, 1-week testing"
  Risk-Level: "Medium - authentication is critical path"

Retention Policies

Short-term (Active Project)

• Proposed/Rejected: Keep for 6 months, then archive
• Accepted: Keep throughout project lifecycle
• Superseded: Keep for 1 year after superseding
• Deprecated: Keep until migration complete + 6 months

Long-term (Post-Project)

• Accepted: Export to knowledge base, keep key decisions
• Archived: Compress and store for compliance/historical reference
• Rejected/Superseded: Purge after 3 years unless compliance required

Compliance Considerations

Some industries require longer retention:

Industry	Requirement	Recommended Retention
Healthcare	HIPAA compliance	7+ years
Financial	SOX, regulatory audit	7+ years
Government	FISMA, compliance audit	10+ years
General	ISO 27001, general audit	3-5 years

Tooling Support

4DDR Management Scripts

# Check 4DDR status
./scripts/4ddr-status.sh

# Supersede a decision
./scripts/4ddr-supersede.sh 0015 0042 "Requirements changed"

# Archive old decisions
./scripts/4ddr-archive.sh --older-than=2years --status=superseded

# Generate lifecycle report
./scripts/4ddr-report.sh --format=html --output=reports/

Database Integration

For teams using database storage:

-- Track decision lifecycle
CREATE TABLE decision_lifecycle (
  decision_id VARCHAR(50),
  old_status VARCHAR(20),
  new_status VARCHAR(20),
  changed_date TIMESTAMP,
  changed_by VARCHAR(100),
  reason TEXT
);

-- Query for maintenance
SELECT decision_id, status, days_since_update
FROM decisions 
WHERE status = 'accepted' 
  AND last_updated < NOW() - INTERVAL '90 days'
ORDER BY last_updated ASC;

Conclusion

Effective 4DDR lifecycle management:

• Maintains decision quality through regular review
• Prevents information decay via automated checks
• Supports compliance through proper retention
• Enables decision analytics through structured transitions
• Reduces maintenance overhead via automation

The key is finding the right balance between thoroughness and pragmatism for your team's context and compliance requirements.