tracing-knowledge-lineages

Understand how ideas evolved over time to find old solutions for new problems and avoid repeating past failures

⭐22stars🔀2forks📁View on GitHub🕐Updated Oct 29, 2025⬇️3downloads

When & Why to Use This Skill

The Tracing Knowledge Lineages skill provides a structured framework for understanding the historical evolution of ideas and technical decisions. By employing 'decision archaeology' and context analysis, it helps teams avoid repeating past failures, rediscover abandoned solutions that may now be viable, and adhere to the principle of Chesterton's Fence before modifying complex systems.

Use Cases

  • Technical Debt Evaluation: Before proposing a rewrite of a complex module, use this skill to trace why the current implementation exists and what specific problems it was designed to solve.
  • Failed Attempt Reassessment: Analyze why a specific technology or pattern failed in the past to determine if modern infrastructure or changed constraints make it a viable candidate today.
  • Architectural Onboarding: Help new team members understand the 'why' behind current best practices by mapping the paradigm shifts and decision records that led to the current state.
  • Revival Detection: Evaluate 'new' industry trends by identifying their historical precedents (e.g., SOA vs. Microservices) to apply lessons learned from previous incarnations.
  • Decision Archaeology: Systematically search through Git history, ADRs (Architecture Decision Records), and old documentation to justify or challenge long-standing technical constraints.
nameTracing Knowledge Lineages
descriptionUnderstand how ideas evolved over time to find old solutions for new problems and avoid repeating past failures
when_to_usewhen questioning "why do we use X", before abandoning approaches, or evaluating "new" ideas that might be revivals
version1.1.0

Tracing Knowledge Lineages

Overview

Ideas have history. Understanding why we arrived at current approaches - and what was tried before - prevents repeating failures and rediscovers abandoned solutions.

Core principle: Before judging current approaches or proposing "new" ones, trace their lineage.

When to Trace Lineages

Trace before:

  • Proposing to replace existing approach (understand why it exists first)
  • Dismissing "old" patterns (they might have been abandoned for wrong reasons)
  • Implementing "new" ideas (they might be revivals worth reconsidering)
  • Declaring something "best practice" (understand its evolution)

Red flags triggering lineage tracing:

  • "This seems overcomplicated" (was it simpler before? why did it grow?)
  • "Why don't we just..." (someone probably tried, what happened?)
  • "This is the modern way" (what did the old way teach us?)
  • "We should switch to X" (what drove us away from X originally?)

Tracing Techniques

Technique 1: Decision Archaeology

Search for when/why current approach was chosen:

  1. Check decision records (common locations: docs/decisions/, docs/adr/, .decisions/, architecture decision records)
  2. Search conversations (skills/collaboration/remembering-conversations)
  3. Git archaeology (git log --all --full-history -- path/to/file)
  4. Ask the person who wrote it (if available)

Document:

## Lineage: [Current Approach]

**When adopted:** [Date/commit]
**Why adopted:** [Original problem it solved]
**What it replaced:** [Previous approach]
**Why replaced:** [What was wrong with old approach]
**Context that drove change:** [External factors, new requirements]

Technique 2: Failed Attempt Analysis

When someone says "we tried X and it didn't work":

Don't assume: X is fundamentally flawed Instead trace:

  1. What was the context? (constraints that no longer apply)
  2. What specifically failed? (the whole approach or one aspect?)
  3. Why did it fail then? (technology limits, team constraints, time pressure)
  4. Has context changed? (new tools, different requirements, more experience)

Document:

## Failed Attempt: [Approach]

**When attempted:** [Timeframe]
**Why attempted:** [Original motivation]
**What failed:** [Specific failure mode]
**Why it failed:** [Root cause, not symptoms]
**Context at time:** [Constraints that existed then]
**Context now:** [What's different today]
**Worth reconsidering?:** [Yes/No + reasoning]

Technique 3: Revival Detection

When evaluating "new" approaches:

  1. Search for historical precedents (was this tried before under different name?)
  2. Identify what's genuinely new (vs. what's rebranded)
  3. Understand why it died (if it's a revival)
  4. Check if resurrection conditions exist (has context changed enough?)

Common revival patterns:

  • Microservices ← Service-Oriented Architecture ← Distributed Objects
  • GraphQL ← SOAP ← RPC
  • Serverless ← CGI scripts ← Cloud functions
  • NoSQL ← Flat files ← Document stores

Ask: "What did we learn from the previous incarnation?"

Technique 4: Paradigm Shift Mapping

When major architectural changes occurred:

Map the transition:

## Paradigm Shift: From [Old] to [New]

**Pre-shift thinking:** [How we thought about problem]
**Catalyst:** [What triggered the shift]
**Post-shift thinking:** [How we think now]
**What was gained:** [New capabilities]
**What was lost:** [Old capabilities sacrificed]
**Lessons preserved:** [What we kept from old paradigm]
**Lessons forgotten:** [What we might need to relearn]

Search Strategies

Where to look for lineage:

  1. Decision records (common locations: docs/decisions/, docs/adr/, .adr/, or search for "ADR", "decision record")
  2. Conversation history (search with skills/collaboration/remembering-conversations)
  3. Git history (git log --grep="keyword", git blame)
  4. Issue/PR discussions (GitHub/GitLab issue history)
  5. Documentation evolution (git log -- docs/)
  6. Team knowledge (ask: "Has anyone tried this before?")

Search patterns:

# Find when approach was introduced
git log --all --grep="introduce.*caching"

# Find what file replaced
git log --diff-filter=D --summary | grep pattern

# Find discussion of abandoned approach
git log --all --grep="remove.*websocket"

Red Flags - You're Ignoring History

  • "Let's just rewrite this" (without understanding why it's complex)
  • "The old way was obviously wrong" (without understanding context)
  • "Nobody uses X anymore" (without checking why it died)
  • Dismissing approaches because they're "old" (age ≠ quality)
  • Adopting approaches because they're "new" (newness ≠ quality)

All of these mean: STOP. Trace the lineage first.

When to Override History

You CAN ignore lineage when:

  1. Context fundamentally changed

    • Technology that didn't exist is now available
    • Constraints that forced decisions no longer apply
    • Team has different capabilities now
  2. We learned critical lessons

    • Industry-wide understanding evolved
    • Past attempt taught us what to avoid
    • Better patterns emerged and were proven
  3. Original reasoning was flawed

    • Based on assumptions later proven wrong
    • Cargo-culting without understanding
    • Fashion-driven, not needs-driven

But document WHY you're overriding: Future you needs to know this was deliberate, not ignorant.

Documentation Format

When proposing changes, include lineage:

## Proposal: Switch from [Old] to [New]

### Current Approach Lineage
- **Adopted:** [When/why]
- **Replaced:** [What it replaced]
- **Worked because:** [Its strengths]
- **Struggling because:** [Current problems]

### Previous Attempts at [New]
- **Attempted:** [When, if ever]
- **Failed because:** [Why it didn't work then]
- **Context change:** [What's different now]

### Decision
[Proceed/Defer/Abandon] because [reasoning with historical context]

Examples

Good Lineage Tracing

"We used XML before JSON. XML died because verbosity hurt developer experience. But XML namespaces solved a real problem. If we hit namespace conflicts in JSON, we should study how XML solved it, not reinvent."

Bad Lineage Ignorance

"REST is old, let's use GraphQL." (Ignores: Why did REST win over SOAP? What problems does it solve well? Are those problems gone?)

Revival with Context

"We tried client-side routing in 2010, abandoned it due to poor browser support. Now that support is universal and we have better tools, worth reconsidering with lessons learned."

Remember

  • Current approaches exist for reasons (trace those reasons)
  • Past failures might work now (context changes)
  • "New" approaches might be revivals (check for precedents)
  • Evolution teaches (study the transitions)
  • Ignorance of history = doomed to repeat it