Architectural Archaeology Process

Guide on how to use architectural archaeology to uncover implicit architectural decisions in my projects.

A systematic approach to uncover and document implicit architectural decisions.

Instructions for AI

1. Identify Target Area

   • Examine current implementation details
   • Note any non-obvious technical choices
   • List patterns that seem intentional but lack documentation

2. Question Chain Analysis For each identified element:

   • Why was this specific approach chosen?
   • What problem was being solved?
   • What alternatives were available at the time?
   • What constraints influenced this choice?
   • What trade-offs were accepted?

3. Evidence Collection

   • Search commit history for relevant changes
   • Review related documentation/comments
   • Identify dependencies and their versions at time of decision
   • Note any patterns in surrounding code

4. Alternative Analysis

   • List other approaches that could have been taken
   • Research common solutions for similar problems
   • Consider technology landscape at time of decision
   • Document why alternatives might have been rejected

5. Context Reconstruction

   • Map out the technical ecosystem at time of decision
   • Consider project constraints and requirements then
   • Note relevant team knowledge/preferences
   • Document industry trends of that period

6. Decision Documentation Create ADR in format:

   # NNNN. Option1 vs Option2
   
   Date: [Archaeological Discovery Date]
   Original Implementation: [Estimated Date]
   Status: Discovered
   Discovery Context: Architectural Archaeology
   
   ## Historical Context
   
   [Reconstructed context from investigation]
   
   ## Decision
   
   [Documented actual implementation]
   
   ## Alternatives Considered
   
   [Reconstructed alternatives]
   
   ## Consequences
   
   [Observed long-term impacts]
   
   ## Archaeological Notes
   
   [Document evidence and reasoning process]

7. Validation

   • Cross-reference findings with team knowledge
   • Verify timeline consistency
   • Check if reconstruction explains current state
   • Note confidence level in conclusions

Remember: Focus on understanding "why" over "what". The goal is reconstructing decision context, not just documenting current state.