| name | expression-intent-archaeology |
| description | Create separate documentation that preserves discovered intent from historical investigation so future readers benefit from your research. Use when: (1) completing code archaeology investigation and needing to ensure discoveries benefit future developers facing the same confusion, (2) recurring questions from team members signal that institutional knowledge needs capture in ADRs or documentation files, (3) team member departure would take critical undocumented context about design decisions with them, (4) creating onboarding documentation where critical context exists only in git history or senior engineers' memories |
Intent Archaeology
Preserve discovered context about code intent by documenting what investigations reveal, creating artifacts that outlive the investigation itself.
Instructions
When I uncover why code exists through historical investigation, I don't just build my own understanding. I create documentation that makes that understanding accessible to future readers who will face the same confusion I did.
-
Gather evidence systematically - I use git log to trace when code was introduced and modified, git blame to identify authors and timing of specific lines, and follow references to pull requests and issues where the real discussions happened. This creates a trail from the present confusion back to the moment when intent was clear, though I know commit messages often assume context their authors had but I lack.
-
Distinguish verification levels - I mark findings with their confidence level, distinguishing statements I can verify directly from primary sources like PR discussions or linked issues from inferences I make based on patterns of change, timing, or related modifications. When I find explicit explanations in a PR comment or issue thread, I note that as confirmed intent and include the reference. When I infer intent from the pattern of changes over time, I phrase it as a likely explanation rather than fact.
-
Infer from patterns when direct evidence is absent - When commit messages are sparse or authors are no longer available, I look at what changed together, how frequently modifications occurred, which other parts of the codebase were touched in related commits, and what the timing suggests about urgency or experimentation. A series of rapid commits touching the same area often indicates a production issue being debugged. Changes that consistently modify security-related code alongside feature additions suggest compliance requirements.
-
Choose the right documentation vehicle - For intent that explains specific code decisions, I write inline comments that connect the what-is-visible to the why-it-exists, including references to PRs or issues when they exist. For architectural decisions that shaped multiple files or systems, I create Architecture Decision Records that capture the context, considered alternatives, and rationale with enough detail that future maintainers can evaluate whether constraints still apply. For broader historical context about how a system evolved, I add sections to README files or create dedicated documentation that tells the story of why things are the way they are.
-
Write for the confused future reader - I document not just what I discovered but why I was confused in the first place, because that confusion signals where context has been lost. I explain what assumptions would be natural to make and why the reality differs. I include enough connective tissue that someone reading my documentation understands both the historical decision and how to think about it in their current context.
-
Preserve institutional knowledge actively - When I discover that important context lives only in someone's memory, especially if they're leaving the team, I schedule time to capture their explanations before the knowledge walks out the door. I ask them to walk through the confusing parts while I document their reasoning, then encode that into the appropriate form whether that's code comments, decision records, or documentation files.
Examples
Documenting production incident context
I'm working on a payment processing service where I notice a redundant null check that validates both the transaction object and a specific field within it, even though the type system guarantees the field exists. This defensive duplication puzzles me because the codebase generally trusts type safety. Using git blame, I find the check was added two years ago by an engineer who has since left the company. The commit message says only "add validation" which doesn't explain the redundancy. I locate the PR and read through the discussion where a reviewer asked why this was needed. The author responded with a link to a production incident where a race condition in a different service occasionally sent transactions with the field set to null despite type declarations, causing payment failures during a high-traffic event. The fix was deployed urgently at 2 AM. Rather than leaving future developers to puzzle over this like I did, I add a comment directly above the check explaining that it defends against a specific upstream race condition documented in incident report INC-2847, and that while the type system says this field can't be null, production experience proved otherwise. I include the PR reference so anyone reconsidering this check can read the full context.
Creating an Architecture Decision Record for API versioning
I'm examining an API gateway where the versioning strategy seems inconsistent. Some endpoints version in the URL path, others use headers, and a few use query parameters. My first instinct is to standardize this, but before refactoring I investigate why the inconsistency exists. Git log reveals the API evolved over three years with different teams owning different services. The path-based versioning came first and was the intended standard. Reading through PRs from a year later, I find a discussion where the mobile team needed to version a specific endpoint but couldn't change the path because it was hardcoded in released mobile apps that couldn't be updated. They chose header-based versioning as a pragmatic solution. Six months after that, a third-party integration needed versioning but couldn't send custom headers due to limitations in their system, leading to query parameter versioning. Rather than trying to force consistency by breaking existing integrations, I create an Architecture Decision Record titled "API Versioning Strategy Evolution" that documents how we arrived at three different approaches, explains which constraint drove each decision, and provides guidance on which approach to use for new endpoints. This preserves the institutional knowledge that these aren't mistakes but conscious adaptations to real-world constraints.
Capturing departing engineer's mental model
During my investigation of a complex caching invalidation system, I discover that most of the subtle logic isn't documented anywhere and git history shows it was primarily built by one engineer who is leaving next week. The commit messages are terse and the PRs were rubber-stamped because this engineer was the domain expert everyone trusted. I realize that when they leave, we'll lose critical knowledge about why certain invalidation patterns exist and what edge cases they handle. I schedule an hour with them and walk through each confusing section, asking them to explain the reasoning. They describe how certain entities have bidirectional relationships that create invalidation cascades, why some caches invalidate immediately while others use lazy expiration, and which compromises they made between consistency and performance. As they talk, I draft inline comments and design notes. After our session, I add detailed comments to the caching logic explaining not just what each section does but why that approach was necessary, documenting specific edge cases they discovered through production incidents. I create a README in the caching module that captures their mental model of how the system works and the principles that guided its design. When they leave, their expertise remains encoded in the codebase for future maintainers.
