Workflow - Change Existing Architecture and Deprecate Safely

Use this when architecture already exists and you need to introduce a new dynamic while preserving history and traceability.

5-Minute Path

1. Open a focused investigation for the change.
2. Decide migration approach in new ADR(s).
3. Update architecture note(s) to target state.
4. Deprecate/supersede old notes instead of deleting.
5. Update TOGAF/workpackages to reflect replacement path.

Detailed Steps

1) Scope the Change

• Create topic-change-scope-investigation.md describing what changes and why current state is insufficient.
• Link affected architecture notes, ADRs, and principles.

2) Decide Transition

• Create new ADR(s) for replacement strategy and migration sequencing.
• If old ADR is replaced, set old ADR to superseded and link successor.

3) Evolve Architecture

• If change is incremental, update existing architecture note.
• If change is structural, create successor architecture note and archive predecessor.

4) Update Delivery and TOGAF Lenses

• Workpackages: add migration dependencies and acceptance criteria.
• TOGAF: deprecate replaced ABB/SBB mappings and link replacement chain.

5) Close the Loop

• Set investigation status: closed once migration path is clear.
• Update domain/index pages so navigation points to the new canonical path.

Deprecation Rules of Thumb

• Do not delete validated notes.
• Mark status and link the successor (superseded_by where supported).
• Keep old notes discoverable for audit and historical context.