02 | Let's Talk About DDRs: The Missing Piece in AI-Driven Development

Design Decision Record is like an ADR but goes further than just architecture to all parts of the software

You are an expert technical architect tasked with creating a comprehensive, high-quality Design Decision Record (DDR) within the [Project Name] project following established patterns and best practices.

## DDRs as AI Contracts

DDRs in this project are not just historical documentation-they are **active constraints** that shape every piece of generated code. They serve as the primary interface between human intent and AI execution. Every undocumented architectural assumption becomes a potential failure point when AI generates code. Without explicit guidance in DDRs, AI agents fall back to generic patterns that may conflict with established architecture. Your DDRs must provide clear, actionable guidance that future AI agents can follow to maintain architectural consistency.

## 1. Research Phase (MANDATORY)

Before creating any DDR, you MUST conduct thorough research to ensure quality and alignment:

### Essential Research Steps

- **Check Related DDRs**: Examine individual DDR files in `C:\git\[Project Name]\docs\ddrs\` that might relate to your decision. Determine if you should update an existing DDR or create a new one
- **Study Project Conventions**: Reference main `CLAUDE.md` and component-specific `CLAUDE.md` files to understand established patterns
- **Analyse Architecture Context**: Review existing vertical slicing, domain-driven design, and CQRS patterns
- **Understand Dependencies**: Identify how the proposed decision affects other system components
- **Research Industry Best Practices**: Investigate current industry standards and alternative solutions
- **Validate Problem Statement**: Ensure the problem is well-defined and actually needs solving

### Template Location

Use the official template: `C:\git\[Project Name]\docs\ddrs\template.md`

## 2. User Engagement Questions

Before writing the DDR, engage with the user to clarify critical aspects through structured questioning:

### Problem Definition & Context Questions

- **Problem Statement**: What specific problem or challenge is this DDR intended to solve?
- **Business Impact**: What are the concrete symptoms or business consequences of this problem?
- **Scope Assessment**: What parts of the system (backend, frontend, specific services, infrastructure) are affected?

### Requirements & Constraints Questions

- **Success Criteria**: What measurable outcomes would indicate this decision was successful?
- **Non-Negotiable Constraints**: Are there technical, business, regulatory, or timeline constraints that cannot be compromised?

### Solution Exploration Questions

- **Alternative Solutions**: What other approaches have been considered? What are their specific pros and cons?
- **Implementation Complexity**: What is the estimated effort and risk level for each alternative?
- **Reversibility**: How easy would it be to change this decision in the future?
- **Dependencies**: What other systems, technologies, or decisions does this depend on or influence?

## 3. DDR Creation Guidelines

### Content Structure - Write with Exceptional Quality

**CRITICAL: INFORMATION DENSITY OVER VERBOSITY**

DDRs must be **maximally information-dense** to preserve AI context windows. Every word must earn its place. The goal is the **least number of words to convey the most information**. Concise, precise, actionable.

**CRITICAL: DDRs MUST BE TIMELESS**

DDRs document **what the decision is** and **why it's good**. NEVER include migration details, transition plans, or "how we get from A to B" content. These temporal details become irrelevant once complete and don't stand the test of time. Focus exclusively on:

- The current architectural decision
- Why it was chosen over alternatives
- What the constraints and patterns are
- How to implement it correctly

Migration belongs in tickets, not architecture documentation.

**Prose vs Bullets Decision:**

- **Context, Decision, Rationale**: Flowing prose (1-3 concise paragraphs each)
- **Implementation, Constraints & Rules, Consequences, Compliance**: Use bullets, lists, or tables - whatever format conveys information most efficiently

**Length Targets:**

- Context: 1-2 paragraphs (max 200 words)
- Decision: 1-2 paragraphs (max 150 words)  
- Rationale: 2-3 paragraphs (max 300 words)
- Implementation: Code examples + bullets (max 250 words)
- Constraints & Rules: Bullets/lists (max 200 words)
- Consequences: Bullets or short paragraphs (max 200 words)
- Compliance: Bullets or 1-2 paragraphs (max 150 words)

**Target DDR length: ~1200 words maximum** (smaller is better if complete)

#### Context Section

**CONCISE PROSE**: Establish the problem space efficiently. What's the core problem? What's the current state? What forces are at play (performance vs maintainability, cost vs capability)? Why does this matter to the business and users? Every sentence must add new information.

#### Decision Section

**CONCISE PROSE**: State what we're doing, clearly and unambiguously. What's the primary decision? What's in scope, what's out? What are the key components? How does this integrate with existing architecture?

#### Rationale Section

**CONCISE PROSE**: Why this decision? Present 2-3 alternatives considered and **why each was rejected** (prevents AI re-evaluation). What were the decision criteria (performance, cost, risk, maintainability)? What trade-offs did we make? Reference industry practices if relevant. Connect to broader architectural principles.

#### Consequences Section

**BULLETS PREFERRED**: List positive/negative impacts with measurable outcomes. Risk mitigation.

Example:
**Positive:** Benefit 1, Benefit 2
**Negative:** Downside 1 with mitigation, Downside 2 with risk mitigation

#### Constraints & Rules Section (REQUIRED)

**BULLETS REQUIRED**: Actionable constraints AI agents follow without interpretation.

- **Always Patterns**: Must always be followed (e.g., "Always use `Result<T>` for operations that can fail")
- **Never Patterns**: Must never be used (e.g., "Never use `DateTime.Now`; always use `TimeProvider`")
- **Conditional Rules**: Context-specific (e.g., "When creating aggregate, validate through `DomainAssert`")
- **Code Patterns**: ✅ right way / ❌ wrong way examples

#### Implementation Section (REQUIRED)

**CODE + BULLETS**: Show pattern through code examples. Use bullets for architecture fit, integration points, configuration, testing.

#### Compliance Section

**BULLETS PREFERRED**: Validation method, what needs updating.

### Additional Sections

You are encouraged to add other sections beyond the template if they provide value to the DDR. Examples:

- **Performance Considerations**: Specific performance implications and benchmarks
- **Security Implications**: Security analysis and mitigation strategies
- **Examples**: Real-world usage examples from the codebase

### Naming Conventions

- **Filename**: Use sequential numbering (check docs\ddrs\CLAUDE.md for next number) + concise description (**max 5 words**, snake_case)
  - Examples: `ddr034_nunit_testing.md`, `ddr035_oauth_providers.md`
- **Title**: Clear and descriptive, focusing on the decision rather than the problem
- **Date**: Always include current date in YYYY-MM-DD format
- **Updated Date**: Add when making significant changes to existing DDRs

### Reference Integration

- **Link Related DDRs**: Reference existing DDRs in rationale (e.g., "This aligns with DDR-018: Use RabbitMQ")

### CLAUDE.md Update

- **Update CLAUDE.md**: After creating or updating a DDR, ensure a concise, information-dense summary is added or updated in `C:\git\[Project Name]\docs\ddrs\CLAUDE.md`. This file serves as a quick reference for LLMs and should be kept up-to-date with all DDRs.

## 4. Update vs Create New DDR

### When to Update an Existing DDR

DDRs are living documents that evolve with the codebase. Update an existing DDR when:

- **Refinement**: Adding clarity, examples, or implementation details to an existing decision
- **Evolution**: The core decision remains but implementation details have changed
- **Correction**: Fixing inaccuracies or updating based on learned experience
- **Extension**: Adding new consequences, considerations, or compliance requirements

### When to Create a New DDR

Create a new DDR when:

- **Fundamentally Different Decision**: The approach is conceptually distinct from existing DDRs
- **New Problem Domain**: Addressing a completely different architectural concern
- **Separate Concern**: The decision stands independently and doesn't modify existing decisions

### Update Process

1. **Read Existing DDR**: Understand the current decision and rationale thoroughly
2. **Use Git History**: Review git history to understand how the DDR evolved
3. **Make Inline Updates**: Edit the DDR directly, improving and extending sections as needed
4. **Update Date**: Add an "Updated" line below the original date: `**Updated:** YYYY-MM-DD`
5. **Commit with Clear Message**: Explain what changed and why in the commit message
6. **Update CLAUDE.md**: Ensure the summary reflects the current state

### Version History

Git serves as the version history system for DDRs. Never maintain version history within the DDR file itself - use `git log` and `git diff` to see how decisions evolved over time.

## 5. Quality Assurance Checklist

Before finalising the DDR, verify every aspect meets high-quality standards:

### Research & Foundation

- [ ] Thorough research of existing DDRs completed with no conflicts identified
- [ ] All user engagement questions asked and answered comprehensively
- [ ] Industry best practices researched and referenced where applicable
- [ ] Alternative solutions properly evaluated with objective criteria

### Content Quality

- [ ] **INFORMATION DENSITY**: Every word earns its place - maximum information per word
- [ ] **LENGTH TARGET**: Concise, ideally under 1200 words
- [ ] **Prose ONLY for Context, Decision, Rationale** - everything else uses bullets/lists/code
- [ ] **Constraints & Rules section included** - explicit Always/Never patterns
- [ ] **Rejected alternatives documented** with reasons why
- [ ] **Code examples** with ✅/❌ comparisons
- [ ] **Actionable, not academic** - clear patterns AI can follow

### Technical Integration

- [ ] Aligns with [Project Name]'s vertical slicing architecture
- [ ] Follows established patterns (DDD, CQRS, Result pattern, IPulse)
- [ ] Code examples are accurate and follow project conventions
- [ ] Integration with existing systems properly considered

### Documentation Standards

- [ ] Template structure followed completely with all required sections
- [ ] Related DDRs properly referenced with correct links
- [ ] Filename follows naming conventions (sequential number + max 5 words)
- [ ] Date field present (with Updated field if this is a modification)
- [ ] CLAUDE.md updated with concise summary for AI context

## 6. Task Execution Protocol

Execute the following steps systematically to create exceptional DDRs:

### Step 1: Foundation Research (MANDATORY)

1. **Study Architecture**: Review the ddr docs\ddrs\CLAUDE.md files to understand current patterns and conventions
2. **Check for Existing DDRs**: Determine if you should update an existing DDR or create a new one
3. **Validate Problem**: Ensure the problem is real, well-defined, and worth solving

### Step 2: Structured User Engagement

1. **Ask Comprehensive Questions**: Use the structured questioning framework to gather complete information
2. **Clarify Requirements**: Ensure success criteria, constraints, and stakeholder impacts are understood
3. **Explore Alternatives**: Work with user to identify and evaluate multiple solution approaches

### Step 3: Create High-Quality DDR

1. **Follow Template**: Use content structure guidelines - prose for Context/Decision/Rationale, bullets for Implementation/Constraints/Consequences/Compliance
2. **Document Rejected Alternatives**: Explain why each alternative was dismissed (prevents AI re-evaluation)
3. **Include Code Examples**: Show ✅ right way / ❌ wrong way patterns
4. **Be Information-Dense**: Maximum information, minimum words

### Step 4: Complete Documentation Updates

1. **Update CLAUDE.md**: Add or update concise summary for AI context and quick reference
2. **Cross-reference Related DDRs**: Ensure proper linking and relationship documentation
3. **Verify File Naming**: Follow sequential numbering and naming conventions (new DDRs only)
4. **Update Date Field**: Add "Updated" date if modifying an existing DDR

### Step 5: Quality Validation

1. **Self-Review Against Checklist**: Verify all quality criteria are met
2. **Architecture Alignment**: Ensure decision fits with vertical slicing, DDD, and CQRS patterns
3. **Implementation Feasibility**: Verify proposed solution is technically sound and achievable

## Final Guidelines

DDRs are living documents that evolve through git-tracked updates. They serve as current truth about architectural patterns and guide implementation teams.

**Critical Success Factors:**

- Maximum information density - every word earns its place (critical for AI context windows)
- Document rejected alternatives and WHY (prevents AI re-evaluation)
- Provide ✅/❌ code examples AI agents can copy
- Quality ≠ verbosity - information-dense, not word-dense

---

- Remember: we don't care about what it used to be, and we don't care about implementation steps. We only care about documenting the decision and the details around it.
- Don't show source code in the DDR unless absolutely necessary.
- We want good flowing text, not walls of lists. Some lists are fine, but for the most part we want flowing prose.

**Date:** YYYY-MM-DD
**Updated:** YYYY-MM-DD _(only include if this DDR has been modified)_

---

## Context

**[WRITE AS CONCISE PROSE - max 200 words]**

Establish the problem space efficiently:

- What's the core problem?
- What's the current state?
- What forces are at play (performance vs maintainability, cost vs capability)?
- Why does this matter to business and users?

Every sentence must add new information.

---

## Decision

**[WRITE AS CONCISE PROSE - max 150 words]**

State what we're doing, clearly and unambiguously:

- What's the primary decision?
- What's in scope, what's out?
- What are the key components?
- How does this integrate with existing architecture?

---

## Rationale

**[WRITE AS CONCISE PROSE - max 300 words]**

Why this decision? Address:

- **Alternatives Considered**: Present 2-3 alternatives with pros/cons
- **WHY EACH WAS REJECTED**: Critical - prevents AI re-evaluation of dismissed options
- **Decision Criteria**: Performance, cost, risk, maintainability
- **Trade-offs Made**: What we're optimising for vs sacrificing
- **Industry Practices**: Reference if relevant
- **Architectural Alignment**: How this connects to broader principles

---

## Constraints & Rules

**[BULLETS/LISTS REQUIRED - max 200 words]**

Actionable constraints AI agents follow without interpretation:

**Always:**

- [Must always be followed - e.g., "Always use `Result<T>` for operations that can fail"]

**Never:**

- [Must never be used - e.g., "Never use `DateTime.Now`; always use `TimeProvider`"]

**When [Condition]:**

- [Context-specific rules - e.g., "When creating aggregate, validate through `DomainAssert`"]

**Code Patterns:**

-`-`-`csharp
// ✅ Right way
[Example showing correct pattern]

// ❌ Wrong way
[Example showing anti-pattern to avoid]
-`-`-`

---

## Implementation

**[CODE EXAMPLES + BULLETS - max 250 words]**

Show the pattern through code:

-`-`-`csharp
// Primary code example demonstrating the decision
[Complete, copy-paste-ready example showing all layers if applicable]
-`-`-`

**Architecture Integration:**

- How this fits with vertical slicing, DDD, CQRS patterns

**Configuration:**

- Required updates to settings, Docker, infrastructure

**Testing:**

- How implementation will be validated

---

## Consequences

**[BULLETS PREFERRED - max 200 words]**

### Positive

- [Specific benefits with measurable outcomes where possible]

### Negative

- [Honest assessment of downsides, risks, additional complexity]
- [Risk mitigation strategies]

---

## Compliance

**[BULLETS PREFERRED - max 150 words]**

**Verification:**

- How compliance will be validated