Skip to content

README.md

Latest commit

 

History

History
107 lines (66 loc) · 2.91 KB

README.md

File metadata and controls

107 lines (66 loc) · 2.91 KB

Architecture Deviations

Part of Architecture Evolution - the pragmatic lens for documenting intentional divergence from ADR intent.

This directory tracks architecture deviations - places where actual implementation intentionally differs from what an ADR describes. These are known, accepted trade-offs, not bugs.

Role in Architecture Evolution

Lens This Directory
Characteristics (Proactive) "What we need" - see ADRs
Gaps (Reactive) "What we learned" - see gaps/
Deviations (Pragmatic) You are here - "What we accepted"

A deviation:

  • Documents why a Characteristic is marked as not planned
  • May originate from a Gap we decided to accept
  • Requires a migration plan for eventual resolution

When to Create a Deviation

Create a deviation document when:

  • Implementation takes a different approach than ADR described
  • PoC simplification that will need future work
  • Architectural compromise due to time/resource constraints
  • Intentional scope reduction with documented rationale

Don't create a deviation for: bugs (use issues), unfinished features (use roadmap), or design limitations not yet decided (use gaps).

Template

# Deviation XXX: [Title]

## Summary

[1-2 sentences describing the divergence]

## Related ADR

- **ADR**: [ADR-NNN](../NNN-title.md)
- **Section**: [Which part of the ADR this deviates from]

## ADR States

> [Quote the relevant section from the ADR]

## Current Implementation

[Describe what was actually built and why]

## Signal Impact

Which signals are affected (metrics, traces, logs)? Does the deviation apply to all three or just one?

## Impact

| Aspect | ADR Target | Current Reality |
|--------|------------|-----------------|
| ... | ... | ... |

## Why This Exists

[Explain the trade-off decision]

## Priority Assessment

[When should this be resolved? Is it acceptable for PoC/MVP/Production?]

## Work Required to Match ADR

| Change | Difficulty | Description |
|--------|------------|-------------|
| ... | ... | ... |

## Recommendation

[Accept for now? Fix before X milestone?]

## References

- [Related Gap](../gaps/NNN-*.md) (if applicable)

## Date

YYYY-MM-DD

Naming Convention

Deviation files use sequential numbering: 001-short-description.md

Index

Deviation Title Related ADR Priority
001 Dual Parquet merge engines during streaming-engine rollout ADR-003 Accept until post-soak

Lifecycle

Identified → Documented → Accepted → (Eventually) Resolved
                              ↓
                        Permanent (rare)

Unlike gaps which may become ADRs, deviations are typically resolved by updating the implementation to match the ADR, or by updating the ADR to match reality.