Provenance Manifesto
arrow_back Back to Blog

Article artifact

The Provenance Manifesto

Source: artifacts/provenance-manifesto-meetup-slides.md

Table of contents

expand_more

The Provenance Manifesto

Meetup Slides Draft

Topic: Decision provenance in the age of AI
Format: Initial review draft in Markdown
Audience: Engineering, architecture, product, and AI practitioners

Slide 1

The Provenance Manifesto

Decision provenance in the age of AI

Addressing organizational context amnesia through the art of provenance.

"The history of every decision is the architecture of our future."

Slide 2

The Problem We Normalized

Software organizations are very good at preserving:

  • code
  • tickets
  • deployments
  • infrastructure
  • documents

But they are very bad at preserving:

  • why a decision was made
  • which trade-offs were accepted
  • which assumptions were true at the time
  • which alternatives were rejected
  • who owned the decision

We preserve the result. We lose the reasoning.

Slide 3

A Familiar Scene

Six months into a project, someone asks:

"Why are we doing it this way?"

What usually follows:

  • someone vaguely remembers the original scope
  • someone thinks it was added later
  • somebody opens outdated documentation
  • the people who knew the full story are gone

So the team does what teams always do:

  • they guess
  • they decide again
  • they move on

This is organizational context amnesia.

Slide 4

Why This Matters More Now

For years, this was mostly a delivery problem.

Now it is becoming something bigger.

AI is making the "what" cheaper:

  • code
  • plans
  • architectures
  • solution options
  • documentation drafts

That means the "why" becomes more valuable:

  • intent
  • trade-offs
  • constraints
  • accountability
  • decision ownership

AI accelerates execution. Provenance preserves accountability.

Slide 5

The Core Idea

Decisions should become first-class artifacts.

Not side effects of meetings.
Not fragments buried in chat.
Not guesses reconstructed from old commits.

A decision should carry its provenance:

  • the problem being solved
  • the context and constraints
  • the alternatives considered
  • the reasoning behind the choice
  • the owner of the decision
  • the later evolution of that decision

Decision provenance explains why a system exists in its current form.

Slide 6

What Provenance Is And Is Not

Provenance is not:

  • just another documentation tool
  • just Jira or Confluence
  • just meeting notes
  • just static ADR files
  • just RAG over old documents

Provenance is:

  • a memory layer for decisions
  • a system of record for reasoning
  • a trace from execution back to intent
  • a way to preserve causality, not just text

Documentation describes the system. Provenance explains how and why it became that system.

Slide 7

Through This Work We Have Come To Value

  • Traceable decisions with context over undocumented intuition
  • Institutional memory over repeated rediscovery
  • Transparent reasoning over hidden assumptions
  • Evolution of decisions over static documentation
  • Accountable decision ownership over anonymous outputs
  • Governed collaboration between humans and AI over uncontrolled automation

While there is value in the items on the right, we value the items on the left more.

Slide 8

The Principles

1. Decisions are first-class artifacts

Every architecture, product behavior, operational process, and incident response originates from decisions.

2. Decisions must carry context

A decision without assumptions, alternatives, risks, and reasoning is incomplete.

3. Decisions evolve but are never erased

History matters because organizations learn through the evolution of reasoning.

4. Decisions must be queryable

Teams should be able to ask:
Why was this designed this way?
Which assumptions justified it?
Which risks were accepted?

Slide 9

The Principles, Continued

5. Decisions must be attributable

Meaningful decisions need ownership.

6. AI must operate within decision governance

AI can generate solutions, but reasoning, assumptions, and approvals must remain visible.

7. Institutional memory is a strategic asset

Organizations that preserve reasoning:

  • move faster
  • repeat fewer mistakes
  • onboard better
  • govern AI more safely
  • compound knowledge over time

Memory compounds.

Slide 10

Why This Creates Real Value

Decision provenance helps organizations:

  • reduce rework and repeated rediscovery
  • shorten onboarding time
  • make architectural change safer
  • expose hidden assumptions earlier
  • improve audits, incident reviews, and compliance discussions
  • give AI systems access to the reasoning layer, not just the artifact layer

The shift is simple:

From private memory to institutional memory.

Slide 11

Why AI Changes The Stakes

Without provenance, AI can often explain:

  • what the code does
  • what the docs say
  • what the current system looks like

But it usually cannot reliably explain:

  • why a trade-off was accepted
  • why a workaround exists
  • why one option was rejected
  • why a constraint still matters

Without preserved reasoning, AI can optimize the system while the organization gradually loses the ability to explain itself.

At that point, humans do not lose their jobs first. They lose their authority over the "why."

Slide 12

What A Provenance Layer Captures

A real provenance model can preserve and connect:

  • decisions
  • assumptions
  • risks
  • questions
  • actions
  • evidence
  • ownership
  • affected systems and artifacts
  • superseded or related decisions

Over time, this becomes:

a graph of reasoning that evolves with the system

not a pile of disconnected documents.

Slide 13

How Teams Can Start

You do not need to wait for a perfect platform.

Start by preserving major decisions where AI or complexity already creates risk:

  • architecture trade-offs
  • product and scope decisions
  • operational responses
  • incident-related decisions
  • AI-assisted implementation plans

Practical starting points:

  1. Capture the decision.
  2. Capture its context, assumptions, risks, and alternatives.
  3. Assign ownership.
  4. Keep the history when the decision changes.
  5. Make it queryable later.

The important change is not the format. It is the intent to preserve reasoning.

Slide 14

This Is Not Really About Tools

The hardest change is cultural, not technical.

Provenance is a mindset shift:

  • from hidden context to shared context
  • from undocumented authority to traceable ownership
  • from static artifacts to evolving reasoning
  • from outputs without lineage to accountable decisions

Provenance is not primarily about changing tools. It is about changing how we think about knowledge, decisions, and responsibility.

Slide 15

Closing Thought

The real divide is not:

  • human-written vs AI-generated

The real divide is:

  • opaque outputs vs traceable reasoning

If we cannot reconstruct how a conclusion was formed, then even the most polished output is still just a well-presented guess.

Slide 16

Invitation

The Provenance Manifesto is not a finished product.

It is:

  • a concept
  • a research direction
  • a practical architecture question
  • an invitation to rethink how engineering organizations preserve memory

Questions for discussion

  • Where does your organization lose critical decision context today?
  • Which decisions would be most valuable to preserve?
  • How should AI participate in a governed decision memory?